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.
- Admin dashboard for objects, wallet, tasks, topology, settings, and health.
- Docker Compose or source build for single-node deployments.
Coming soon: replica repair for provider outages.
Dashboard
Architecture
Writes commit to local cache and metadata before returning success. Reads use local cache first, then committed Filecoin copies when available.
Core S3 Compatibility
| Area | Operation | Status | Notes |
|---|---|---|---|
| Bucket | CreateBucket |
✅ | Creates a bucket |
| Bucket | HeadBucket |
✅ | Checks bucket metadata |
| Bucket | ListBuckets |
✅ | Lists active buckets |
| Bucket | DeleteBucket |
❌ | Bucket deletion is not supported |
| Bucket | GetBucketVersioning |
✅ | Buckets are always versioning-enabled |
| Bucket | PutBucketVersioning |
⚠️ | Accepts Enabled; Suspended is rejected |
| Object | PutObject |
✅ | Stores an object |
| Object | GetObject |
✅ | Reads an object |
| Object | HeadObject |
✅ | Reads object metadata |
| Object | DeleteObject |
✅ | Creates a delete marker without versionId; with versionId, deletes an eligible data version or delete marker |
| Object | DeleteObjects |
✅ | Applies the same deletion rules per entry and reports entry-specific failures |
| Object | CopyObject |
✅ | Source object must be readable from cache or committed Filecoin storage |
| Object | ListObjects |
✅ | Marker pagination |
| Object | ListObjectsV2 |
✅ | Continuation-token pagination |
| Object | ListObjectVersions |
✅ | Lists object versions and delete markers |
| Object | GetObjectAttributes |
✅ | Reports metadata and multipart ObjectParts; TotalPartsCount is not emitted |
| Multipart | CreateMultipartUpload |
✅ | Starts an upload |
| Multipart | UploadPart |
✅ | Uploads one part |
| Multipart | UploadPartCopy |
⚠️ | Whole-object copy only; range copy is not supported |
| Multipart | CompleteMultipartUpload |
✅ | Assembles parts |
| Multipart | AbortMultipartUpload |
✅ | Cancels an upload |
| Multipart | ListMultipartUploads |
✅ | Lists open uploads |
| Multipart | ListParts |
✅ | Lists uploaded parts |
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. |
|
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. |
|
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. |
|
testutil
Package testutil provides shared test infrastructure for SynapS3 packages.
|
Package testutil provides shared test infrastructure for SynapS3 packages. |
|
tests
|
|
Click to show internal directories.
Click to hide internal directories.