garage/doc/book/src/reference_manual/s3_compatibility.md

# S3 Compatibility status

## Global S3 features

Implemented:

- path-style URLs (`garage.tld/bucket/key`)
- vhost-style URLs (`bucket.garage.tld/key`)
- putting and getting objects in buckets
- multipart uploads
- listing objects
- access control on a per-access-key-per-bucket basis
- CORS headers on web endpoint

Not implemented:

- object-level ACL
- [object versioning](https://git.deuxfleurs.fr/Deuxfleurs/garage/issues/166)
- encryption
- most `x-amz-` headers


## Endpoint implementation

All APIs that are not mentionned are not implemented and will return a 501 Not Implemented.

| Endpoint                     | Status                           |
|------------------------------|----------------------------------|
| AbortMultipartUpload         | Implemented                      |
| CompleteMultipartUpload      | Implemented                      |
| CopyObject                   | Implemented                      |
| CreateBucket                 | Implemented                      |
| CreateMultipartUpload        | Implemented                      |
| DeleteBucket                 | Implemented                      |
| DeleteBucketCors             | Implemented                      |
| DeleteBucketWebsite          | Implemented                      |
| DeleteObject                 | Implemented                      |
| DeleteObjects                | Implemented                      |
| GetBucketCors                | Implemented                      |
| GetBucketLocation            | Implemented                      |
| GetBucketVersioning          | Stub (see below)                 |
| GetBucketWebsite             | Implemented                      |
| GetObject                    | Implemented                      |
| HeadBucket                   | Implemented                      |
| HeadObject                   | Implemented                      |
| ListBuckets                  | Implemented                      |
| ListObjects                  | Implemented, bugs? (see below)   |
| ListObjectsV2                | Implemented                      |
| ListMultipartUpload          | Implemented                      |
| ListParts                    | Implemented                      |
| PutObject                    | Implemented                      |
| PutBucketCors                | Implemented                      |
| PutBucketWebsite             | Partially implemented (see below)|
| UploadPart                   | Implemented                      |
| UploadPartCopy               | Implemented                      |


- **GetBucketVersioning:** Stub implementation (Garage does not yet support versionning so this always returns
"versionning not enabled").

- **ListObjects:** Implemented, but there isn't a very good specification of what `encoding-type=url` covers so there might be some encoding bugs. In our implementation the url-encoded fields are in the same in ListObjects as they are in ListObjectsV2.

- **PutBucketWebsite:** Implemented, but only stores the index document suffix and the error document path. Redirects are not supported.
Write documentation on configuration file and other improvements 2021-05-28 16:00:59 +00:00			`# S3 Compatibility status`
Add compatibility list 2021-02-19 18:10:23 +00:00
Write documentation on configuration file and other improvements 2021-05-28 16:00:59 +00:00			`## Global S3 features`
Add compatibility list 2021-02-19 18:10:23 +00:00
			`Implemented:`

add precision 2021-02-19 18:11:55 +00:00			- path-style URLs (`garage.tld/bucket/key`)
update s3 compatibility list (#177) Co-authored-by: Trinity Pointard <trinity.pointard@gmail.com> Reviewed-on: https://git.deuxfleurs.fr/Deuxfleurs/garage/pulls/177 Co-authored-by: trinity-1686a <trinity.pointard@gmail.com> Co-committed-by: trinity-1686a <trinity.pointard@gmail.com> 2021-12-15 14:05:54 +00:00			- vhost-style URLs (`bucket.garage.tld/key`)
Add compatibility list 2021-02-19 18:10:23 +00:00			`- putting and getting objects in buckets`
			`- multipart uploads`
			`- listing objects`
Implement {Put,Get,Delete}BucketCors and CORS in general - OPTIONS request against API endpoint - Returning corresponding CORS headers on API calls - Returning corresponding CORS headers on website GET's 2022-01-07 15:23:04 +00:00			`- access control on a per-access-key-per-bucket basis`
			`- CORS headers on web endpoint`
Add compatibility list 2021-02-19 18:10:23 +00:00
			`Not implemented:`

			`- object-level ACL`
update s3 compatibility list (#177) Co-authored-by: Trinity Pointard <trinity.pointard@gmail.com> Reviewed-on: https://git.deuxfleurs.fr/Deuxfleurs/garage/pulls/177 Co-authored-by: trinity-1686a <trinity.pointard@gmail.com> Co-committed-by: trinity-1686a <trinity.pointard@gmail.com> 2021-12-15 14:05:54 +00:00			`- [object versioning](https://git.deuxfleurs.fr/Deuxfleurs/garage/issues/166)`
Add compatibility list 2021-02-19 18:10:23 +00:00			`- encryption`
			- most `x-amz-` headers


Write documentation on configuration file and other improvements 2021-05-28 16:00:59 +00:00			`## Endpoint implementation`
Add compatibility list 2021-02-19 18:10:23 +00:00
Implement UploadPartCopy 2022-01-11 16:31:09 +00:00			`All APIs that are not mentionned are not implemented and will return a 501 Not Implemented.`
Add compatibility list 2021-02-19 18:10:23 +00:00
Improve CLI, adapt tests, update documentation 2021-10-19 14:16:10 +00:00			`\| Endpoint \| Status \|`
			`\|------------------------------\|----------------------------------\|`
			`\| AbortMultipartUpload \| Implemented \|`
			`\| CompleteMultipartUpload \| Implemented \|`
			`\| CopyObject \| Implemented \|`
Update documentation 2022-01-07 16:14:37 +00:00			`\| CreateBucket \| Implemented \|`
Improve CLI, adapt tests, update documentation 2021-10-19 14:16:10 +00:00			`\| CreateMultipartUpload \| Implemented \|`
Update documentation 2022-01-07 16:14:37 +00:00			`\| DeleteBucket \| Implemented \|`
Implement {Put,Get,Delete}BucketCors and CORS in general - OPTIONS request against API endpoint - Returning corresponding CORS headers on API calls - Returning corresponding CORS headers on website GET's 2022-01-07 15:23:04 +00:00			`\| DeleteBucketCors \| Implemented \|`
update s3 compatibility list (#177) Co-authored-by: Trinity Pointard <trinity.pointard@gmail.com> Reviewed-on: https://git.deuxfleurs.fr/Deuxfleurs/garage/pulls/177 Co-authored-by: trinity-1686a <trinity.pointard@gmail.com> Co-committed-by: trinity-1686a <trinity.pointard@gmail.com> 2021-12-15 14:05:54 +00:00			`\| DeleteBucketWebsite \| Implemented \|`
Improve CLI, adapt tests, update documentation 2021-10-19 14:16:10 +00:00			`\| DeleteObject \| Implemented \|`
			`\| DeleteObjects \| Implemented \|`
Implement {Put,Get,Delete}BucketCors and CORS in general - OPTIONS request against API endpoint - Returning corresponding CORS headers on API calls - Returning corresponding CORS headers on website GET's 2022-01-07 15:23:04 +00:00			`\| GetBucketCors \| Implemented \|`
Improve CLI, adapt tests, update documentation 2021-10-19 14:16:10 +00:00			`\| GetBucketLocation \| Implemented \|`
			`\| GetBucketVersioning \| Stub (see below) \|`
Update documentation 2022-01-07 16:13:16 +00:00			`\| GetBucketWebsite \| Implemented \|`
Improve CLI, adapt tests, update documentation 2021-10-19 14:16:10 +00:00			`\| GetObject \| Implemented \|`
			`\| HeadBucket \| Implemented \|`
			`\| HeadObject \| Implemented \|`
			`\| ListBuckets \| Implemented \|`
			`\| ListObjects \| Implemented, bugs? (see below) \|`
			`\| ListObjectsV2 \| Implemented \|`
Implement ListMultipartUploads (#171) Implement ListMultipartUploads, also refactor ListObjects and ListObjectsV2. It took me some times as I wanted to propose the following things: - Using an iterator instead of the loop+goto pattern. I find it easier to read and it should enable some optimizations. For example, when consuming keys of a common prefix, we do many [redundant checks](https://git.deuxfleurs.fr/Deuxfleurs/garage/src/branch/main/src/api/s3_list.rs#L125-L156) while the only thing to do is to [check if the following key is still part of the common prefix](https://git.deuxfleurs.fr/Deuxfleurs/garage/src/branch/feature/s3-multipart-compat/src/api/s3_list.rs#L476). - Try to name things (see ExtractionResult and RangeBegin enums) and to separate concerns (see ListQuery and Accumulator) - An IO closure to make unit tests possibles. - Unit tests, to track regressions and document how to interact with the code - Integration tests with `s3api`. In the future, I would like to move them in Rust with the aws rust SDK. Merging of the logic of ListMultipartUploads and ListObjects was not a goal but a consequence of the previous modifications. Some points that we might want to discuss: - ListObjectsV1, when using pagination and delimiters, has a weird behavior (it lists multiple times the same prefix) with `aws s3api` due to the fact that it can not use our optimization to skip the whole prefix. It is independant from my refactor and can be tested with the commented `s3api` tests in `test-smoke.sh`. It probably has the same weird behavior on the official AWS S3 implementation. - Considering ListMultipartUploads, I had to "abuse" upload id marker to support prefix skipping. I send an `upload-id-marker` with the hardcoded value `include` to emulate your "including" token. - Some ways to test ListMultipartUploads with existing software (my tests are limited to s3api for now). Co-authored-by: Quentin Dufour <quentin@deuxfleurs.fr> Reviewed-on: https://git.deuxfleurs.fr/Deuxfleurs/garage/pulls/171 Co-authored-by: Quentin <quentin@dufour.io> Co-committed-by: Quentin <quentin@dufour.io> 2022-01-12 18:04:55 +00:00			`\| ListMultipartUpload \| Implemented \|`
Test ListParts endpoint with awscli 2022-01-20 15:38:28 +00:00			`\| ListParts \| Implemented \|`
Improve CLI, adapt tests, update documentation 2021-10-19 14:16:10 +00:00			`\| PutObject \| Implemented \|`
Implement {Put,Get,Delete}BucketCors and CORS in general - OPTIONS request against API endpoint - Returning corresponding CORS headers on API calls - Returning corresponding CORS headers on website GET's 2022-01-07 15:23:04 +00:00			`\| PutBucketCors \| Implemented \|`
update s3 compatibility list (#177) Co-authored-by: Trinity Pointard <trinity.pointard@gmail.com> Reviewed-on: https://git.deuxfleurs.fr/Deuxfleurs/garage/pulls/177 Co-authored-by: trinity-1686a <trinity.pointard@gmail.com> Co-committed-by: trinity-1686a <trinity.pointard@gmail.com> 2021-12-15 14:05:54 +00:00			`\| PutBucketWebsite \| Partially implemented (see below)\|`
Improve CLI, adapt tests, update documentation 2021-10-19 14:16:10 +00:00			`\| UploadPart \| Implemented \|`
Implement UploadPartCopy 2022-01-11 16:31:09 +00:00			`\| UploadPartCopy \| Implemented \|`
Improve CLI, adapt tests, update documentation 2021-10-19 14:16:10 +00:00

			`- GetBucketVersioning: Stub implementation (Garage does not yet support versionning so this always returns`
Updates to documentation 2021-05-31 15:23:35 +00:00			`"versionning not enabled").`

Improve CLI, adapt tests, update documentation 2021-10-19 14:16:10 +00:00			- ListObjects: Implemented, but there isn't a very good specification of what `encoding-type=url` covers so there might be some encoding bugs. In our implementation the url-encoded fields are in the same in ListObjects as they are in ListObjectsV2.
Add compatibility list 2021-02-19 18:10:23 +00:00
Update documentation 2022-01-07 16:13:16 +00:00			`- PutBucketWebsite: Implemented, but only stores the index document suffix and the error document path. Redirects are not supported.`
update s3 compatibility list (#177) Co-authored-by: Trinity Pointard <trinity.pointard@gmail.com> Reviewed-on: https://git.deuxfleurs.fr/Deuxfleurs/garage/pulls/177 Co-authored-by: trinity-1686a <trinity.pointard@gmail.com> Co-committed-by: trinity-1686a <trinity.pointard@gmail.com> 2021-12-15 14:05:54 +00:00