Amazon S3

The s3 driver wraps the AWS SDK v2 *s3.Client. It works with native AWS S3 and any S3-compatible service (MinIO, DigitalOcean Spaces, Backblaze B2, Cloudflare R2, …) by passing a custom endpoint to the AWS config.

When to use it

• Production object storage on AWS or any S3-compatible vendor.
• You need pre-signed URLs, native copy/move, and multipart uploads.
• You’re fine with polling-based watching (default 30 s).

Install

go get github.com/gobeaver/filekit/driver/s3
go get github.com/aws/aws-sdk-go-v2/config
go get github.com/aws/aws-sdk-go-v2/service/s3

Construct

import (
    "context"
    "time"

    "github.com/aws/aws-sdk-go-v2/config"
    awss3 "github.com/aws/aws-sdk-go-v2/service/s3"
    s3driver "github.com/gobeaver/filekit/driver/s3"
    "github.com/gobeaver/filekit"
)

ctx := context.Background()

cfg, err := config.LoadDefaultConfig(ctx, config.WithRegion("us-west-2"))
if err != nil {
    panic(err)
}

client := awss3.NewFromConfig(cfg)

fs := s3driver.New(client, "my-bucket",
    s3driver.WithPrefix("uploads/"),
)

_, _ = fs.Write(ctx, "report.pdf", reader,
    filekit.WithContentType("application/pdf"),
    filekit.WithVisibility(filekit.Public),
)

url, _ := fs.SignedURL(ctx, "report.pdf", 15*time.Minute)
_ = url

Options

• s3driver.WithPrefix(prefix string) — prepended to every key. A trailing / is added if missing.

That is the only option exposed by the constructor today; everything else is controlled via the *s3.Client you pass in.

Credentials

Credentials follow the standard AWS chain (env vars, shared config file, IAM role, …). filekit does not load them itself — configure them on the SDK client. The FILEKIT_S3_ACCESS_KEY_ID / FILEKIT_S3_SECRET_ACCESS_KEY env vars in the top-level filekit.Config are only consulted if you go through filekit.New(cfg).

S3-compatible endpoints

For MinIO, R2, Spaces, etc., set a custom endpoint when loading the AWS config:

import "github.com/aws/aws-sdk-go-v2/aws"

cfg, _ := config.LoadDefaultConfig(ctx,
    config.WithRegion("auto"),
    config.WithEndpointResolverWithOptions(
        aws.EndpointResolverWithOptionsFunc(func(svc, region string, _ ...interface{}) (aws.Endpoint, error) {
            return aws.Endpoint{
                URL:           "https://<account>.r2.cloudflarestorage.com",
                SigningRegion: region,
            }, nil
        }),
    ),
)
client := awss3.NewFromConfig(cfg, func(o *awss3.Options) {
    o.UsePathStyle = true // required by MinIO and some others
})

Capabilities

Interface	Implemented	Notes
FileSystem	yes
CanCopy	yes	native CopyObject
CanMove	yes	CopyObject + DeleteObject
CanSignURL	yes	SignedURL, SignedUploadURL
CanChecksum	yes	uses S3-side checksums when present, otherwise streams the object
CanWatch	yes	polling-based (default 30 s)
ChunkedUploader	yes	maps to native multipart upload
CanReadRange	no	not implemented in this driver yet

Quirks

• The driver uploads via PutObject for unknown reader types and buffers them in memory first. For large unbuffered streams use the ChunkedUploader interface (multipart upload) instead — see InitiateUpload / UploadPart / CompleteUpload on the adapter.
• Stat() populates Checksum only when S3 returns a ChecksumSHA256, ChecksumSHA1, ChecksumCRC32, or ChecksumCRC32C header on the object.
• WriteResult.Checksum after a write is whatever S3 echoed back as ChecksumSHA256 (the driver always requests ChecksumAlgorithmSha256).
• DirExists is implemented by listing with the directory key as a prefix — S3 has no real directories.