How randilt/geckos3 works
GeckoS3 is a single-binary Go HTTP server that implements a subset of the S3 API and persists data to the local filesystem:
• Buckets ⇢ directories under a configurable data directory (-data-dir / GECKOS3_DATA_DIR)
• Objects ⇢ files inside bucket directories (nested keys create subdirectories)
• Object metadata ⇢ .metadata.json sidecar files
• Optional AWS Signature V4 auth (-auth / GECKOS3_AUTH_ENABLED)
• Designed for local dev/CI/single-node usage (explicitly not HA/clustered)
• an S3-compatible HTTP façade
• with auth middleware
• a request handler/router implementing S3 operations
• a storage layer mapping S3 semantics onto filesystem + metadata
• plus logging and health check concerns
• optionally containerized via Docker with a mounted volume
• main.go
Composition root: parses flags/env, constructs dependencies (auth/storage/logger), starts HTTP server on -listen / GECKOS3_LISTEN.
• handler.go
HTTP routing + S3 API implementation: endpoints listed in README (ListBuckets, PutObject, GetObject, ListObjectsV1/V2, etc.). Likely dispatches based on method/path/query.
• auth.go
SigV4 authentication/authorization middleware:
• validates header-signed requests
• validates presigned URLs
• bypass for GET /health (explicit requirement)
• storage.go
Persistence adapter: filesystem operations:
• create/delete bucket directories
• atomic writes (temp + fsync + rename)
• range reads
• copy semantics (via x-amz-copy-source)
• path traversal protection (keys escaping data dir rejected)
• metadata read/write to .metadata.json
• logging.go
Request logging: structured JSON logs to stdout (request_id, duration_ms, bytes, etc.)
• Tests:
• *_test.go, integration_test.go
• Deployment/build:
• Dockerfile, docker-compose.yml, Dockerfile.goreleaser, .goreleaser.yaml, Makefile
These become “deployment view” artifacts: container, port mapping, volume mount, healthcheck.
This repo strongly suggests a layered single-service design:
Cross-cutting middleware: auth + logging + health bypass
3. Application/endpoint layer: S3 operation handlers (request parsing, XML responses, headers)
Infrastructure: local disk / mounted volume
• Auth boundary: SigV4 verification is the “trust gate” for all S3 endpoints except /health
• Atomic write guarantee: temp file → fsync → rename (annotate on PutObject path)
• Path traversal protection: reject keys escaping data dir (annotate in Storage)
• Range reads: GetObject supports Range (annotate response path)
Given the README, accuracy hinges on capturing these specifics:
Endpoints
• S3 root: GET / (ListBuckets)
• Bucket ops: PUT/DELETE/HEAD /{bucket}, GET /{bucket} (ListObjects v1/v2)
• Object ops: PUT/GET/HEAD/DELETE /{bucket}/{key}
• POST /{bucket}?delete (DeleteObjects)
• Copy via PUT ... + x-amz-copy-source
• Health: GET /health (no auth)
Storage mapping
• “Bucket directory” and “Object file”
• “Sidecar metadata .metadata.json”
• “Nested keys create directories”
• “Atomic write” + “fsync”
• “Path traversal blocked”
Auth
• “AWS SigV4 (header + presigned URL)”
• “Can be disabled”
Logging
• “JSON logs to stdout”
• External actors (clients) = gray
• Runtime components (Go service internals) = blue
• Trust boundary line:
• An explicit boundary around “Authenticated S3 API”
• /health bypassing it
• Annotate key constraints directly on components (small callouts):
• “No multipart”, “single-node”, “no TLS built-in”