9f786b3c2c
Fixes #2123 Fixes #2120 Fixes #2116 Fixes #2111 Fixes #2108 Fixes #2086 Fixes #2085 Fixes #2083 Fixes #2081 Fixes #2080 Fixes #2073 Fixes #2072 Fixes #2071 Fixes #2069 Fixes #2044 Fixes #2043 Fixes #2042 Fixes #2041 Fixes #2040 Fixes #2039 Fixes #2036 Fixes #2035 Fixes #2034 Fixes #2028 Fixes #2020 Fixes #1842 Fixes #1810 Fixes #1780 Fixes #1775 Fixes #1736 Fixes #1705 Fixes #1663 Fixes #1645 Fixes #1583 Fixes #1526 Fixes #1514 Fixes #1493 Fixes #1487 Fixes #959 Fixes #779 Closes #823 Closes #85 Refactor global S3 error handling around structured error types and centralized XML response generation. All S3 errors now share the common APIError base for the fields every error has: Code, HTTP status code, and Message. Non-traditional errors that need AWS-compatible XML fields now have dedicated typed errors in the s3err package. Each typed error implements the shared S3Error behavior so controllers and middleware can handle errors consistently while still emitting error-specific XML fields. Add a dedicated InvalidArgumentError type because InvalidArgument is used widely across request validation, auth, copy source handling, object lock validation, multipart validation, and header parsing. The new InvalidArgument path uses explicit InvalidArgErrorCode constants with predefined descriptions and ArgumentName values, keeping call sites readable while preserving the correct InvalidArgument XML shape and optional ArgumentValue. New structured errors added in s3err: - `AccessForbiddenError`: Method, ResourceType - `BadDigestError`: CalculatedDigest, ExpectedDigest - `BucketError`: BucketName - `ContentSHA256MismatchError`: ClientComputedContentSHA256, S3ComputedContentSHA256 - `EntityTooLargeError`: ProposedSize, MaxSizeAllowed - `EntityTooSmallError`: ProposedSize, MinSizeAllowed - `ExpiredPresignedURLError`: ServerTime, XAmzExpires, Expires - `InvalidAccessKeyIdError`: AWSAccessKeyId - `InvalidArgumentError`: Description, ArgumentName, ArgumentValue - `InvalidChunkSizeError`: Chunk, BadChunkSize - `InvalidDigestError`: ContentMD5 - `InvalidLocationConstraintError`: LocationConstraint - `InvalidPartError`: UploadId, PartNumber, ETag - `InvalidRangeError`: RangeRequested, ActualObjectSize - `InvalidTagError`: TagKey, TagValue - `KeyTooLongError`: Size, MaxSizeAllowed - `MetadataTooLargeError`: Size, MaxSizeAllowed - `MethodNotAllowedError`: Method, ResourceType, AllowedMethods - `NoSuchUploadError`: UploadId - `NoSuchVersionError`: Key, VersionId - `NotImplementedError`: Header, AdditionalMessage - `PreconditionFailedError`: Condition - `RequestTimeTooSkewedError`: RequestTime, ServerTime, MaxAllowedSkewMilliseconds - `SignatureDoesNotMatchError`: AWSAccessKeyId, StringToSign, SignatureProvided, StringToSignBytes, CanonicalRequest, CanonicalRequestBytes Fix CompleteMultipartUpload validation in the Azure backend so missing or empty `ETag` values return the appropriate S3 error instead of allowing a gateway panic. Fix presigned authentication expiration validation to compare server time in `UTC`, matching the `UTC` timestamp used by presigned URL signing. Add request ID and host ID support across S3 requests. Each request now receives AWS S3-like identifiers, returned in response headers as `x-amz-request-id` and `x-amz-id-2` and included in all XML error responses as RequestId and HostId. The generated ID structure is designed to resemble AWS S3 request IDs and host IDs. The request signature calculation/validation for streaming uploads was previously delayed until the request body was fully read, both for Authorization header authentication and presigned URLs. Now, the signature is validated immediately in the authorization middlewares without reading the request body, since the signature calculation itself does not depend on the request body. Instead, only the `x-amz-content-sha256` SHA-256 hash calculation is delayed.
The Versity S3 Gateway:
A High-Performance S3 Translation Service
Binary release builds
Download latest release
| Linux/amd64 | Linux/arm64 | MacOS/amd64 | MacOS/arm64 | BSD/amd64 | BSD/arm64 |
|---|---|---|---|---|---|
| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
Use Cases
- Turn your local filesystem into an S3 server with a single command!
- Proxy S3 requests to S3 storage
- Simple to deploy S3 server with a single command
- Protocol compatibility in
posixallows common access to files via posix or S3 - Simplified interface for adding new storage system support
WebGUI
Get more details about the new (optional) WebGUI management/explorer here: https://github.com/versity/versitygw/wiki/WebGUI
News
Check out latest wiki articles: https://github.com/versity/versitygw/wiki/Articles
Mailing List
Keep up to date with latest gateway announcements by signing up to the versitygw mailing list.
Documentation
See project documentation on the wiki.
Need help?
Ask questions in the community discussions.
Contact Versity Sales to discuss enterprise support.
Overview
Versity Gateway, a simple to use tool for seamless inline translation between AWS S3 object commands and storage systems. The Versity Gateway bridges the gap between S3-reliant applications and other storage systems, enabling enhanced compatibility and integration while offering exceptional scalability.
The server translates incoming S3 API requests and transforms them into equivalent operations to the backend service. By leveraging this gateway server, applications can interact with the S3-compatible API on top of already existing storage systems. This project enables leveraging existing infrastructure investments while seamlessly integrating with S3-compatible systems, offering increased flexibility and compatibility in managing data storage.
The Versity Gateway is focused on performance, simplicity, and expandability. The Versity Gateway is designed with modularity in mind, enabling future extensions to support additional backend storage systems. At present, the Versity Gateway supports any generic POSIX file backend storage, Versity’s open source ScoutFS filesystem, Azure Blob Storage, and other S3 servers.
The gateway is completely stateless. Multiple Versity Gateway instances may be deployed in a cluster to increase aggregate throughput. The Versity Gateway’s stateless architecture allows any request to be serviced by any gateway thereby distributing workloads and enhancing performance. Load balancers may be used to evenly distribute requests across the cluster of gateways for optimal performance.
The S3 HTTP(S) server and routing is implemented using the Fiber web framework. This framework is actively developed with a focus on performance. S3 API compatibility leverages the official aws-sdk-go-v2 whenever possible for maximum service compatibility with AWS S3.
Getting Started
See the Quickstart documentation.
Run the gateway with posix backend:
mkdir /tmp/vgw /tmp/vers
ROOT_ACCESS_KEY="testuser" ROOT_SECRET_KEY="secret" ./versitygw --port :10000 --iam-dir /tmp/vgw posix --versioning-dir /tmp/vers /tmp/vgw
This will enable an S3 server on the current host listening on port 10000 and hosting the directory /tmp/vgw with older object versions in /tmp/vers. It's fine if both of these directories are within the same filesystem. The --iam-dir option enables simple JSON flat file accounts for testing.
To get the usage output, run the following:
./versitygw --help
The command format is
versitygw [global options] command [command options] [arguments...]
The global options are specified before the backend type and the backend options are specified after.
Testing & Production Readiness
VersityGW is battle-tested and production-ready. Every pull request must pass our comprehensive test suite before it can be reviewed or merged. All code reviews are done by at least one human in the loop. LLMs may be used to augment the review process, but are never the sole reviewer or decision maker. See Testing for high level testing documentation.
Comprehensive Test Coverage
Our multi-layered testing strategy includes:
- Go Unit Test Files - Extensive unit tests with race detection and code coverage analysis covering core functionality, edge cases, and error handling.
- Integration Test Scripts - Real-world scenario testing across multiple backends (POSIX, S3, Azure) and configurations.
- Functional/Regression Tests - End-to-end SDK tests validating complete workflows including full-flow operations, POSIX-specific behavior, and IAM functionality populated with regression tests as issues are addressed.
- Static Analysis - Static Analysis checks using staticcheck.
- System Tests - Protocol-level validation using industry-standard S3 clients:
- AWS CLI - Official AWS command-line tools
- s3cmd - Popular S3 client
- Direct REST API testing with curl for request/response validation
- Security Testing - Both HTTP and HTTPS configurations tested. Vulnerability scanning with govulncheck. And regular dependency updates with dependabot.
- Compatibility Testing - Multiple backends, versioning scenarios, static bucket modes, and various authentication methods.
Run the gateway in Docker
Use the published image like the native binary by passing CLI arguments:
docker run --rm versity/versitygw:latest --version
See Docker for more documentation for running within Docker.
Run on Kubernetes
A Helm chart is provided to easily run Versity in Kubernetes environments:
helm install versitygw oci://ghcr.io/versity/versitygw/charts/versitygw
Please refer to the chart's README for more information and configuration parameters.
Versity gives you clarity and control over your archival storage, so you can allocate more resources to your core mission.
Contact
info@versity.com
+1 844 726 8826
@versitysoftware
