@crvouga/mockingbird-service-s3

Local emulators. Real API contracts. Part of Mockingbird.

Stateful S3 emulator that answers exactly as MinIO does, so it drops in for MinIO, Amazon S3 and other S3-compatible storage in tests. Every behavior is pinned by a differential oracle: 370 scripted scenarios (about 3,800 HTTP exchanges) were recorded against MinIO RELEASE.2025-10-15T17-29-55Z, and bun test replays each one against the emulator and requires the same status, headers and XML byte for byte.

Install

npm install -D @crvouga/mockingbird-service-s3

ESM only. Node 22+ or Bun 1.2+.

Usage

Point the SDK endpoint at the emulator and enable path-style addressing. Fixture credentials are validated for presigned requests; the default pair is fixture / fixture.

import { CreateBucketCommand, GetObjectCommand, PutObjectCommand, S3Client } from "@aws-sdk/client-s3"
import { createServer } from "@crvouga/mockingbird-service-s3/server"

// Test setup: start the emulator and point the SDK's endpoint at it.
const server = await createServer()
const s3 = new S3Client({
  endpoint: server.url,
  region: "us-east-1",
  forcePathStyle: true,
  credentials: { accessKeyId: "fixture", secretAccessKey: "fixture" },
})

// Application code: the S3 SDK calls it already makes.
await s3.send(new CreateBucketCommand({ Bucket: "fixtures" }))
await s3.send(
  new PutObjectCommand({ Bucket: "fixtures", Key: "result.bin", Body: new Uint8Array([0, 255]) }),
)
const object = await s3.send(new GetObjectCommand({ Bucket: "fixtures", Key: "result.bin" }))
console.log(await object.Body?.transformToByteArray()) // Uint8Array(2) [ 0, 255 ]

await server.close()

Set an application's S3 endpoint environment variable to the server URL and its region to us-east-1.

Supported operations

Everything MinIO's S3 router serves, with MinIO's precedence, validation order, error codes and messages (generated from MinIO's own error table):

• Buckets: CreateBucket (location constraint, object-lock flag), HeadBucket, DeleteBucket (incl. x-minio-force-delete), ListBuckets, GetBucketLocation, Get/PutBucketVersioning (incl. MinIO's excluded prefixes), Get/Put/DeleteBucketPolicy and GetBucketPolicyStatus, Get/Put/DeleteBucketTagging, Get/Put/DeleteBucketLifecycle, Get/Put/DeleteBucketEncryption, Get/PutBucketNotification, Get/Put/DeleteBucketReplication, Get/PutObjectLockConfiguration, the ACL, website, accelerate, request-payment and logging stubs, and MinIO's ListenNotification and replication extensions.
• Objects: PutObject, GetObject, HeadObject (system and user metadata, conditional reads and writes, every Range form, partNumber, response-* overrides, checksums CRC32/CRC32C/CRC64NVME/SHA1/SHA256 with x-amz-checksum-mode), CopyObject (metadata and tagging directives, copy-source conditionals, versions), DeleteObject and DeleteObjects (delete markers, null versions), Get/Put/DeleteObjectTagging, Get/PutObjectRetention, Get/PutObjectLegalHold, Get/PutObjectAcl, GetObjectAttributes, RestoreObject, SelectObjectContent (CSV and JSON input, basic SQL, event-stream framing), and browser POST uploads (POST policy, V4 and V2 form signatures).
• Listing: ListObjects V1, V2 and metadata=true, ListObjectVersions, including MinIO's marker and truncation behavior.
• Multipart: Create, UploadPart, UploadPartCopy, Complete, Abort, ListParts, ListMultipartUploads, with part checksums and the <md5>-N ETag.
• Authentication: SigV4 header and presigned, streaming aws-chunked (signed chunks and signed or unsigned trailers), SigV2 header and presigned, request-time skew, and anonymous access through bucket policies.

GetObjectLambda and PutObjectExtract (snowball auto-extract) answer NotImplemented.

Authentication modes

• authentication: "lenient" (default): unsigned requests act as the bucket owner and header signatures are not checked, so plain fetch works in tests. Presigned URLs are still verified against credentials (default fixture / fixture).
• authentication: "strict": MinIO's authentication exactly. Every request must be signed by a key in credentials, and an anonymous request is allowed only where the bucket policy grants it. The oracle runs in this mode.

region (default us-east-1) is the signing region and the x-amz-bucket-region header.

Where it departs from MinIO

• Bucket CORS: MinIO only stubs the bucket CORS API, so the emulator keeps Amazon S3's documented behavior. The stored CORSConfiguration is enforced: a preflight is answered by the first matching rule or refused with 403 AccessForbidden, and matching actual requests get Access-Control-* headers. This is not oracle-verified.
• Virtual-hosted-style addressing: Host: <bucket>.<base host> names the bucket (base hosts default to localhost; set virtualHosts, or --virtual-host a,b, empty for path-style only).
• Body size: createServer accepts up to 5 GiB per PUT or part (S3's limit; MinIO's is 5 TiB). createServer({ maxBodyBytes }) lowers it.
• Listings always read live data, where MinIO serves later pages from a snapshot taken on the first page.

The oracle

oracle/ in the repository holds the harness, the scenarios and the recorded MinIO transcripts. bun oracle/run.ts replays them against a live MinIO, --record refreshes the transcripts; see oracle/README.md.

Admin and deterministic controls

• GET/POST /__admin/objects inspects metadata or seeds an object; GET /__admin/objects/:bucket/:key downloads its bytes.
• GET /__admin/uploads inspects active uploads and part metadata.
• Preset faults are slow_down, access_denied, expired_token, and one-shot truncate_stream. Generic faults can fail or reset the next part request.
• Advance the shared emulator clock through /__admin/clock to expire a presigned URL.
• Object writes, copies, multipart completion, and deletes publish S3-shaped notifications. Configure HTTP sinks through runtime webhooks options or the shared webhook admin routes; delivery attempts and retries appear under /__admin/webhooks.

The shared runtime also provides health, reset, journal, metrics, timeline, and fault routes. Select isolated state with x-mockingbird-namespace, /__admin/ns/<name>, or a SigV4 access-key mapping.

Deliberately not modelled

SSE-C and SSE-KMS encryption (MinIO needs TLS and a KMS for them), IAM users and policies other than the root credentials and bucket policies, actually applying lifecycle rules or replicating, and real SQS delivery. SQS consumers can use the captured notification payload through a configured HTTP sink.

API

• S3API, S3APIOptions: Fetch handler and configuration.
• S3Notification, S3Object (ObjectVersion), S3SeedObject, BucketRecord, MultipartUpload, MultipartPart: notification, state, and fixture types.
• createRuntime, S3Runtime, S3RuntimeOptions: full Mockingbird runtime and webhook hub.
• S3_NAMESPACE, S3_PRESETS, accessKeyCredential: constants and fault controls.
• S3_MAX_UPLOAD_BYTES: the default request body limit (5 GiB) for createServer.
• document, operationIds, supportedOperationIds: generated OpenAPI metadata.
• createServer, S3ServerOptions, DEFAULT_PORT, serveTarget from ./server: Node HTTP adapter and CLI integration.

Oracle: MinIO RELEASE.2025-10-15T17-29-55Z, with the Amazon S3 API Reference for bucket CORS.