durabletest

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 5, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package durabletest holds runner-independent conformance cases and benchmark workloads for durable.Storage implementations.

Index

Constants

This section is empty.

Variables

View Source
var STORAGE_MEMORY_SCALES = []StorageBenchmarkScale{
	{Name: "1k", EntryCount: 1_000, TaskCount: 200, DocumentCount: 200},
	{Name: "10k", EntryCount: 10_000, TaskCount: 2_000, DocumentCount: 2_000},
}

STORAGE_MEMORY_SCALES are the dataset sizes used for memory measurements.

View Source
var STORAGE_READ_BENCHMARKS = storageReadBenchmarks()

STORAGE_READ_BENCHMARKS are the read measurements run against every backend.

View Source
var STORAGE_WRITE_BENCHMARKS = []StorageWriteBenchmark{
	{
		Name:     "commit one entry",
		Expected: 1,
		Run: func(ctx context.Context, storage durable.Storage) (int64, error) {
			id, err := mintAs[durable.EntryId](storage)
			if err != nil {
				return 0, err
			}
			_, err = CommitWrites(ctx, storage, []durable.StorageWrite{durable.EntryWrite{Value: durable.EntryRecord{
				Id: id, ConversationId: durable.ROOT_CONVERSATION_ID, Kind: "benchmark.write",
				Data: map[string]any{"text": strings.Repeat("x", 128)},
			}}})
			return 1, err
		},
	},
	{
		Name:     "commit 100 entries",
		Expected: 100,
		Run: func(ctx context.Context, storage durable.Storage) (int64, error) {
			writes := make([]durable.StorageWrite, 0, 100)
			for index := range 100 {
				id, err := mintAs[durable.EntryId](storage)
				if err != nil {
					return 0, err
				}
				writes = append(writes, durable.EntryWrite{Value: durable.EntryRecord{
					Id: id, ConversationId: durable.ROOT_CONVERSATION_ID, Kind: "benchmark.write",
					Data: map[string]any{"index": index, "text": strings.Repeat("x", 128)},
				}})
			}
			_, err := CommitWrites(ctx, storage, writes)
			return int64(len(writes)), err
		},
	},
	{
		Name:     "commit mixed entry/task/submission/document",
		Expected: 4,
		Run: func(ctx context.Context, storage durable.Storage) (int64, error) {
			entryId, err := mintAs[durable.EntryId](storage)
			if err != nil {
				return 0, err
			}
			taskId, err := mintAs[durable.TaskId](storage)
			if err != nil {
				return 0, err
			}
			submissionId, err := mintAs[durable.SubmissionId](storage)
			if err != nil {
				return 0, err
			}
			documentId, err := mintAs[durable.DocumentId](storage)
			if err != nil {
				return 0, err
			}
			requestId := fmt.Sprintf("benchmark-%d", submissionId)
			key := strconv.FormatInt(int64(documentId), 10)
			writes := []durable.StorageWrite{
				durable.EntryWrite{Value: durable.EntryRecord{Id: entryId, ConversationId: durable.ROOT_CONVERSATION_ID, Kind: "benchmark.mixed"}},
				durable.TaskWrite{Value: benchmarkTask(taskId, int(taskId))},
				durable.SubmissionWrite{Value: durable.SubmissionRecord{
					Id: submissionId, ConversationId: durable.ROOT_CONVERSATION_ID, RequestId: &requestId,
					Type: durable.SubmissionTypeWrite, Status: durable.SubmissionDone, Entry: &entryId,
				}},
				durable.DocumentCreateWrite{
					Record:  durable.DocumentCreate{Id: documentId, Kind: "benchmark.mixed", Key: &key, Scope: durable.DocumentRecordScope{Kind: durable.ScopeSession}},
					Content: durable.DocumentContent{Kind: durable.ContentBase, Version: 1, Value: chorddelta.JsonObjectOf("entryId", entryId, "taskId", taskId)},
				},
			}
			_, err = CommitWrites(ctx, storage, writes)
			return int64(len(writes)), err
		},
	},
}

STORAGE_WRITE_BENCHMARKS are the write measurements run against every backend.

