threadtest

Documentation

Overview

Package threadtest is the shared conformance table for thread.Storage backends — the executable form of ADR 0011 §5's promises. Every backend runs it before it may call itself a backend (the store's storetest precedent: LangGraph ships one table for its savers and got five backends out of it); Run takes a factory so each subtest gets fresh storage.

Index

• Constants
• func CrashMatrix(t *testing.T, helperTest string, pathFor func(point string) string, ...)
• func CrashTurn(t *testing.T, helperTest, storagePath string, ...)
• func Run(t *testing.T, open func(t *testing.T) thread.Storage)
• func RunCrashMatrixChild(t *testing.T, open func() (thread.Storage, error))
• func RunCrashTurnChild(t *testing.T, open func() (thread.Storage, error))
• func RunWatch(t *testing.T, open func(t *testing.T) thread.Storage)
• type RawInjector

Constants

const (
	CrashMatrixTurnID  = "s_mx_turn"  // prompt and turn_end
	CrashMatrixParkID  = "s_mx_park"  // approval, decision, compaction, resume_arm, decide_signed
	CrashMatrixSteerID = "s_mx_steer" // steer and clear_queue
	CrashMatrixPoolID  = "s_mx_pool"  // pool_receipt
	CrashMatrixForkID  = "s_mx_fork"  // fork (the forked session's own id)
)

The four sessions the child creates, one per family of write points; the parent asserts over each by id.

const CrashSession = "s_crashturn"

CrashSession is the session id the child creates.

Functions

func CrashMatrix

func CrashMatrix(t *testing.T, helperTest string, pathFor func(point string) string, open func(path string) (thread.Storage, error))

CrashMatrix runs the parent side over every write point: for each, it re-executes the test binary at helperTest (the backend's child, gated on the crash env) with the point set and its own fresh storage location (pathFor — the points must not share sessions), waits out the child, and asserts the point's invariant through reopen — a fresh Storage over the same location, the shape of the next process after the crash. open is the backend's constructor over a location.

func CrashTurn

func CrashTurn(t *testing.T, helperTest, storagePath string, reopen func() (thread.Storage, error))

CrashTurn runs the parent side: it re-executes the test binary at helperTest (the backend's child test, gated on the crash env), waits for the child's "step0done" marker, SIGKILLs it mid-second-step, and asserts the crash's durability through reopen — a fresh Storage over the same location. storagePath is passed to the child through WEFT_THREADTEST_CRASH_STORAGE.

func Run

func Run(t *testing.T, open func(t *testing.T) thread.Storage)

Run executes the conformance table against a backend. open returns fresh storage for each subtest; the table never shares state between them. The corruption rows — unknown kind, newer "v", malformed and torn lines — need a backend that can hold undecodable data, so they run only when the storage also implements RawInjector and skip otherwise: Memory holds the raw bytes (it implements the hook), and a backend that cannot hold them at all pins its loudness where its format lives.

func RunCrashMatrixChild

func RunCrashMatrixChild(t *testing.T, open func() (thread.Storage, error))

RunCrashMatrixChild is the child side, called from the backend's re-executed helper test: it opens its storage through open and dies at the point the env names. It returns only when the env gate is unset (the parent's own run).

func RunCrashTurnChild

func RunCrashTurnChild(t *testing.T, open func() (thread.Storage, error))

RunCrashTurnChild is the child side, called from the backend's re-executed helper test: it opens its storage through open (the WEFT_THREADTEST_CRASH_STORAGE location), runs the turn, prints the step0done marker once the first step is fully emitted, and blocks in the second model call until the parent kills it. It returns only when the env gate is unset (the parent's own run).

func RunWatch

func RunWatch(t *testing.T, open func(t *testing.T) thread.Storage)

RunWatch runs the Watch capability's conformance table against a backend that implements thread.Watcher (the optional interface, ADR 0011 §5): the whole session yields in arrival order, after names the resume point, entries appended while watching arrive exactly once, a canceled context ends the stream, and the loud failures (unknown session, an after the tree does not hold) are errors before the first yield.

Types

type RawInjector

type RawInjector interface {
	Inject(ctx context.Context, session string, data []byte) error
}

RawInjector is the optional hook a durable backend implements so the table can exercise the loud rows the Storage interface itself cannot express: it appends raw bytes to a session's stored data, verbatim — the way a crashed or newer writer would have left them. The test controls the bytes exactly, torn tails included (no trailing newline).