@bylocico/testcontainers-rustfs

A small Testcontainers wrapper for RustFS, an S3-compatible object store written in Rust.

The package is intentionally dependency-light and shaped like the official Testcontainers modules so it can be upstreamed to testcontainers/testcontainers-node later.

Versioning

The npm package version tracks the RustFS Docker image version it targets.

For example, @bylocico/[email protected] defaults to:

rustfs/rustfs:1.0.0-beta.1

Wrapper-only changes should be kept small and released with the next RustFS target version where practical. If an urgent wrapper fix is needed before RustFS moves, publish a patch version and document the exception in the release notes.

CI runs automatically on pull requests and pushes. The update workflow also queries Docker Hub on a schedule, finds every new semver RustFS image tag, tests each one in ascending order, and opens an auto-merge PR that retargets the package to the newest passing tag. Variant image tags such as -glibc are ignored for package versioning because they are image flavors, not RustFS release versions.

Consumers can still pull any valid RustFS image version without waiting for this package to retarget:

await new RustfsContainer('rustfs/rustfs:1.0.0-beta.1').start()
await new RustfsContainer('rustfs/rustfs:latest').start()

Install

npm install --save-dev @bylocico/testcontainers-rustfs @aws-sdk/client-s3

@aws-sdk/client-s3 is a peer dependency because most consumers already own their SDK version.

Usage

import { PutObjectCommand, S3Client } from '@aws-sdk/client-s3'
import { RustfsContainer } from '@bylocico/testcontainers-rustfs'

const rustfs = await new RustfsContainer().start()

try {
  await rustfs.ensureBucket('my-bucket')

  const s3 = new S3Client({
    endpoint: rustfs.getEndpoint(),
    region: 'us-east-1',
    credentials: {
      accessKeyId: rustfs.accessKey,
      secretAccessKey: rustfs.secretKey,
    },
    forcePathStyle: true,
  })

  try {
    await s3.send(
      new PutObjectCommand({
        Bucket: 'my-bucket',
        Key: 'hello.txt',
        Body: 'world',
      }),
    )
  } finally {
    s3.destroy()
  }
} finally {
  await rustfs.stop()
}

API

new RustfsContainer(image?: string)

Creates an unstarted RustFS container. By default it uses the RustFS image version that matches the package version.

Pass an explicit image to test a different RustFS release:

new RustfsContainer('rustfs/rustfs:latest')
new RustfsContainer('rustfs/rustfs:1.0.0-beta.1')

.withCredentials(user, password)

Overrides the default root user/password.

Defaults:

rustfsadmin / rustfsadmin

Example:

const rustfs = await new RustfsContainer()
  .withCredentials('test-user', 'test-password')
  .start()

All normal GenericContainer builder methods remain available through inheritance, including withEnvironment, withCommand, and withNetwork.

StartedRustfsContainer

The started container exposes:

• getEndpoint(): string - http://<host>:<port> for the S3 API
• getHost(): string
• getPort(): number
• accessKey: string
• secretKey: string
• ensureBucket(name): Promise<void>
• stop(): Promise<void>

ensureBucket() is idempotent and tolerates BucketAlreadyOwnedByYou and BucketAlreadyExists.

S3 Client Notes

Use getEndpoint() rather than hardcoding ports. Testcontainers maps container port 9000 to a random host port.

Use path-style addressing with the AWS SDK:

forcePathStyle: true

Virtual-hosted-style addressing requires DNS entries that the test container does not provide.

Development

Requirements:

• Node.js 18+
• npm
• Docker

Install dependencies:

npm install

Run checks:

npm run typecheck
npm run build
npm test

Run tests against a specific RustFS image:

RUSTFS_IMAGE=rustfs/rustfs:latest npm test

List RustFS release image tags newer than the package target:

node scripts/update-rustfs-version.mjs --list-newer

Retarget the package to a specific RustFS version:

node scripts/update-rustfs-version.mjs --version 1.0.0-beta.1
npm install --package-lock-only

Inspect the package contents before publishing:

npm pack --dry-run

Publishing

Publishing is handled by .github/workflows/publish.yml.

Repository setup:

1. Create an npm automation token with publish access to @bylocico/testcontainers-rustfs.
2. Add it to the GitHub repository as NPM_TOKEN.
3. Ensure GitHub Actions has permission to request OIDC tokens for npm provenance.

Release flow:

1. Confirm the target RustFS Docker tag exists:

   docker manifest inspect rustfs/rustfs:1.0.0-beta.1
   

2. Update package.json and DEFAULT_RUSTFS_VERSION to the same version.

3. Run npm install so package-lock.json records the new package version.

4. Run npm run typecheck && npm run build && npm test && npm pack --dry-run.

5. Push to main.

6. Create a GitHub release for the same version, for example v1.0.0-beta.1.

7. The publish workflow runs tests and publishes with npm provenance:

   npm publish --access public --provenance
   

Upstreaming

Keep the public API close to the official Testcontainers module style:

• one container class extending GenericContainer
• one started container class extending AbstractStartedContainer
• no application-specific dependencies
• no Bylocico or Ema-specific runtime behavior

That keeps a future upstream contribution to testcontainers/testcontainers-node small and reviewable.