Skip to content

docs(FIL-5): comprehensive S3 compatibility matrix #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
RichardHerold wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(FIL-5): comprehensive S3 compatibility matrix #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
140 changes: 118 additions & 22 deletions docs/reference/s3-compatibility.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

<!-- PLACEHOLDER: Confirm final endpoint URL before launch -->

All requests use HTTPS. HTTP connections are rejected.

## Authentication
Expand All @@ -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

Expand All @@ -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. |
2 changes: 2 additions & 0 deletions sidebars.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ const sidebars = {
"storage/buckets",
"storage/objects",
"storage/multipart-uploads",
"storage/versioning",
"storage/object-lock",
],
},
{
Expand Down