hyperguild/ingestion/internal/brainfs/brainfstest/brainfstest.go

// Package brainfstest is the shared harness for hyperguild#157's swap-race
// tests: it keeps swapping a regular note, a symlink to a sentinel target file
// (outside the brain, or inside it for hyperguild#171), or a FIFO (with a
// writer held open) into a path while a reader under test loops.
// It observes two things, over a sampled window only: no sentinel byte from
// the target reaches the reader's output, and the reader returns within a
// timeout. It does not cover
// hard links, other paths into the reader, or races it does not generate.
package brainfstest

import (
	"fmt"
	"os"
	"path/filepath"
	"strings"
	"sync"
	"sync/atomic"
	"syscall"
	"testing"
	"time"
)

// Sentinel marks the target file's contents.
const Sentinel = "zqbrainfssentinelonefiftyseven"

// outsideContent carries Sentinel in every field a reader might extract: the
// frontmatter title and aliases, a heading, a wikilink and the body.
const outsideContent = "---\ntitle: " + Sentinel + "\naliases:\n  - " + Sentinel + "\n---\n# " + Sentinel +
	"\n\n" + Sentinel + " [[" + Sentinel + "]]\n"

// Outside writes a file outside any brain dir containing Sentinel.
func Outside(t *testing.T) string {
	t.Helper()
	p := filepath.Join(t.TempDir(), "secret.md")
	if err := os.WriteFile(p, []byte(outsideContent), 0o644); err != nil {
		t.Fatal(err)
	}
	return p
}

var swapSeq atomic.Int64

// StartSwap renames, in a loop, a regular note (content inside) and either
// a symlink to outside or a FIFO into path, until the test ends. FIFOs get a
// writer held open until the swapper exits, so a reader that skips the
// handle check parks forever instead of reading EOF. The swapper is stopped
// and awaited before t.TempDir cleanup.
func StartSwap(t *testing.T, path, inside, outside string, fifo bool) {
	t.Helper()
	var stop atomic.Bool
	var wg sync.WaitGroup
	wg.Add(1)
	go func() {
		defer wg.Done()
		// A name of its own: swappers on one path share a test, and one
		// opening another's FIFO for write would block forever.
		tmp := fmt.Sprintf("%s.swap%d", path, swapSeq.Add(1))
		// A relative link: os.Root refuses every absolute link on its own, so
		// an absolute in-brain target would test nothing.
		link := outside
		if rel, err := filepath.Rel(filepath.Dir(path), outside); err == nil {
			link = rel
		}
		var writers []*os.File
		defer func() {
			for _, w := range writers {
				_ = w.Close()
			}
		}()
		for i := 0; !stop.Load(); i++ {
			_ = os.Remove(tmp)
			switch {
			case i%2 == 0:
				_ = os.WriteFile(tmp, []byte(inside), 0o644)
			case fifo:
				if err := syscall.Mkfifo(tmp, 0o644); err == nil {
					if w, err := os.OpenFile(tmp, os.O_RDWR, 0); err == nil {
						writers = append(writers, w)
					}
				}
			default:
				_ = os.Symlink(link, tmp)
			}
			_ = os.Rename(tmp, path)
		}
	}()
	t.Cleanup(func() { stop.Store(true); wg.Wait() })
}

// WriteSentinelAt writes a file carrying Sentinel at p (creating its
// directory), for an in-brain symlink target.
func WriteSentinelAt(t *testing.T, p string) string {
	t.Helper()
	if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
		t.Fatal(err)
	}
	if err := os.WriteFile(p, []byte(outsideContent), 0o644); err != nil {
		t.Fatal(err)
	}
	return p
}

// AssertNoLeak loops read for d while a symlink swapper runs on path, and
// fails if any output contains Sentinel. The symlink points outside the
// brain; os.Root refuses that on its own, so pair it with AssertNoLeakFrom
// and an in-brain target.
func AssertNoLeak(t *testing.T, path, inside string, d time.Duration, read func() string) {
	t.Helper()
	AssertNoLeakFrom(t, path, inside, Outside(t), d, read)
}

// AssertNoLeakFrom is AssertNoLeak with the symlink pointing at target, e.g.
// a file elsewhere in the brain written with WriteSentinelAt.
func AssertNoLeakFrom(t *testing.T, path, inside, target string, d time.Duration, read func() string) {
	t.Helper()
	StartSwap(t, path, inside, target, false)
	leaks, iters := 0, 0
	for deadline := time.Now().Add(d); time.Now().Before(deadline); iters++ {
		leaks += strings.Count(read(), Sentinel)
	}
	if leaks > 0 {
		t.Fatalf("symlink target %s leaked %d times in %d iterations", target, leaks, iters)
	}
}

// AssertNoHang loops read for d while a FIFO swapper (held writers) runs on
// path, and fails if a read does not return within timeout.
func AssertNoHang(t *testing.T, path, inside string, d, timeout time.Duration, read func()) {
	t.Helper()
	StartSwap(t, path, inside, Outside(t), true)
	done := make(chan struct{})
	go func() {
		for deadline := time.Now().Add(d); time.Now().Before(deadline); {
			read()
		}
		close(done)
	}()
	select {
	case <-done:
	case <-time.After(timeout):
		t.Fatal("reader hung on a swapped-in FIFO with a writer held open")
	}
}