diff --git a/docs/reference/s3-compatibility.mdx b/docs/reference/s3-compatibility.mdx index 7245bb9..e4eedd5 100644 --- a/docs/reference/s3-compatibility.mdx +++ b/docs/reference/s3-compatibility.mdx @@ -11,8 +11,6 @@ Fil One provides an S3-compatible API. If your application works with AWS S3, it https://eu-west-1.s3.fil.one ``` - - All requests use HTTPS. HTTP connections are rejected. ## Authentication @@ -37,45 +35,139 @@ Fil One supports **AWS Signature Version 4 (SigV4)** authentication. Any S3 clie | `DeleteBucket` | ✅ Supported | Bucket must be empty first. Returns `BucketNotEmpty` if objects remain. | | `ListBuckets` | ✅ Supported | | | `HeadBucket` | ✅ Supported | | +| `GetBucketVersioning` | ✅ Supported | Always returns `Enabled`. Versioning is always on and cannot be disabled. | +| `PutBucketVersioning` | ⚠️ Partial | Accepted for SDK compatibility. Versioning cannot be suspended or disabled — suspend requests are rejected. | +| `GetBucketObjectLockConfiguration` | ✅ Supported | Returns the bucket-level default retention policy, if set. | +| `PutBucketObjectLockConfiguration` | ✅ Supported | Sets the default retention policy (Compliance mode). | +| `GetBucketEncryption` | ✅ Supported | Returns the default SSE-KMS (AES-256) configuration. | +| `PutBucketEncryption` | ⚠️ No-op | Encryption cannot be modified or disabled. Accepted for SDK compatibility but has no effect. | +| `GetBucketAcl` | ❌ Not supported | ACL model is not implemented. See [ACLs](#acls). | +| `PutBucketAcl` | ❌ Not supported | ACL model is not implemented. | +| `GetBucketPolicy` | ❌ Not supported | Bucket policies are not implemented. | +| `PutBucketPolicy` | ❌ Not supported | Bucket policies are not implemented. | +| `GetBucketLifecycleConfiguration` | ❌ Not supported | Planned for a future release. | +| `PutBucketLifecycleConfiguration` | ❌ Not supported | Planned for a future release. | +| `GetBucketNotificationConfiguration` | ❌ Not supported | Event notifications are not supported. | +| `PutBucketNotificationConfiguration` | ❌ Not supported | Event notifications are not supported. | +| `GetBucketTagging` | ❌ Not supported | Bucket and object tagging are not implemented. | +| `PutBucketTagging` | ❌ Not supported | Bucket and object tagging are not implemented. | ### Object operations | Operation | Status | Notes | |-----------|--------|-------| | `PutObject` | ✅ Supported | Max object size: 5 TB (use multipart for objects > 5 GB). | -| `GetObject` | ✅ Supported | | -| `DeleteObject` | ✅ Supported | | +| `GetObject` | ✅ Supported | Supports range requests (`Range` header). Supports `VersionId` to retrieve a specific version. | +| `DeleteObject` | ✅ Supported | Creates a delete marker on versioned buckets. Pass `VersionId` to permanently delete a specific version. | +| `DeleteObjects` | ✅ Supported | Bulk delete up to 1,000 objects per request. | | `HeadObject` | ✅ Supported | | | `ListObjectsV2` | ✅ Supported | | -| `CopyObject` | ✅ Supported | | +| `ListObjectVersions` | ✅ Supported | Returns all versions and delete markers. Supports `Prefix` and `KeyMarker` filters. | +| `CopyObject` | ✅ Supported | Supports `x-amz-copy-source-version-id` to copy a specific version. | +| `GetObjectRetention` | ✅ Supported | Returns the Object Lock Compliance retention for a specific version. | +| `PutObjectRetention` | ✅ Supported | Sets Compliance retention on a specific version. Retention can be extended but not shortened. | +| `GetObjectLegalHold` | ❌ Not supported | Planned for a future release. | +| `PutObjectLegalHold` | ❌ Not supported | Planned for a future release. | +| `GetObjectAcl` | ❌ Not supported | ACL model is not implemented. | +| `PutObjectAcl` | ❌ Not supported | ACL model is not implemented. | +| `GetObjectTagging` | ❌ Not supported | Object tagging is not implemented. | +| `PutObjectTagging` | ❌ Not supported | Object tagging is not implemented. | +| `RestoreObject` | ❌ Not applicable | Fil One has a single storage class. There are no archival tiers to restore from. | +| `SelectObjectContent` | ❌ Not planned | S3 Select is not planned. | ### Multipart upload | Operation | Status | Notes | |-----------|--------|-------| | `CreateMultipartUpload` | ✅ Supported | | -| `UploadPart` | ✅ Supported | | -| `CompleteMultipartUpload` | ✅ Supported | | +| `UploadPart` | ✅ Supported | Minimum part size: 5 MB (except last part). Maximum: 5 GB. | +| `CompleteMultipartUpload` | ✅ Supported | Maximum 10,000 parts per upload. | | `AbortMultipartUpload` | ✅ Supported | | +| `ListParts` | ✅ Supported | | +| `ListMultipartUploads` | ✅ Supported | | + +### Versioning + +Versioning is **always enabled** on every Fil One bucket. It cannot be suspended or disabled. Every upload to an existing key creates a new version rather than overwriting. + +| Operation | Status | Notes | +|-----------|--------|-------| +| `GetBucketVersioning` | ✅ Supported | Always returns `Enabled`. | +| `ListObjectVersions` | ✅ Supported | Lists all versions and delete markers in a bucket. | +| `GetObject` with `VersionId` | ✅ Supported | Retrieves a specific historical version by ID. | +| `DeleteObject` with `VersionId` | ✅ Supported | Permanently deletes a specific version, bypassing delete markers. | +| `CopyObject` with `x-amz-copy-source-version-id` | ✅ Supported | Copies a specific version to restore or duplicate it. | +| `PutBucketVersioning` (suspend) | ❌ Rejected | Versioning is always on. Suspend requests return an error. | + +See [Versioning](/storage/versioning) for detailed usage and examples. + +### Object Lock + +Object Lock enforces WORM (Write-Once-Read-Many) protection. Compliance mode is supported. Governance mode and Legal Hold are planned for a future release. + +| Operation | Status | Notes | +|-----------|--------|-------| +| `GetBucketObjectLockConfiguration` | ✅ Supported | Returns the bucket-level default retention policy. | +| `PutBucketObjectLockConfiguration` | ✅ Supported | Sets the default retention (Compliance mode, 1 day – 10 years). | +| `GetObjectRetention` | ✅ Supported | Returns the Compliance retention for a specific object version. | +| `PutObjectRetention` | ✅ Supported | Sets or extends Compliance retention on a version. Cannot be shortened. | +| `GetObjectLegalHold` | ❌ Not supported | Planned for a future release. | +| `PutObjectLegalHold` | ❌ Not supported | Planned for a future release. | + +**Object Lock modes:** + +| Mode | Status | +|------|--------| +| Compliance | ✅ Supported — no user, including the account owner, can delete a locked object or shorten its retention. | +| Governance | ❌ Not supported — planned for a future release. | + +See [Object Lock](/storage/object-lock) for compliance use cases, retention configuration, and examples. ### Presigned URLs | Operation | Status | Notes | |-----------|--------|-------| -| Presigned `GetObject` | ✅ Supported | | -| Presigned `PutObject` | ✅ Supported | | +| Presigned `GetObject` | ✅ Supported | Generate time-limited download URLs without requiring API credentials. | +| Presigned `PutObject` | ✅ Supported | Generate time-limited upload URLs for direct client or browser uploads. | + +### Server-side encryption + +Encryption is **always enabled** on every Fil One bucket. There is nothing to configure. + +| Feature | Status | Notes | +|---------|--------|-------| +| SSE-KMS (AES-256) | ✅ Always on | All objects are encrypted at rest with AES-256. Applied automatically — no headers required. | +| Encryption in transit (TLS) | ✅ Always on | All API connections use HTTPS. HTTP is rejected. | +| `GetBucketEncryption` | ✅ Supported | Returns the default SSE-KMS (AES-256) configuration. | +| `PutBucketEncryption` | ⚠️ No-op | Accepted for SDK compatibility. Encryption cannot be modified or disabled. | +| SSE-C (customer-provided keys) | ❌ Not supported | Key management is handled by Fil One infrastructure. | +| Client-side encryption | ✅ Optional | Encrypt data before upload using AWS SDK encryption utilities. Server-side AES-256 is still applied on top. | + +See [Encryption](/security/encryption) for details. + +## ACLs + +The S3 ACL model is **not supported**. Fil One does not implement bucket or object ACLs, bucket policies, or public access controls. All access requires SigV4 authentication. + +If your application passes ACL flags (e.g. `--acl public-read` in the AWS CLI, or `ACL: 'public-read'` in SDK calls), those flags are silently ignored — the request succeeds but no ACL is applied. -### Not yet supported +Per-bucket access control via API key scoping is planned for a future release. -The following operations are planned for future releases: +## Not yet supported -| Operation | Timeline | Notes | -|-----------|----------|-------| -| Bucket policies / ACLs | Phase 2 | | -| Lifecycle rules | Phase 2 | | +| Feature | Timeline | Notes | +|---------|----------|-------| +| Lifecycle rules (expiration, transitions) | Phase 2 | Planned. Affects archival and cleanup workflows. | +| Event notifications (SNS/SQS/Lambda triggers) | Phase 2 | Planned. | +| Object and bucket tagging | Phase 2 | Planned. | +| Object Lock: Governance mode | Phase 2 | Compliance mode is supported today. | +| Object Lock: Legal Hold | Phase 2 | Planned. | +| Multi-region (`us-east-1`, etc.) | Phase 2 | `eu-west-1` only today. | +| IAM / multi-user accounts / RBAC | Phase 2 | Single-user accounts only. | | S3 Select | Not planned | | | S3 Inventory | Not planned | | | S3 Batch Operations | Not planned | | +| Multiple storage classes | Not planned | Single storage class. | ## Error responses @@ -98,10 +190,14 @@ See the [Error Reference](/reference/errors) for a full list of error codes. Fil One is S3-compatible, not an S3 clone. A few behaviors differ: | Behavior | AWS S3 | Fil One | -|----------|--------|----------------| -| Bucket deletion | Requires bucket to be empty first. | Same — bucket must be empty. Returns `BucketNotEmpty` if objects remain. | -| IAM policies | Full IAM support. | Single-user accounts in the current release. IAM planned for a future release. | -| Public access | Configurable public bucket policies and ACLs. | No public bucket ACLs or public access settings. All access requires authentication. | -| Lifecycle rules | Supported (expiration, transitions, etc.). | Not supported in the current release. Planned for a future release. Affects common archival and cleanup workflows. | -| Storage classes | Multiple (Standard, IA, Glacier, etc.) | Single storage class. | -| Regions | 30+ regions globally. | `eu-west-1` (additional regions planned). | +|----------|--------|---------| +| Versioning | Configurable — can be enabled, suspended, or left off per bucket. | Always enabled on every bucket. Cannot be suspended or disabled. | +| Encryption | Optional and configurable. Off by default for older buckets. | Always on (AES-256 SSE-KMS). Cannot be disabled. | +| Bucket deletion | Requires an empty bucket. | Same. Returns `BucketNotEmpty` if objects remain. | +| IAM and policies | Full IAM with users, roles, and bucket policies. | Single-user accounts. No IAM or bucket policies. Key-based auth only. | +| Public access | Configurable via ACLs and bucket policies. | No public access. All requests require authentication. | +| Lifecycle rules | Supported (expiration, storage class transitions). | Not supported. Planned for a future release. | +| Object Lock modes | Compliance and Governance. | Compliance only. Governance and Legal Hold planned. | +| Storage classes | Multiple (Standard, IA, Glacier, etc.). | Single storage class. | +| Regions | 30+ globally. | `eu-west-1` only. Additional regions planned. | +| Data retention after deletion | Object is immediately and permanently deleted. | Object is immediately inaccessible in Fil One, but the underlying Filecoin storage deals persist up to 180 days until natural sector expiration. | diff --git a/sidebars.js b/sidebars.js index c5f36e7..b27c3b3 100644 --- a/sidebars.js +++ b/sidebars.js @@ -19,6 +19,8 @@ const sidebars = { "storage/buckets", "storage/objects", "storage/multipart-uploads", + "storage/versioning", + "storage/object-lock", ], }, {