Documentation
¶
Overview ¶
Package s3waltest carries the shared s3wal test fixtures: the pinned SeaweedFS/MinIO testcontainers, raw path-style S3 client construction, bucket bootstrap/cleanup helpers, and the Phase 1a {seq, nonce} payload codec. It deliberately does NOT import package s3wal — s3wal's own internal tests import these fixtures, and an s3waltest that imported s3wal back would be an import cycle in that test binary. Callers build s3wal.Client / run s3wal.Probe themselves from the raw client returned here.
Index ¶
- Constants
- Variables
- func DecodeSeq(body []byte) (int64, bool)
- func DeleteAllPrefix(tb testing.TB, client *s3.Client, bucket, prefix string)
- func EncodePayload(tb testing.TB, seq int64, size int) []byte
- func EncodePayloadNonce(tb testing.TB, seq int64, nonce string, size int) []byte
- func EnsureBucket(ctx context.Context, client *s3.Client, bucket string) error
- func MustEnsureBucket(tb testing.TB, client *s3.Client, bucket string)
- func NewNonce(tb testing.TB) string
- func OpenExternalS3(tb testing.TB, blobURL string) (*s3.Client, string)
- func RandomHex(tb testing.TB, n int) string
- func RawS3Client(endpoint, region, accessKey, secretKey string) *s3.Client
- func RawS3ClientSession(endpoint, region, accessKey, secretKey, sessionToken string) *s3.Client
- func StartFloci(tb testing.TB) string
- func StartMinIOLegacy(tb testing.TB) (endpoint, user, pass string)
- func StartSeaweedFS(tb testing.TB) string
- func StartSeaweedFSContainer(ctx context.Context) (endpoint string, terminate func(), err error)
- func WaitWriteReady(ctx context.Context, client *s3.Client, bucket string) error
- type BootingFakeS3
- type Payload
Constants ¶
const ( SeaweedFSImage = "chrislusf/seaweedfs:4.48" MinIOLegacyImage = "quay.io/minio/minio:RELEASE.2024-01-16T16-07-38Z@sha256:4c4a4876193f030c81f57aabb22bcb9a73462010eb61fcab66908e03e5484af8" // FlociImage pins the qualified stable release by OCI index digest. // Release 2.2.0 includes the GetObject torn-read fix floci-io/floci#2874 // and follow-up #2901. The linux/amd64 image (config b12af5357828, // upstream revision 17c99047) passed all 22 standard surfaces plus // get-under-overwrite in REQUIRE mode. It honors DeleteObject+If-Match // (412), but that row stays record-only, never a correctness guard. // Keep both Floci workflows in sync with this pin. See // docs/reference/testing.md for credential coverage and remaining gaps. FlociImage = "floci/floci:2.2.0@sha256:e97cd0c1dc2aa14e7697fb5ef5018404c4d6345169dbd276315f0bed2c7b0520" )
Store image pins. SeaweedFS is the self-hosted store of record (plan §5-R7); the MinIO pin is the repo's legacy CI image, kept in the qualification matrix only to document its conditional-write behavior. Upstream withdrew its community MinIO images and binaries (issue #304), so the MinIO pin only resolves on hosts that still hold this exact digest; its lane is opt-in (OPENSTORAGE_TEST_MINIO_LEGACY in internal/ref/s3wal).
const ( SeaweedFSAccessKey = "seaweedfs" SeaweedFSSecretKey = "seaweedfs" )
SeaweedFS's `weed server -s3` anonymous mode accepts any static credential pair; every fixture client signs with these.
const EnvTestS3WALURL = "OPENSTORAGE_TEST_S3WAL_URL"
EnvTestS3WALURL names an external S3 endpoint the qualification lane runs against (same URL grammar as OPENSTORAGE_TEST_S3_URL in internal/blob; distinct variable so blob-package and s3wal runs never collide on cleanup). Unset skips the lane.
Variables ¶
var HTTPClient = awshttp.NewBuildableClient().WithTransportOptions(func(t *http.Transport) {
t.MaxIdleConns = 256
t.MaxIdleConnsPerHost = 256
})
HTTPClient is shared by every fixture S3 client. The SDK default transport keeps only a handful of idle connections per host; the 60 s contention campaign (writers=32) churns thousands of short-lived connections through one endpoint, piling up TIME_WAIT sockets until the kernel runs out of ephemeral ports and dials fail pre-send. Pooling well above the maximum harness concurrency keeps connections reused. (s3wal.New derives its no-retry client from Options(), so the pooled client propagates to CAS calls too.)
Functions ¶
func DecodeSeq ¶
DecodeSeq is the s3wal Client.DecodeSeq hook for payload bodies: it arms the §2.3 read-side seq-monotonicity assert in test/bench clients.
func DeleteAllPrefix ¶
DeleteAllPrefix lists then deletes every key under prefix, reporting real deletion failures so a PASS can never silently leak objects into a user-supplied bucket.
func EncodePayload ¶
EncodePayload is EncodePayloadNonce with a fresh nonce.
func EncodePayloadNonce ¶
EncodePayloadNonce marshals a {seq, nonce} payload padded to roughly size bytes (never below the bare encoding).
func EnsureBucket ¶
EnsureBucket creates the bucket, retrying while the store boots (the SeaweedFS S3 gateway accepts TCP before the filer is ready) and tolerating already-owned rejections, verifies it with HeadBucket, then proves WRITE readiness via WaitWriteReady — the harness must absorb the store's boot window instead of handing out a bucket that cannot yet be written (issue #165).
func MustEnsureBucket ¶
MustEnsureBucket is EnsureBucket for tests.
func OpenExternalS3 ¶
OpenExternalS3 opens an externally provided endpoint from a blob-style URL (s3://bucket?endpoint=…®ion=…&s3ForcePathStyle=true; credentials from the standard AWS env). Real-endpoint safety follows internal/blob/s3endpoint_test.go: buckets are created only on emulator endpoints (endpoint= present); against real S3 the bucket must already exist (HeadBucket only — never CreateBucket, which can reset ACLs on an owned us-east-1 bucket), and versioned buckets are refused because the per-key DeleteObject cleanup would silently accumulate noncurrent versions.
func RandomHex ¶
RandomHex returns n crypto-random bytes hex-encoded so keys stay unique across reruns against a shared long-lived bucket.
func RawS3Client ¶
RawS3Client builds a path-style SigV4 client with static credentials — the same wiring shape as internal/blob's s3ClientOptions, but with explicit credentials so container lanes never depend on process env.
func RawS3ClientSession ¶
RawS3ClientSession is RawS3Client for STS session credentials: temporary keys must send their session token (X-Amz-Security-Token) alongside the SigV4 signature or an enforcing endpoint rejects the request. Used by the nightly Floci githttp lane, whose credentials come from IAM CreateAccessKey → STS AssumeRole rather than a static emulator identity.
func StartFloci ¶
StartFloci runs the pinned Floci image with the S3 service in its default non-enforcing auth mode: the data plane then accepts any static SigV4 credential pair, so the lane needs no IAM provisioning (the only vendored AWS service clients are s3 and sts). That is the right shape for the qualification matrix, which probes data-plane semantics. Auth-enabled IAM and STS coverage lives in the two Floci workflows. Callers must still gate on EnsureBucket for write readiness.
func StartMinIOLegacy ¶
StartMinIOLegacy runs the repo's legacy MinIO CI pin with the testcontainers MinIO module defaults. The image can no longer be pulled from quay.io or Docker Hub (issue #304): a missing local copy fails here.
func StartSeaweedFS ¶
StartSeaweedFS is the testing-scoped convenience: the container terminates with tb.
func StartSeaweedFSContainer ¶
StartSeaweedFSContainer runs the pinned SeaweedFS image (`weed server -s3`: master + volume + filer + S3 gateway in one process; versioning and object-lock never enabled — seaweedfs#8073 avoidance) and returns the S3 endpoint URL plus a terminate func. The gateway components start asynchronously after the port listens — and a created bucket still has no writable volume for a while (issue #165) — so callers must gate on EnsureBucket, whose write-readiness roundtrip is the readiness signal.
func WaitWriteReady ¶
WaitWriteReady proves the bucket accepts OBJECT WRITES with a retried scratch PutObject/DeleteObject roundtrip (60 s bound). Bucket existence alone is not a write-readiness signal: SeaweedFS serves CreateBucket from the filer while object PUTs need a writable volume assignment from the master, which returns 500 InternalError until the volume server has registered and volumes are grown (issues #165, #177). The scratch key lives outside every store-scanned prefix (`_wal/...`, `packs/...`, `lfs/...`) and carries a fresh nonce so concurrent harnesses sharing an external emulator bucket never collide. The PUT/DELETE pair retries as a unit so a transient boot 500 on the delete cannot leak the key. Shared by every SeaweedFS-booting harness: the s3wal qualification lanes (whose no-retry CAS clients turn one boot 500 into a fatal ambiguous verdict), the internal/blob container tests (whose SDK 3-attempt budget can be exhausted inside the boot window), and the githttp e2e lanes.
Types ¶
type BootingFakeS3 ¶
type BootingFakeS3 struct {
PutFailures int // object PUTs left to fail with 500
// contains filtered or unexported fields
}
BootingFakeS3 models the SeaweedFS boot window behind issues #165/#177 as a plain HTTP handler: bucket operations succeed immediately (CreateBucket/HeadBucket run on the filer alone) while the first PutFailures OBJECT PUTs fail with the store's literal 500 InternalError (no writable volume assigned yet). The failure count is deterministic, so the boot-window flake reproduces on every run instead of one CI run in dozens. Zero value is ready to use; set PutFailures before serving.
func (*BootingFakeS3) Handler ¶
func (f *BootingFakeS3) Handler() http.Handler
Handler serves the fake: bucket PUT/HEAD → 200, object PUT → 500 while PutFailures remain (then 200 with an ETag), object DELETE → 204, anything else → 400.
func (*BootingFakeS3) Snapshot ¶
func (f *BootingFakeS3) Snapshot() (putFailures, objectPuts, deletes int)
Snapshot returns (remaining put failures, object puts served, deletes served) under the lock, so assertions never race late keep-alive handler goroutines.