# S3 compatibility

The endpoint, addressing, region and signing the S3 API takes, the S3 operations it supports, and its limits.

## Endpoint

| Item                      | Value                                                                                                                                       |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Endpoint (path style)     | `https://s3.<domain>/<bucket>/<key>`                                                                                                        |
| Endpoint (virtual-hosted) | `https://<bucket>.s3.<domain>/<key>`, shown as the bucket's **Address**                                                                     |
| Region                    | the bucket's region (`de1`; `fi1` for `fi1a`), answered by HeadBucket in `x-amz-bucket-region`; a signature for any region name is accepted |
| Signing                   | AWS Signature Version 4, in a header or a presigned URL; uploads signed per chunk or with a trailing checksum are accepted                  |
| Clock skew                | a request more than 15 minutes off is refused with `RequestTimeTooSkewed`                                                                   |
| Presigned URL lifetime    | up to 604800 seconds (7 days)                                                                                                               |

Every bucket is reached at the same endpoint whatever its zone.

## Supported operations

| Area            | Operations                                                                                                                                                                                       |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Buckets         | ListBuckets, HeadBucket, GetBucketLocation (answers the zone)                                                                                                                                    |
| Listing         | ListObjectsV2; ListObjects (version 1) with `prefix`, `delimiter`, `max-keys`, `marker` and `encoding-type`; up to 1000 keys per request                                                         |
| Objects         | GetObject (ranges, `If-Match`, `If-None-Match`, `If-Modified-Since`, `If-Unmodified-Since`, `response-content-disposition`), HeadObject, PutObject, CopyObject, DeleteObject                     |
| Batch delete    | DeleteObjects, up to 1000 keys; an entry with a `VersionId` deletes that version for good and needs `s3:DeleteObjectVersion`                                                                     |
| Multipart       | CreateMultipartUpload, UploadPart, UploadPartCopy, CompleteMultipartUpload, AbortMultipartUpload, ListParts, ListMultipartUploads; part numbers 1–10000                                          |
| Tagging         | GetObjectTagging (always an empty set)                                                                                                                                                           |
| Bucket settings | Get, Put and Delete of the bucket policy, public access block, website, CORS, replication, encryption and lifecycle; Get and Put of versioning and object lock configuration; ListObjectVersions |
| Versions, locks | GET, HEAD and DELETE with `versionId`; object retention and legal hold                                                                                                                           |

Bucket settings can be changed only by the bucket's own organization. A bucket on a storage
cluster that was created without object lock shares a storage pool: changing its versioning,
lifecycle or object lock configuration the first time works only while it is still empty (the
bucket then gets storage of its own), and until then ListObjectVersions answers `NotImplemented`.

PutObject stores `Content-Type`, `Content-Encoding`, `Content-Disposition`, `Cache-Control` and
user metadata (`x-amz-meta-*`). Other headers, such as `x-amz-tagging` or
`x-amz-website-redirect-location`, are not stored.

## Limits

| Item                  | Value                                                                                                                                                                                                                 |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bucket names          | 3–63 characters; lowercase letters, digits, hyphens; start and end with a letter or digit; no dots; no two hyphens in a row; not starting with `xn-`; some names reserved (see [Create a bucket](create-a-bucket.md)) |
| Object key length     | up to 1024 bytes (`KeyTooLongError`)                                                                                                                                                                                  |
| Large objects         | upload with a multipart upload, parts numbered 1–10000                                                                                                                                                                |
| Bucket policy         | up to 20 KB                                                                                                                                                                                                           |
| CORS rules            | up to 100 per bucket                                                                                                                                                                                                  |
| Website routing rules | up to 50                                                                                                                                                                                                              |

## Answered differently from AWS

- CreateBucket: `BucketAlreadyOwnedByYou` for your own bucket, `BucketAlreadyExists` for another's,
  so tools that create a bucket "if needed" carry on; for a new name, `NotImplemented` saying to
  create it in the console, with `dcloud s3 buckets create` or the API. DeleteBucket answers
  `NotImplemented` the same way.
- ACLs: an upload with a public ACL (`x-amz-acl` other than `private` or
  `bucket-owner-full-control`, or any `x-amz-grant-*` header) is refused with
  `AccessControlListNotSupported`.
- `?acl`, `?notification`, `?logging`, `?accelerate`, `?requestPayment`, `?ownershipControls`,
  `?intelligent-tiering`, `?analytics`, `?metrics`, `?inventory`, `?restore`, `?select`,
  `?torrent`, `?attributes`, bucket tagging, setting object tags and POST object uploads answer
  `NotImplemented`.

## Related

- [Not supported](not-supported.md)
- [Troubleshooting](troubleshooting.md)
