enginetest

package
v0.30.0 Latest Latest
Warning

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

Go to latest
Published: Oct 31, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package enginetest holds the shared kill-and-resume suite: a real *engine.Engine, driven through a real object-store backend, killed, and resumed on a clean filesystem.

Why this is a second suite and not part of objectstoretest

objectstoretest answers "is this a conformant Backend?" from the outside, with nothing but the interface. This one answers the question the effort actually exists for -- "does a session survive the death of the process that produced it?" -- and it can only be answered by booting the engine, so this package imports pkg/engine.

That import is why it is a package of its own rather than more files in objectstoretest. pkg/engine's own tests are `package engine` (internal) and import objectstoretest for its Memory backend; if objectstoretest imported pkg/engine back, that test binary would not build. Keeping the engine-importing half in a sibling package keeps both directions legal.

Why it is exported at all

The same reason objectstoretest is. A backend may live in a module this repository never sees, and "it passed the interface conformance suite" does not mean a session resumes from it: the WAL checkpoint has to survive a real upload, Flush has to be durable outside the process, and the manifest has to name a restorable object set. Two in-repo backends run this suite -- S3 against MinIO, GCS against fake-gcs-server -- and they run the same one on purpose. Two hand-written copies of a 500-line kill-and-resume choreography diverge the first time either is fixed, and a divergence would show up as one backend quietly proving less than the other rather than as a failure.

What a caller has to supply

Everything here is store-independent except four things: how to register a factory, how to get an empty container, how to read that container back WITHOUT the backend under test, and which config keys the backend needs. Store is those four things and nothing else.

What this suite does not claim

Not IAM, in either cloud. Both suites run against an emulator, and no emulator reproduces IRSA, EKS Pod Identity, GKE Workload Identity, Application Default Credentials resolution or Workload Identity Federation. Those are the legs that justify taking a vendor SDK at all, and they stay covered by a documented manual check, not by this.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RunResumeSuite

func RunResumeSuite(t *testing.T, store Store)

RunResumeSuite runs the full cycle against store.

Two cases, both of which kill an engine rather than stopping it, because the property under test is what a turn-boundary snapshot alone can restore. Nothing here uses t.Parallel: a caller may be pointed at a shared emulator, and a suite that is only correct when run serially is better than one that is intermittently wrong.

func YAMLString

func YAMLString(s string) string

YAMLString renders a value as a YAML double-quoted scalar, for a Store building its ObjectStoreYAML block.

strconv.Quote's escaping is a subset of YAML's for the ASCII these values are (temp paths, backend names, URLs), and it means a t.TempDir() containing a character YAML would otherwise treat as syntax cannot silently produce a different config.

Types

type Store

type Store interface {
	// Name is what failure messages call this store -- "MinIO",
	// "fake-gcs-server". It appears in assertions an implementer will read
	// without knowing which suite produced them.
	Name() string

	// Register registers an objectstore.Factory under a name unique to the
	// running test and returns that name, for an engine to select from YAML.
	//
	// A per-call name rather than the backend's real one: a single case needs
	// two independently controllable backends (the mid-flush case arms one and
	// leaves the other alone), and objectstore's registry is process-global, so
	// sharing the real name would make the cases order-dependent.
	//
	// wrap, when non-nil, interposes on the backend the engine will use. That
	// is the entire mechanism for the mid-flush case: there is no seam inside a
	// backend for "die here", and adding one would be a production change made
	// to satisfy a test.
	//
	// Anything that must run on the test goroutine -- t.Setenv for the
	// credentials the backend will resolve, for instance -- belongs here rather
	// than inside the factory, which runs during Boot.
	Register(t *testing.T, label string, wrap func(objectstore.Backend) objectstore.Backend) string

	// NewBucket creates an empty container and registers its teardown on t.
	// A container per case, never a shared one with a per-case prefix: the
	// suite asserts on the whole key set the engine wrote.
	NewBucket(t *testing.T) string

	// ObjectStoreYAML renders the body of the core.object_store block for a
	// bucket and a registered backend name, indented four spaces so it nests
	// under `core:` -> `object_store:`.
	//
	// The suite does not build this itself because the two backends need
	// different keys: S3 signs over a region, GCS has none and warns if one is
	// given. Rendering YAML rather than an *engine.Config is not a stylistic
	// choice -- newFromConfig is unexported, so engine.NewFromBytes is the only
	// cross-module way in, and it is the path an operator's config takes,
	// including the object-store block's own validation.
	ObjectStoreYAML(backendName, bucket string, policy objectstore.FailurePolicy) string

	// Keys lists every object key in the container, using a client that is NOT
	// the backend under test. Assertions made through the backend that wrote
	// the objects would agree with themselves.
	Keys(t *testing.T, bucket string) []string

	// Get downloads one object with that same independent client.
	Get(t *testing.T, bucket, key string) []byte

	// Exists reports whether one object is present.
	Exists(t *testing.T, bucket, key string) bool
}

Store is the store-specific half of the suite: the things only a backend's own ecosystem can do, expressed so the choreography below does not have to know which cloud it is talking to.

Every method takes *testing.T rather than returning an error, matching objectstoretest: a helper that fails should say which store and which operation, at the line it happened, and a caller who has to check four error returns writes four different messages for the same failure.

Jump to

Keyboard shortcuts

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