View Source
var TIMING_SCALE = StorageBenchmarkScale{Name: "timing", EntryCount: 1_000, TaskCount: 300, DocumentCount: 300}

TIMING_SCALE is the dataset size used for timing measurements.

Functions

func CheckRecordCarriers

func CheckRecordCarriers(storage durable.Storage) error

CheckRecordCarriers writes a task with a stored trace carrier and creation-time links, and a submission with a stored trace carrier (Pi 2ec55d80 packages/durable/src/types.ts: TaskRecord.trace/links, SubmissionRecord.trace), and reads them back through storage. The carriers are opaque and the records persist them as plain JSON members, so a record without them reads back without them.

func CheckRecordKeyOrder

func CheckRecordKeyOrder(storage durable.Storage) error

CheckRecordKeyOrder writes records whose dynamic members (entry data, task input and checkpoint, submission detail) hold objects with keys out of alphabetical order, then reads them back through storage. Pi decodes stored records with JSON.parse, so each object keeps its key order; a Go map would list the keys sorted.

func CommitWrites

func CommitWrites(ctx context.Context, storage durable.Storage, writes []durable.StorageWrite) (durable.Seq, error)

CommitWrites commits writes as one batch through Storage.Commit and returns its seq. It returns the refusal as the error if the storage refused the batch.

func Describe

func Describe(value any) string

Describe renders value as JSON for failure messages.

func MatchObject

func MatchObject(actual, expected any) bool

MatchObject reports whether actual contains expected: objects match recursively on expected's keys, arrays match element-wise with equal length, and scalars match exactly.

func Normalize

func Normalize(value any) any

Normalize returns the JSON form of value with JavaScript string semantics: nil, bool, float64, string, []any, or map[string]any. A value without a JSON form is returned unchanged.

func RegisterEnvConformance

func RegisterEnvConformance(t *testing.T, name string, withEnv EnvConformanceProvider, options EnvConformanceRegisterOptions)

RegisterEnvConformance runs every environment conformance case as a subtest of a test named name (runner-independent cases registered with the Go test runner, testing/runner.ts:28).

func RegisterStorageConformance

func RegisterStorageConformance(t *testing.T, name string, withStorage StorageConformanceProvider)

RegisterStorageConformance runs every conformance case as a subtest of a test named name.

func SeedStorageWriteBenchmark

func SeedStorageWriteBenchmark(ctx context.Context, storage durable.Storage) error

SeedStorageWriteBenchmark seeds the common state expected by every write benchmark sample.

func StorageBenchmarkPrimaryRecordCount

func StorageBenchmarkPrimaryRecordCount(scale StorageBenchmarkScale) int

StorageBenchmarkPrimaryRecordCount is the number of primary records that SeedStorageBenchmark creates at scale.

Types

type EnvConformanceAssertions

type EnvConformanceAssertions = StorageConformanceAssertions

EnvConformanceAssertions are the checks an environment conformance case makes.

type EnvConformanceCase

type EnvConformanceCase struct {
	Name string
	// Timeout is how long a case that waits for an environment's watch latency needs; zero uses the runner's default.
	Timeout time.Duration
	Run     func() error
}

EnvConformanceCase is one named environment conformance case.

func CreateEnvConformance

func CreateEnvConformance(options EnvConformanceOptions) []EnvConformanceCase

CreateEnvConformance creates runner-independent cases for an ExecutionEnv. WithEnv must call its callback exactly once per case.

type EnvConformanceOptions

type EnvConformanceOptions struct {
	Assertions EnvConformanceAssertions
	WithEnv    EnvConformanceProvider
	// Shell is the program and flag that run a POSIX shell script from the next argument; default {"sh", "-c"}.
	Shell []string
	// Symlinks is false when the shell's `ln -s` does not create symbolic links; nil means true (env-conformance.ts symlinks, default true).
	Symlinks *bool
	// ListFiles is whether the environment implements the optional env.FileLister, which the suite then checks; default false.
	ListFiles bool
}

EnvConformanceOptions configures CreateEnvConformance.

type EnvConformanceProvider

type EnvConformanceProvider func(use func(executionEnv env.ExecutionEnv) error) error

