MildStack Logo

Amazon S3

MildStack provides full S3 emulation with bucket management, object storage, multipart uploads, versioning, object lock, and more.

Overview

MildStack's S3 emulation lets you work with buckets and objects locally, just like you would with the real AWS S3. It supports a wide range of S3 features including multipart uploads, versioning, tagging, and object lock.

Supported Operations

Bucket Operations

OperationDescription
ListBucketsList all buckets
CreateBucketCreate a new bucket
HeadBucketCheck if a bucket exists
DeleteBucketDelete an empty bucket
GetBucketLocationGet the region of a bucket

Object Operations

OperationDescription
GetObjectDownload an object
PutObjectUpload an object
HeadObjectGet object metadata without downloading
DeleteObjectDelete a single object
DeleteObjectsDelete multiple objects in a single request
CopyObjectCopy an object between buckets or keys
ListObjectsV2List objects in a bucket

Multipart Upload

OperationDescription
CreateMultipartUploadStart a multipart upload
UploadPartUpload a part
ListPartsList uploaded parts
CompleteMultipartUploadComplete the upload
AbortMultipartUploadCancel the upload
ListMultipartUploadsList active multipart uploads

Versioning

OperationDescription
GetBucketVersioningGet versioning configuration
PutBucketVersioningEnable or suspend versioning
ListObjectVersionsList all versions of objects

Bucket Configuration

OperationDescription
GetBucketPolicy / PutBucketPolicy / DeleteBucketPolicyBucket policy
GetBucketEncryption / PutBucketEncryption / DeleteBucketEncryptionServer-side encryption
GetBucketLifecycleConfiguration / PutBucketLifecycleConfiguration / DeleteBucketLifecycleConfigurationLifecycle rules
GetBucketCors / PutBucketCors / DeleteBucketCorsCORS configuration
GetBucketTagging / PutBucketTagging / DeleteBucketTaggingBucket tags
GetBucketAcl / PutBucketAclAccess control list
GetBucketNotificationConfiguration / PutBucketNotificationConfigurationEvent notifications
GetBucketLogging / PutBucketLoggingAccess logging
GetBucketReplication / PutBucketReplication / DeleteBucketReplicationReplication rules
GetBucketOwnershipControls / PutBucketOwnershipControls / DeleteBucketOwnershipControlsOwnership controls
GetPublicAccessBlock / PutPublicAccessBlock / DeletePublicAccessBlockPublic access block

Object Lock & Governance

OperationDescription
GetObjectLockConfiguration / PutObjectLockConfigurationBucket-level object lock
GetObjectRetention / PutObjectRetentionObject retention period
GetObjectLegalHold / PutObjectLegalHoldLegal hold on objects
GetObjectAcl / PutObjectAclObject ACL
GetObjectTagging / PutObjectTagging / DeleteObjectTaggingObject tags

Quick Example

import {
  S3Client,
  CreateBucketCommand,
  PutObjectCommand,
  GetObjectCommand,
} from "@aws-sdk/client-s3";

const s3 = new S3Client({
  region: "us-east-1",
  endpoint: "http://localhost:4566",
  credentials: { accessKeyId: "test", secretAccessKey: "test" },
  forcePathStyle: true,
});

// Create a bucket
await s3.send(new CreateBucketCommand({ Bucket: "my-bucket" }));

// Upload a file
await s3.send(
  new PutObjectCommand({
    Bucket: "my-bucket",
    Key: "hello.txt",
    Body: "Hello from MildStack!",
    ContentType: "text/plain",
  })
);

// Download the file
const response = await s3.send(
  new GetObjectCommand({
    Bucket: "my-bucket",
    Key: "hello.txt",
  })
);
const body = await response.Body.transformToString();
console.log(body); // "Hello from MildStack!"

AWS CLI Examples

# Create a bucket
awslocal s3 mb s3://photos

# Upload files
awslocal s3 cp ./image.jpg s3://photos/image.jpg

# List objects
awslocal s3 ls s3://photos/

# Enable versioning
awslocal s3api put-bucket-versioning \
  --bucket photos \
  --versioning-configuration Status=Enabled

# Upload a new version
awslocal s3 cp ./image-v2.jpg s3://photos/image.jpg

# List versions
awslocal s3api list-object-versions --bucket photos

Path Style vs Virtual Hosted Style

MildStack uses path-style URLs by default:

http://localhost:4566/my-bucket/my-key

Make sure to set forcePathStyle: true (JavaScript SDK) or the equivalent option in your SDK of choice.

Persistence

All S3 data is stored locally on disk. Buckets, objects, and metadata persist across instance restarts. Deleting an instance removes all its S3 data.

On this page