S3

kumolo implements the S3 REST API. All operations accept standard AWS SDK v2 requests — point your client at http://localhost:5566 with UsePathStyle = true.

Support levels

Symbol	Meaning
✓	Fully implemented — the feature behaves like real AWS
◐	Partial support — the operation works but has known limitations; see the note for details
—	Not yet implemented

Operation support

Operations sourced from internal/s3/router.go in the kumolo repository.

Bucket operations

Operation	Supported
CreateBucket	✓
DeleteBucket	✓
HeadBucket	✓
ListBuckets	◐
ListDirectoryBuckets	—
CreateSession	—

Note

ListBuckets pagination (max-buckets, continuation-token) is not implemented — all buckets are returned in a single response. prefix and bucket-region filters are ignored.

Object operations

Operation	Supported
PutObject	✓
GetObject	✓
DeleteObject	✓
DeleteObjects	✓
HeadObject	✓
CopyObject	✓
GetObjectAttributes	✓
RestoreObject	◐
SelectObjectContent	◐
GetObjectTorrent	—
WriteGetObjectResponse	—

Note

SelectObjectContent supports CSV and JSON input with CSV and JSON output. Parquet input is not supported and returns an error. RestoreObject does not support the versionId query parameter; only the current version can be restored.

Listing

Operation	Supported
ListObjects	✓
ListObjectsV2	✓
ListObjectVersions	◐

Note

ListObjectVersions: version-id-marker (tiebreaking within the same key) is not implemented; only key-marker is supported.

Multipart upload

Operation	Supported
CreateMultipartUpload	✓
UploadPart	✓
UploadPartCopy	✓
CompleteMultipartUpload	✓
AbortMultipartUpload	✓
ListMultipartUploads	◐
ListParts	✓

Note

ListMultipartUploads: upload-id-marker tiebreaking within the same key is not implemented; only key-marker pagination is supported.

Presigned requests

Presigned URLs

All object operations (GetObject, PutObject, DeleteObject, HeadObject, etc.) support standard SigV4 presigned URLs generated by the AWS SDK presign client. The X-Amz-Expires value is validated (1–604800 seconds); expired URLs return 403 AccessDenied. Signatures are not verified — see Known Limitations.

Presigned POST

Operation	Supported
POST Object	✓

Presigned POST enables browser-based direct-to-S3 uploads without routing the file through your server. Generate a presigned POST policy with @aws-sdk/s3-presigned-post (JS) or a compatible library, then submit via an HTML form with enctype="multipart/form-data".

Supported form fields: key (required; supports ${filename} substitution), Content-Type, acl, x-amz-meta-*, success_action_status (200, 201, 204), and success_action_redirect.

Policy conditions are not evaluated — see Known Limitations.

Versioning

Operation	Supported
GetBucketVersioning	✓
PutBucketVersioning	◐

Note

PutBucketVersioning: the x-amz-mfa header (MFA delete) is not supported and is silently ignored.

CORS

Operation	Supported
GetBucketCors	✓
PutBucketCors	✓
DeleteBucketCors	✓

Tagging

Operation	Supported
GetBucketTagging	✓
PutBucketTagging	✓
DeleteBucketTagging	✓
GetObjectTagging	✓
PutObjectTagging	✓
DeleteObjectTagging	✓

Object Lock

Operation	Supported
GetObjectRetention	✓
PutObjectRetention	✓
GetObjectLegalHold	✓
PutObjectLegalHold	✓
GetObjectLockConfiguration	✓
PutObjectLockConfiguration	✓

Note

PutObjectLockConfiguration with a DefaultRetention rule automatically applies the configured mode (GOVERNANCE or COMPLIANCE) and period (days or years) to every new object uploaded to that bucket via PutObject, CopyObject, and CompleteMultipartUpload.

Location

Operation	Supported
GetBucketLocation	✓

Policy

Operation	Supported
GetBucketPolicy	◐
PutBucketPolicy	◐
DeleteBucketPolicy	◐
GetBucketPolicyStatus	—

ACL

Operation	Supported
GetBucketAcl	✓
PutBucketAcl	◐
GetObjectAcl	◐
PutObjectAcl	◐

Note

ACL is stored and enforced on object reads. Individual grant headers (e.g. x-amz-grant-read, x-amz-grant-write) are not supported in PutBucketAcl and PutObjectAcl — use the canned ACL or XML body form. The versionId query parameter is not supported on GetObjectAcl and PutObjectAcl; ACL applies to the current version only.

Encryption

Operation	Supported
GetBucketEncryption	✓
PutBucketEncryption	✓
DeleteBucketEncryption	✓

Note

Bucket default encryption is applied to PutObject, CopyObject, and CreateMultipartUpload when no per-request SSE header is supplied.

Supported SSE types:

