{"_id":"@bylocico/testcontainers-rustfs","name":"@bylocico/testcontainers-rustfs","dist-tags":{"latest":"1.0.0-beta.1"},"versions":{"1.0.0-beta.1":{"name":"@bylocico/testcontainers-rustfs","version":"1.0.0-beta.1","description":"Testcontainers wrapper for RustFS — an S3-compatible object store written in Rust.","keywords":["testcontainers","rustfs","s3","minio","object-storage","testing"],"license":"MIT","author":{"name":"By Loci"},"repository":{"type":"git","url":"git+https://github.com/bylocico/testcontainers-rustfs.git"},"homepage":"https://github.com/bylocico/testcontainers-rustfs#readme","bugs":{"url":"https://github.com/bylocico/testcontainers-rustfs/issues"},"packageManager":"npm@10.9.8","engines":{"node":">=18","npm":">=10.0.0 <11.0.0"},"type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"scripts":{"build":"tsc -p tsconfig.build.json","clean":"rimraf dist","prepack":"npm run clean && npm run build","npm10":"node ./node_modules/npm/bin/npm-cli.js","test":"node --import tsx --test \"test/**/*.test.ts\"","typecheck":"tsc --noEmit -p tsconfig.json"},"peerDependencies":{"@aws-sdk/client-s3":">=3"},"peerDependenciesMeta":{"@aws-sdk/client-s3":{"optional":false}},"dependencies":{"testcontainers":"^11.8.0"},"devDependencies":{"npm":"10.9.8","@aws-sdk/client-s3":"^3.1037.0","@types/node":"^24.10.1","rimraf":"^6.1.0","tsx":"^4.20.6","typescript":"^5.9.3"},"_id":"@bylocico/testcontainers-rustfs@1.0.0-beta.1","gitHead":"9d4b37f07828bb9d7bd23b0e929bfd952315fa6f","_nodeVersion":"24.15.0","_npmVersion":"10.9.8","dist":{"integrity":"sha512-yzlQXvOhQ16Y0kgLxUvVyElaaNcxCXNUYBJpqq32ypgHuf+x1dgVwBymsubtFB1Lr7W6Ercem/B1Ci+wAJypPQ==","shasum":"167ae2a8318e4b81224c9f1339bda100b9f34855","tarball":"https://registry.npmjs.org/@bylocico/testcontainers-rustfs/-/testcontainers-rustfs-1.0.0-beta.1.tgz","fileCount":13,"unpackedSize":18228,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBGEZpcLX7JiCcXVigqRaIH4e6wv9Kvhi5n3LOn+s3l9AiA2lnJpZ1N+yKB/0VmoXT/l8vYSL+Uj17z3B7AiCPuPGQ=="}]},"_npmUser":{"name":"thatdoogieguy","email":"j@cobthom.as"},"directories":{},"maintainers":[{"name":"thatdoogieguy","email":"j@cobthom.as"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/testcontainers-rustfs_1.0.0-beta.1_1778200652591_0.1596095325482605"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-08T00:37:32.462Z","1.0.0-beta.1":"2026-05-08T00:37:32.742Z","modified":"2026-05-08T00:37:33.000Z"},"maintainers":[{"name":"thatdoogieguy","email":"j@cobthom.as"}],"description":"Testcontainers wrapper for RustFS — an S3-compatible object store written in Rust.","homepage":"https://github.com/bylocico/testcontainers-rustfs#readme","keywords":["testcontainers","rustfs","s3","minio","object-storage","testing"],"repository":{"type":"git","url":"git+https://github.com/bylocico/testcontainers-rustfs.git"},"author":{"name":"By Loci"},"bugs":{"url":"https://github.com/bylocico/testcontainers-rustfs/issues"},"license":"MIT","readme":"# @bylocico/testcontainers-rustfs\n\nA small [Testcontainers](https://testcontainers.com) wrapper for [RustFS](https://rustfs.com), an S3-compatible object store written in Rust.\n\nThe package is intentionally dependency-light and shaped like the official Testcontainers modules so it can be upstreamed to [`testcontainers/testcontainers-node`](https://github.com/testcontainers/testcontainers-node) later.\n\n## Versioning\n\nThe npm package version tracks the RustFS Docker image version it targets.\n\nFor example, `@bylocico/testcontainers-rustfs@1.0.0-beta.1` defaults to:\n\n```text\nrustfs/rustfs:1.0.0-beta.1\n```\n\nWrapper-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.\n\nCI 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.\n\nConsumers can still pull any valid RustFS image version without waiting for this package to retarget:\n\n```ts\nawait new RustfsContainer('rustfs/rustfs:1.0.0-beta.1').start()\nawait new RustfsContainer('rustfs/rustfs:latest').start()\n```\n\n## Install\n\n```bash\nnpm install --save-dev @bylocico/testcontainers-rustfs @aws-sdk/client-s3\n```\n\n`@aws-sdk/client-s3` is a peer dependency because most consumers already own their SDK version.\n\n## Usage\n\n```ts\nimport { PutObjectCommand, S3Client } from '@aws-sdk/client-s3'\nimport { RustfsContainer } from '@bylocico/testcontainers-rustfs'\n\nconst rustfs = await new RustfsContainer().start()\n\ntry {\n  await rustfs.ensureBucket('my-bucket')\n\n  const s3 = new S3Client({\n    endpoint: rustfs.getEndpoint(),\n    region: 'us-east-1',\n    credentials: {\n      accessKeyId: rustfs.accessKey,\n      secretAccessKey: rustfs.secretKey,\n    },\n    forcePathStyle: true,\n  })\n\n  try {\n    await s3.send(\n      new PutObjectCommand({\n        Bucket: 'my-bucket',\n        Key: 'hello.txt',\n        Body: 'world',\n      }),\n    )\n  } finally {\n    s3.destroy()\n  }\n} finally {\n  await rustfs.stop()\n}\n```\n\n## API\n\n### `new RustfsContainer(image?: string)`\n\nCreates an unstarted RustFS container. By default it uses the RustFS image version that matches the package version.\n\nPass an explicit image to test a different RustFS release:\n\n```ts\nnew RustfsContainer('rustfs/rustfs:latest')\nnew RustfsContainer('rustfs/rustfs:1.0.0-beta.1')\n```\n\n### `.withCredentials(user, password)`\n\nOverrides the default root user/password.\n\nDefaults:\n\n```text\nrustfsadmin / rustfsadmin\n```\n\nExample:\n\n```ts\nconst rustfs = await new RustfsContainer()\n  .withCredentials('test-user', 'test-password')\n  .start()\n```\n\nAll normal `GenericContainer` builder methods remain available through inheritance, including `withEnvironment`, `withCommand`, and `withNetwork`.\n\n### `StartedRustfsContainer`\n\nThe started container exposes:\n\n- `getEndpoint(): string` - `http://<host>:<port>` for the S3 API\n- `getHost(): string`\n- `getPort(): number`\n- `accessKey: string`\n- `secretKey: string`\n- `ensureBucket(name): Promise<void>`\n- `stop(): Promise<void>`\n\n`ensureBucket()` is idempotent and tolerates `BucketAlreadyOwnedByYou` and `BucketAlreadyExists`.\n\n## S3 Client Notes\n\nUse `getEndpoint()` rather than hardcoding ports. Testcontainers maps container port `9000` to a random host port.\n\nUse path-style addressing with the AWS SDK:\n\n```ts\nforcePathStyle: true\n```\n\nVirtual-hosted-style addressing requires DNS entries that the test container does not provide.\n\n## Development\n\nRequirements:\n\n- Node.js 18+\n- npm\n- Docker\n\nInstall dependencies:\n\n```bash\nnpm install\n```\n\nRun checks:\n\n```bash\nnpm run typecheck\nnpm run build\nnpm test\n```\n\nRun tests against a specific RustFS image:\n\n```bash\nRUSTFS_IMAGE=rustfs/rustfs:latest npm test\n```\n\nList RustFS release image tags newer than the package target:\n\n```bash\nnode scripts/update-rustfs-version.mjs --list-newer\n```\n\nRetarget the package to a specific RustFS version:\n\n```bash\nnode scripts/update-rustfs-version.mjs --version 1.0.0-beta.1\nnpm install --package-lock-only\n```\n\nInspect the package contents before publishing:\n\n```bash\nnpm pack --dry-run\n```\n\n## Publishing\n\nPublishing is handled by `.github/workflows/publish.yml`.\n\nRepository setup:\n\n1. Create an npm automation token with publish access to `@bylocico/testcontainers-rustfs`.\n2. Add it to the GitHub repository as `NPM_TOKEN`.\n3. Ensure GitHub Actions has permission to request OIDC tokens for npm provenance.\n\nRelease flow:\n\n1. Confirm the target RustFS Docker tag exists:\n\n   ```bash\n   docker manifest inspect rustfs/rustfs:1.0.0-beta.1\n   ```\n\n2. Update `package.json` and `DEFAULT_RUSTFS_VERSION` to the same version.\n3. Run `npm install` so `package-lock.json` records the new package version.\n4. Run `npm run typecheck && npm run build && npm test && npm pack --dry-run`.\n5. Push to `main`.\n6. Create a GitHub release for the same version, for example `v1.0.0-beta.1`.\n7. The publish workflow runs tests and publishes with npm provenance:\n\n   ```bash\n   npm publish --access public --provenance\n   ```\n\n## Upstreaming\n\nKeep the public API close to the official Testcontainers module style:\n\n- one container class extending `GenericContainer`\n- one started container class extending `AbstractStartedContainer`\n- no application-specific dependencies\n- no Bylocico or Ema-specific runtime behavior\n\nThat keeps a future upstream contribution to `testcontainers/testcontainers-node` small and reviewable.\n","readmeFilename":"README.md","_rev":"1-c14bcf5b2944408edd8352c64252343d"}