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.TB) 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. It returns the number of symlinks
// or FIFOs actually renamed into path so far, so a caller can tell a race
// that ran from one whose every swap failed (hyperguild#177).
func StartSwap(t testing.TB, path, inside, outside string, fifo bool) *atomic.Int64 {
	t.Helper()
	var swaps atomic.Int64
	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)
			var made error
			switch {
			case i%2 == 0:
				_ = os.WriteFile(tmp, []byte(inside), 0o644)
			case fifo:
				if made = syscall.Mkfifo(tmp, 0o644); made == nil {
					if w, err := os.OpenFile(tmp, os.O_RDWR, 0); err == nil {
						writers = append(writers, w)
					}
				}
			default:
				made = os.Symlink(link, tmp)
			}
			if err := os.Rename(tmp, path); err == nil && made == nil && i%2 == 1 {
				swaps.Add(1)
			}
		}
	}()
	t.Cleanup(func() { stop.Store(true); wg.Wait() })
	return &swaps
}

// 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)
}

// InsideMarker must appear in the inside note's content and in read's
// output whenever read saw that note: the floor below counts such reads.
const InsideMarker = "inside"

// AssertNoLeakFrom is AssertNoLeak with the symlink pointing at target, e.g.
// a file elsewhere in the brain written with WriteSentinelAt.
//
// Beyond "no Sentinel in any output" it sets two floors, because without
// them the assertion passes when nothing was tested (hyperguild#177): at
// least one symlink must have been swapped into path, and at least one read
// must have returned InsideMarker (a reader that always errors returns
// nothing, and so never leaks).
func AssertNoLeakFrom(t testing.TB, path, inside, target string, d time.Duration, read func() string) {
	t.Helper()
	if !strings.Contains(inside, InsideMarker) {
		t.Fatalf("inside content must contain %q", InsideMarker)
	}
	swaps := StartSwap(t, path, inside, target, false)
	leaks, iters, insideReads := 0, 0, 0
	for deadline := time.Now().Add(d); time.Now().Before(deadline); iters++ {
		out := read()
		leaks += strings.Count(out, Sentinel)
		if strings.Contains(out, InsideMarker) {
			insideReads++
		}
	}
	if leaks > 0 {
		t.Fatalf("symlink target %s leaked %d times in %d iterations", target, leaks, iters)
	}
	if n := swaps.Load(); n == 0 {
		t.Fatalf("no symlink was swapped into %s in %d iterations: the race did not run", path, iters)
	}
	if insideReads == 0 {
		t.Fatalf("no read in %d iterations returned the inside note (%q): the reader read nothing", iters, InsideMarker)
	}
}

// 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")
	}
}