sigv4s3

README

sigv4-s3

Minimal AWS Signature Version 4 (SigV4) client for S3 and S3-compatible object storage such as AWS S3, MinIO, Backblaze B2, and Cloudflare R2.

Why this exists

The official AWS Go SDK v2 is large and brings in dozens of transitive dependencies. If your application only needs basic object operations (PUT, GET, DELETE, COPY) with streaming uploads, sigv4-s3 provides a lightweight client using only the Go standard library.

Features

• Standard library only (crypto/*, net/http, encoding/*)
• Streaming uploads by hashing payload data via io.ReadSeeker without loading entire files into memory
• Daily SigV4 derived key caching to avoid redundant HMAC calculations
• SSE-C header formatting for customer-managed encryption keys
• Path-style (MinIO) and virtual-hosted bucket addressing
• Retries with backoff and stream rewind on transient HTTP 429 and 5xx responses

Installation

go get github.com/fumbledlol/sigv4-s3

Quick start

package main

import (
	"context"
	"os"

	"github.com/fumbledlol/sigv4-s3"
)

func main() {
	client, err := sigv4s3.New(sigv4s3.Config{
		Endpoint:  "https://s3.us-east-1.amazonaws.com",
		Region:    "us-east-1",
		Bucket:    "my-bucket",
		AccessKey: os.Getenv("AWS_ACCESS_KEY_ID"),
		SecretKey: os.Getenv("AWS_SECRET_ACCESS_KEY"),
	})
	if err != nil {
		panic(err)
	}

	ctx := context.Background()

	// Upload file
	file, err := os.Open("avatar.png")
	if err != nil {
		panic(err)
	}
	defer file.Close()

	err = client.PutObject(ctx, "users/1/avatar.png", file, "image/png", nil)
	if err != nil {
		panic(err)
	}

	// Copy object
	err = client.CopyObject(ctx, "users/1/avatar.png", "users/1/avatar-backup.png", nil)
	if err != nil {
		panic(err)
	}

	// Delete object
	err = client.DeleteObject(ctx, "users/1/avatar.png")
	if err != nil {
		panic(err)
	}
}

Benchmarks

BenchmarkAuthorize-12    454682    2785 ns/op    2848 B/op    25 allocs/op

License

MIT

Documentation

Index

• func EscapePath(key string) string
• func HashBody(body io.ReadSeeker) (sum []byte, length int64, err error)
• func SSECHeaders(keyBytes []byte) map[string]string
• type Client
  • func New(cfg Config) (*Client, error)
  • func (c *Client) Authorize(method, reqURL string, headers map[string]string, payloadHash string, ...) string
  • func (c *Client) CopyObject(ctx context.Context, srcKey, dstKey string, headers map[string]string) error
  • func (c *Client) DeleteObject(ctx context.Context, key string) error
  • func (c *Client) Do(ctx context.Context, method, key string, body io.ReadSeeker, ...) error
  • func (c *Client) ObjectURL(key string) string
  • func (c *Client) PutObject(ctx context.Context, key string, body io.ReadSeeker, contentType string, ...) error
  • func (c *Client) SigningKey(date string) []byte
• type Config
• type Error
  • func (e *Error) Error() string

Functions

func EscapePath

func EscapePath(key string) string

EscapePath percent-encodes key preserving '/' separators per SigV4 rules.

func HashBody

func HashBody(body io.ReadSeeker) (sum []byte, length int64, err error)

HashBody computes the SHA256 of body without buffering all content in heap memory, then seeks back to the starting offset.

func SSECHeaders

func SSECHeaders(keyBytes []byte) map[string]string

SSECHeaders returns standard S3 customer-provided encryption headers.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client executes S3-compatible API requests using AWS SigV4 signing.

func New

func New(cfg Config) (*Client, error)

New creates an initialized S3 client.

func (*Client) Authorize

func (c *Client) Authorize(method, reqURL string, headers map[string]string, payloadHash string, now time.Time) string

Authorize computes the Authorization header for a request.

func (*Client) CopyObject

func (c *Client) CopyObject(ctx context.Context, srcKey, dstKey string, headers map[string]string) error

CopyObject copies an object from srcKey to dstKey.

func (*Client) DeleteObject

func (c *Client) DeleteObject(ctx context.Context, key string) error

DeleteObject deletes an object key from the S3 bucket.

func (*Client) Do

func (c *Client) Do(ctx context.Context, method, key string, body io.ReadSeeker, contentType string, extraHeaders map[string]string) error

Do executes an S3 request with SigV4 authorization and retries on retryable errors.

func (*Client) ObjectURL

func (c *Client) ObjectURL(key string) string

ObjectURL returns the fully qualified URL for the object key.

func (*Client) PutObject

func (c *Client) PutObject(ctx context.Context, key string, body io.ReadSeeker, contentType string, headers map[string]string) error

PutObject uploads an object key to the S3 bucket.

func (*Client) SigningKey

func (c *Client) SigningKey(date string) []byte

SigningKey returns the derived signing key for a given scope date (YYYYMMDD). Results are cached across calls on the same date.

type Config

type Config struct {
	Endpoint     string // e.g. "https://s3.us-east-1.amazonaws.com" or "https://s3.us-west-004.backblazeb2.com"
	Region       string // e.g. "us-east-1"
	Bucket       string
	AccessKey    string
	SecretKey    string
	UsePathStyle bool // Set true for MinIO or path-style endpoints
	HTTPClient   *http.Client
}

Config defines connection coordinates and credentials for the S3 client.

type Error

type Error struct {
	Status  int
	Code    string
	Message string
}

Error represents an S3 XML error response.

func (*Error) Error

func (e *Error) Error() string