Skip to content

S3

Protocol: REST XML Endpoint: http://localhost:4566/{bucket}/{key}

Supported Operations

Category Operations
Buckets ListBuckets, CreateBucket, HeadBucket, DeleteBucket, GetBucketLocation
Objects PutObject, GetObject, GetObjectAttributes, HeadObject, DeleteObject, DeleteObjects, CopyObject
Listing ListObjects, ListObjectsV2, ListObjectVersions
Multipart CreateMultipartUpload, UploadPart, CompleteMultipartUpload, AbortMultipartUpload, ListMultipartUploads
Versioning PutBucketVersioning, GetBucketVersioning
Tagging PutBucketTagging, GetBucketTagging, PutObjectTagging, GetObjectTagging, DeleteObjectTagging
Policy PutBucketPolicy, GetBucketPolicy, DeleteBucketPolicy
CORS PutBucketCors, GetBucketCors, DeleteBucketCors
Lifecycle PutBucketLifecycle, GetBucketLifecycle, DeleteBucketLifecycle
ACL PutBucketAcl, GetBucketAcl, PutObjectAcl, GetObjectAcl
Encryption PutBucketEncryption, GetBucketEncryption, DeleteBucketEncryption
Notifications PutBucketNotification, GetBucketNotification
Object Lock PutObjectLockConfiguration, GetObjectLockConfiguration, PutObjectRetention, GetObjectRetention, PutObjectLegalHold, GetObjectLegalHold
Pre-signed URLs Generates and validates pre-signed GET/PUT URLs
S3 Select SelectObjectContent

Configuration

floci:
  services:
    s3:
      enabled: true
      default-presign-expiry-seconds: 3600
  auth:
    presign-secret: local-emulator-secret

Examples

export AWS_ENDPOINT=http://localhost:4566

# Create bucket
aws s3 mb s3://my-bucket --endpoint-url $AWS_ENDPOINT

# Upload a file
aws s3 cp ./report.pdf s3://my-bucket/reports/report.pdf --endpoint-url $AWS_ENDPOINT

# Upload inline content
echo '{"hello":"world"}' | aws s3 cp - s3://my-bucket/data.json --endpoint-url $AWS_ENDPOINT

# Download
aws s3 cp s3://my-bucket/data.json ./data.json --endpoint-url $AWS_ENDPOINT

# Inspect object attributes without downloading the body
aws s3api get-object-attributes \
  --bucket my-bucket \
  --key data.json \
  --object-attributes ETag ObjectSize StorageClass \
  --endpoint-url $AWS_ENDPOINT

# List
aws s3 ls s3://my-bucket --endpoint-url $AWS_ENDPOINT

# Delete
aws s3 rm s3://my-bucket/data.json --endpoint-url $AWS_ENDPOINT

# Enable versioning
aws s3api put-bucket-versioning \
  --bucket my-bucket \
  --versioning-configuration Status=Enabled \
  --endpoint-url $AWS_ENDPOINT

# Generate a pre-signed URL (valid for 1 hour)
aws s3 presign s3://my-bucket/report.pdf \
  --expires-in 3600 \
  --endpoint-url $AWS_ENDPOINT

Path-Style URLs

Floci uses path-style URLs:

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

When using the AWS SDK, enable path-style mode:

S3Client s3 = S3Client.builder()
    .endpointOverride(URI.create("http://localhost:4566"))
    .serviceConfiguration(S3Configuration.builder()
        .pathStyleAccessEnabled(true)
        .build())
    .build();

const s3 = new S3Client({
  endpoint: "http://localhost:4566",
  forcePathStyle: true,
});

s3 = boto3.client("s3",
    endpoint_url="http://localhost:4566",
    config=Config(s3={"addressing_style": "path"}))

Object Attribute Notes

Floci now persists and returns the following object attribute state on S3 object APIs:

  • user metadata from x-amz-meta-*
  • storage class from x-amz-storage-class
  • checksum metadata for object reads and GetObjectAttributes
  • multipart part manifests for GetObjectAttributes(ObjectParts)

Current limitations:

  • checksum responses focus on SHA-1 and SHA-256
  • copy-based metadata updates support x-amz-metadata-directive: REPLACE for user metadata and content type, but do not yet cover every AWS copy header