CodeFactory.EphemeralS3 0.1.0

CodeFactory.EphemeralS3

A throwaway S3 server for .NET tests. EphemeralS3Server starts a MinIO process on a free loopback port and hands you a preconfigured AmazonS3Client. No Docker, no shared test infrastructure, no cleanup — disposing the server kills the process and deletes its data directory.

The package itself is a few kilobytes of code. The MinIO server is downloaded into a per-user cache the first time you construct an EphemeralS3Server, verified against a pinned SHA-256, and reused from then on.

Install

dotnet add package CodeFactory.EphemeralS3

Usage

using CodeFactory.EphemeralS3;

using var server = new EphemeralS3Server();
using var s3 = server.CreateS3Client();

await s3.PutBucketAsync(new PutBucketRequest { BucketName = "my-bucket" });

Each instance is isolated, so tests can run in parallel. Constructor options:

server.Endpoint exposes the base URL (http://127.0.0.1:<port>) if you need to configure a client yourself. Note that clients must use path-style addressing.

The MinIO download

On first use the pinned MinIO release (RELEASE.2025-09-07T16-13-09Z, ~110 MiB) is downloaded from MinIO's official host, checked against a known SHA-256, and cached at:

Later runs reuse the cached file. Concurrent processes are safe: downloads are serialised with a lock file and published by atomic rename, so a parallel test suite downloads once.

Two environment variables control this:

To download ahead of time rather than inside your first test, call await MinioBinary.EnsureAsync() from an async fixture (or MinioBinary.Ensure()).

In CI, cache the directory so you download once rather than per run:

env:
  EPHEMERAL_S3_CACHE_DIR: ${{ github.workspace }}/.minio-cache

- uses: actions/cache@v4
  with:
    path: ${{ env.EPHEMERAL_S3_CACHE_DIR }}
    key: minio-${{ runner.os }}-${{ runner.arch }}-<pinned release>

Supported platforms

linux-x64, linux-arm64, osx-x64, osx-arm64 and win-x64 — every platform MinIO publishes a server build for. Anything else (notably Windows on arm64) throws PlatformNotSupportedException naming the platform.

Releasing

Tag a commit to publish to NuGet — the tag drives the package version:

git tag v1.2.3
git push origin v1.2.3

Publishing uses NuGet Trusted Publishing via GitHub OIDC, so no API key is stored anywhere. The policy on nuget.org is bound to this repository and to .github/workflows/release.yml; renaming that file breaks publishing until the policy is updated.

License

This library is MIT licensed. See LICENSE.

Third-party notice

This package contains no MinIO code. The MinIO server is downloaded at runtime from MinIO's official host and is licensed separately under the GNU AGPL v3 — Copyright 2015-2025 MinIO, Inc. Source: https://github.com/minio/minio. Using this library therefore means running AGPL-licensed software locally during your tests; review those terms if your organization restricts AGPL dependencies.