S3

Overview

CloudMock emulates Amazon S3 object storage, supporting bucket management, object CRUD, listing with prefix/delimiter filtering, and server-side copy.

Supported Operations

Operation	Status	Notes
ListBuckets	Supported	Returns all buckets in the account
CreateBucket	Supported	Creates a bucket; ignores LocationConstraint
DeleteBucket	Supported	Deletes an empty bucket
HeadBucket	Supported	Returns 200 if bucket exists, 404 otherwise
PutObject	Supported	Stores an object with arbitrary content
GetObject	Supported	Retrieves object content and metadata
DeleteObject	Supported	Removes a single object
HeadObject	Supported	Returns object metadata without body
ListObjectsV2	Supported	Lists objects with prefix/delimiter support
CopyObject	Supported	Server-side copy within or across buckets

Quick Start

curl

# Create a bucket
curl -X PUT http://localhost:4566/my-bucket

# Upload an object
curl -X PUT http://localhost:4566/my-bucket/hello.txt \
  -d "Hello, world!"

# Download an object
curl http://localhost:4566/my-bucket/hello.txt

Node.js

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

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

await s3.send(new CreateBucketCommand({ Bucket: 'my-bucket' }));
await s3.send(new PutObjectCommand({
  Bucket: 'my-bucket', Key: 'hello.txt', Body: 'Hello, world!',
}));

Python

import boto3

s3 = boto3.client('s3', endpoint_url='http://localhost:4566',
                  aws_access_key_id='test', aws_secret_access_key='test',
                  region_name='us-east-1')

s3.create_bucket(Bucket='my-bucket')
s3.put_object(Bucket='my-bucket', Key='hello.txt', Body=b'Hello, world!')

response = s3.get_object(Bucket='my-bucket', Key='hello.txt')
print(response['Body'].read())  # b'Hello, world!'

Configuration

cloudmock.yml

services:
  s3:
    enabled: true

No additional service-specific configuration is required. S3 uses the global port (default 4566).

Known Differences from AWS

• Versioning is not implemented. All objects are unversioned.
• Bucket policies and ACLs are accepted but not enforced.
• LocationConstraint is ignored during CreateBucket.
• Multipart uploads are not supported.
• Presigned URLs are not supported.
• Event notifications (S3 to SNS/SQS/Lambda) are not implemented.

Error Codes

Code	HTTP Status	Description
NoSuchBucket	404	The specified bucket does not exist
NoSuchKey	404	The specified key does not exist
BucketAlreadyExists	409	A bucket with the same name already exists
BucketNotEmpty	409	The bucket is not empty and cannot be deleted
InvalidBucketName	400	The bucket name is invalid