Documentation
¶
Overview ¶
Package durabletest holds runner-independent conformance cases and benchmark workloads for durable.Storage implementations.
Index ¶
- Variables
- func CheckRecordCarriers(storage durable.Storage) error
- func CheckRecordKeyOrder(storage durable.Storage) error
- func Describe(value any) string
- func MatchObject(actual, expected any) bool
- func Normalize(value any) any
- func RegisterEnvConformance(t *testing.T, name string, withEnv EnvConformanceProvider, ...)
- func RegisterStorageConformance(t *testing.T, name string, withStorage StorageConformanceProvider)
- func SeedStorageWriteBenchmark(ctx context.Context, storage durable.Storage) error
- func StorageBenchmarkPrimaryRecordCount(scale StorageBenchmarkScale) int
- type EnvConformanceAssertions
- type EnvConformanceCase
- type EnvConformanceOptions
- type EnvConformanceProvider
- type EnvConformanceRegisterOptions
- type StorageBenchmarkDataset
- type StorageBenchmarkScale
- type StorageConformanceAssertions
- type StorageConformanceCase
- type StorageConformanceOptions
- type StorageConformanceProvider
- type StorageReadBenchmark
- type StorageWriteBenchmark
Constants ¶
This section is empty.
Variables ¶
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.
var STORAGE_READ_BENCHMARKS = storageReadBenchmarks()
STORAGE_READ_BENCHMARKS are the read measurements run against every backend.
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 = storage.Commit(ctx, []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)}, }}}, adopt) 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 := storage.Commit(ctx, writes, adopt) 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 = storage.Commit(ctx, writes, adopt) return int64(len(writes)), err }, }, }
STORAGE_WRITE_BENCHMARKS are the write measurements run against every backend.
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 ¶
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 ¶
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 MatchObject ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.