• AES256 — objects are encrypted with AES-256-GCM using a per-object random key
• aws:kms — the specified KMS key (or the bucket default) is validated and the key ARN is stored; the object body is encrypted using a data key generated via KMS
• aws:kms:dsse — same as aws:kms with dual-layer header behaviour
• SSE-C — the customer-provided key is used to encrypt and decrypt the object; the key itself is not stored

Public access block

Operation	Supported
GetPublicAccessBlock	◐
PutPublicAccessBlock	◐
DeletePublicAccessBlock	◐

Ownership controls

Operation	Supported
GetBucketOwnershipControls	◐
PutBucketOwnershipControls	◐
DeleteBucketOwnershipControls	◐

Lifecycle

Operation	Supported
GetBucketLifecycleConfiguration	✓
PutBucketLifecycleConfiguration	✓
DeleteBucketLifecycle	✓

Note

Transition (for the current object version) is not supported. Expiration (by days and by date), ExpiredObjectDeleteMarker, NoncurrentVersionExpiration, NoncurrentVersionTransition, and AbortIncompleteMultipartUpload are enforced. The x-amz-transition-default-minimum-object-size request header is accepted and stored but does not affect lifecycle evaluation.

Static website hosting

Operation	Supported
GetBucketWebsite	◐
PutBucketWebsite	◐
DeleteBucketWebsite	◐

Note

The website configuration API is accepted and persisted, but kumolo does not serve static website content. The website endpoint is not available.

Replication

Operation	Supported
GetBucketReplication	✓
PutBucketReplication	✓
DeleteBucketReplication	✓

Note

Replication is executed synchronously within the same kumolo instance. Cross-instance replication to a real AWS destination is not supported. DeleteMarkerReplication is supported. Tag-based filter rules (Filter.Tag and Filter.And.Tags) are supported in addition to key prefix matching (Filter.Prefix).

Notification

Operation	Supported
GetBucketNotificationConfiguration	◐
PutBucketNotificationConfiguration	◐

Logging

Operation	Supported
GetBucketLogging	✓
PutBucketLogging	✓

Note

Access logs are written to the configured target bucket in S3 server access log format. Each request produces one log object (real AWS batches multiple records per file). Fields not tracked by kumolo (bucket-owner, request-id, object-size, etc.) are emitted as -.

Transfer acceleration

Operation	Supported
GetBucketAccelerateConfiguration	◐
PutBucketAccelerateConfiguration	◐

Request payment

Operation	Supported
GetBucketRequestPayment	◐
PutBucketRequestPayment	◐

Analytics

Operation	Supported
GetBucketAnalyticsConfiguration	—
PutBucketAnalyticsConfiguration	—
DeleteBucketAnalyticsConfiguration	—
ListBucketAnalyticsConfigurations	—

Intelligent-Tiering

Operation	Supported
GetBucketIntelligentTieringConfiguration	—
PutBucketIntelligentTieringConfiguration	—
DeleteBucketIntelligentTieringConfiguration	—
ListBucketIntelligentTieringConfigurations	—

Inventory

Operation	Supported
GetBucketInventoryConfiguration	—
PutBucketInventoryConfiguration	—
DeleteBucketInventoryConfiguration	—
ListBucketInventoryConfigurations	—

Metrics

Operation	Supported
GetBucketMetricsConfiguration	—
PutBucketMetricsConfiguration	—
DeleteBucketMetricsConfiguration	—
ListBucketMetricsConfigurations	—

Quick start

Go

import (
    "context"
    "strings"

    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/credentials"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

cfg, err := config.LoadDefaultConfig(context.Background(),
    config.WithRegion("us-east-1"),
    config.WithCredentialsProvider(
        credentials.NewStaticCredentialsProvider("test", "test", ""),
    ),
)
if err != nil {
    panic(err)
}

client := s3.NewFromConfig(cfg, func(o *s3.Options) {
    o.BaseEndpoint = aws.String("http://localhost:5566")
    o.UsePathStyle = true  // required for local endpoint
})

if _, err = client.CreateBucket(context.Background(), &s3.CreateBucketInput{
    Bucket: aws.String("my-bucket"),
}); err != nil {
    panic(err)
}

if _, err = client.PutObject(context.Background(), &s3.PutObjectInput{
    Bucket: aws.String("my-bucket"),
    Key:    aws.String("hello.txt"),
    Body:   strings.NewReader("hello, kumolo"),
}); err != nil {
    panic(err)
}

Python (boto3)

import boto3

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

s3.create_bucket(Bucket="my-bucket")
s3.put_object(Bucket="my-bucket", Key="hello.txt", Body=b"hello, kumolo")

AWS CLI

aws s3 mb s3://my-bucket \
  --endpoint-url http://localhost:5566 \
  --region us-east-1

aws s3 cp hello.txt s3://my-bucket/ \
  --endpoint-url http://localhost:5566

Note

UsePathStyle = true is required for Go and other SDKs that default to virtual-hosted-style URLs. Without it, the SDK generates URLs like my-bucket.localhost:5566 which do not resolve.