README
¶
SynapS3
SynapS3 is an open-source, self-hosted S3-compatible gateway for Filecoin storage.
Documentation
Highlights
- S3-compatible bucket, object, versioning, and multipart APIs.
- Cache-first reads and writes, with Filecoin upload handled in the background.
- Dashboard, Admin API, and CLI for buckets, objects, wallet, tasks, storage providers, settings, and health.
- Single-node deployment with Docker Compose or a source build.
Coming soon: replica repair for storage provider outages.
Dashboard
Architecture
A write returns success after the object is stored in the local cache and its metadata is committed. Reads use the local cache first, then a committed Filecoin replica.
Core S3 Compatibility
Clients must use path-style addressing. Objects must be 127 to 1,065,353,216 bytes.
| Area | Operation | Status | Notes |
|---|---|---|---|
| Bucket | CreateBucket |
✅ | |
| Bucket | HeadBucket |
✅ | |
| Bucket | ListBuckets |
✅ | |
| Bucket | DeleteBucket |
❌ | Returns 501 NotImplemented. |
| Bucket | GetBucketVersioning |
✅ | Buckets are always versioning-enabled. |
| Bucket | PutBucketVersioning |
⚠️ | Accepts Enabled; rejects Suspended. |
| Bucket ACL | GetBucketAcl |
✅ | |
| Bucket ACL | PutBucketAcl |
✅ | Grants are enforced; see Access Control. |
| Object ACL | GetObjectAcl, PutObjectAcl |
❌ | |
| Bucket policy | GetBucketPolicy, PutBucketPolicy, DeleteBucketPolicy |
❌ | Policies are not stored or enforced. |
| Bucket tagging | GetBucketTagging, PutBucketTagging, DeleteBucketTagging |
❌ | |
| Object tagging | GetObjectTagging, PutObjectTagging, DeleteObjectTagging |
❌ | |
| Ownership controls | GetBucketOwnershipControls |
⚠️ | Reports BucketOwnerPreferred. |
| Ownership controls | PutBucketOwnershipControls |
⚠️ | Accepts only BucketOwnerPreferred. |
| Ownership controls | DeleteBucketOwnershipControls |
⚠️ | The bucket keeps BucketOwnerPreferred. |
| Object | PutObject |
✅ | |
| Object | GetObject |
✅ | Supports a single byte range. A range read of an object that is not cached downloads the whole object from the storage provider. |
| Object | HeadObject |
✅ | Returns custom metadata of the requested version. |
| Object | DeleteObject |
✅ | See Versioning and Deletion. |
| Object | DeleteObjects |
✅ | 1 to 1,000 keys. Reports failures per key; Quiet=true omits successful keys. |
| Object | CopyObject |
✅ | The source must be in the cache or have a committed replica. |
| Object | ListObjects |
✅ | Marker pagination. |
| Object | ListObjectsV2 |
✅ | Continuation-token pagination. |
| Object | ListObjectVersions |
✅ | Lists versions and delete markers. |
| Object | GetObjectAttributes |
⚠️ | Returns ObjectParts for multipart objects without TotalPartsCount. |
| Multipart | CreateMultipartUpload |
✅ | |
| Multipart | UploadPart |
✅ | |
| Multipart | UploadPartCopy |
⚠️ | Whole-object copy only; a source range returns NotImplemented. |
| Multipart | CompleteMultipartUpload |
✅ | |
| Multipart | AbortMultipartUpload |
✅ | |
| Multipart | ListMultipartUploads |
✅ | |
| Multipart | ListParts |
✅ |
Server-side encryption is not supported; requests with customer-provided keys (SSE-C) return 501 NotImplemented.
Details are in the S3 Compatibility reference. Per-operation and client results are in the S3 Compatibility workflow runs on main.
License
See LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
synaps3
command
|
|
|
internal
|
|
|
app
Package app owns the production application composition and lifecycle.
|
Package app owns the production application composition and lifecycle. |
|
errtext
Package errtext prepares error text for persisted error fields, which the Admin API shows to operators unchanged.
|
Package errtext prepares error text for persisted error fields, which the Admin API shows to operators unchanged. |
|
observability
Package observability owns the boundary between collected storage facts and product-facing health signals.
|
Package observability owns the boundary between collected storage facts and product-facing health signals. |
|
providerselect
Package providerselect defines provider admission and ranking without I/O.
|
Package providerselect defines provider admission and ranking without I/O. |
|
storagecleanup
Package storagecleanup owns durable cleanup task inputs.
|
Package storagecleanup owns durable cleanup task inputs. |
|
storagepipeline
Package storagepipeline owns the workflow-neutral storage task inputs.
|
Package storagepipeline owns the workflow-neutral storage task inputs. |
|
storagepull
Package storagepull owns the ledger of provider-side copy attempts.
|
Package storagepull owns the ledger of provider-side copy attempts. |
|
storagereplacement
Package storagereplacement owns the operator-approved provider replacement record: its state machine, wait reasons, stable API codes, and task payload contract.
|
Package storagereplacement owns the operator-approved provider replacement record: its state machine, wait reasons, stable API codes, and task payload contract. |
|
systemtask
Package systemtask names recurring built-in tasks.
|
Package systemtask names recurring built-in tasks. |
|
testpg
Package testpg provides isolated PostgreSQL schemas for tests and the system-test server.
|
Package testpg provides isolated PostgreSQL schemas for tests and the system-test server. |
|
testutil
Package testutil provides shared test infrastructure for SynapS3 packages.
|
Package testutil provides shared test infrastructure for SynapS3 packages. |
|
walletoperation
Package walletoperation owns wallet task inputs and recovery checkpoints.
|
Package walletoperation owns wallet task inputs and recovery checkpoints. |
|
worker
Package task owns the workflow-neutral task contract and execution engine.
|
Package task owns the workflow-neutral task contract and execution engine. |
|
tests
|
|
Click to show internal directories.
Click to hide internal directories.