EnvConformanceProvider supplies an environment whose Cwd is a fresh, empty, writable directory, calls use once with it, and then cleans up. It returns use's error.

type EnvConformanceRegisterOptions

type EnvConformanceRegisterOptions struct {
	// Shell is the program and flag that run a POSIX shell script from the next argument; default {"sh", "-c"}.
	Shell []string
	// Symlinks is false when the shell's `ln -s` does not create symbolic links; nil means true.
	Symlinks *bool
	// ListFiles is whether the environment implements the optional env.FileLister, which the suite then checks; default false.
	ListFiles bool
}

EnvConformanceRegisterOptions is Pick<EnvConformanceOptions, "shell" | "symlinks" | "listFiles">, the options of RegisterEnvConformance.

type StorageBenchmarkDataset

type StorageBenchmarkDataset struct {
	FirstEntryId          durable.EntryId
	FilteredTaskCount     int
	ExactDocumentId       durable.DocumentId
	ExactDocumentKey      string
	ReplayDocumentIds     map[int]durable.DocumentId
	HistoricalDocumentId  durable.DocumentId
	AncientAt             durable.Seq
	RecentAt              durable.Seq
	DeepestConversationId durable.ConversationId
	AncestorHeadEntryId   durable.EntryId
}

StorageBenchmarkDataset identifies the seeded records that read benchmarks address.

func SeedStorageBenchmark

func SeedStorageBenchmark(ctx context.Context, storage durable.Storage, scale StorageBenchmarkScale) (StorageBenchmarkDataset, error)

SeedStorageBenchmark seeds deterministic representative data through only the public Storage contract.

type StorageBenchmarkScale

type StorageBenchmarkScale struct {
	Name          string
	EntryCount    int
	TaskCount     int
	DocumentCount int
}

StorageBenchmarkScale is the size of a seeded benchmark dataset.

type StorageConformanceAssertions

type StorageConformanceAssertions interface {
	// Ok asserts that value is truthy as JavaScript defines it; message is optional.
	Ok(value any, message ...string)
	StrictEqual(actual, expected any)
	DeepEqual(actual, expected any)
	PartialDeepEqual(actual, expected any)
	GreaterThan(actual, expected float64)
	// Rejects checks that a call failed with an error whose message includes messageIncludes.
	Rejects(err error, messageIncludes string)
}

StorageConformanceAssertions are the checks a conformance case makes. A failing check ends the case.

Values compare by their JSON form, as upstream's Vitest matchers compare plain data: absent optional fields equal missing ones, and every Go number type compares by value.

func CreateTestingAssertions

func CreateTestingAssertions(tb testing.TB) StorageConformanceAssertions

CreateTestingAssertions adapts a Go test to StorageConformanceAssertions; a failure stops the test.

type StorageConformanceCase

type StorageConformanceCase struct {
	Name string
	Run  func() error
}

StorageConformanceCase is one named conformance case.

func CreateStorageConformance

func CreateStorageConformance(options StorageConformanceOptions) []StorageConformanceCase

CreateStorageConformance creates runner-independent cases. WithStorage must call its callback exactly once per case.

type StorageConformanceOptions

type StorageConformanceOptions struct {
	Assertions  StorageConformanceAssertions
	WithStorage StorageConformanceProvider
}

StorageConformanceOptions configures CreateStorageConformance.

type StorageConformanceProvider

type StorageConformanceProvider func(use func(storage durable.Storage) error) error

StorageConformanceProvider supplies fresh storage to use and returns use's error. It must call use exactly once.

type StorageReadBenchmark

type StorageReadBenchmark struct {
	Name     string
	Run      func(ctx context.Context, storage durable.Storage, dataset StorageBenchmarkDataset) (int64, error)
	Expected func(dataset StorageBenchmarkDataset) int64
}

StorageReadBenchmark is one read measurement and the value it must return for a seeded dataset.

type StorageWriteBenchmark

type StorageWriteBenchmark struct {
	Name     string
	Expected int64
	Run      func(ctx context.Context, storage durable.Storage) (int64, error)
}

StorageWriteBenchmark is one write measurement and the count it must return.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL