Skip to content

filecoin-storage-flow.md

Latest commit

 

History

History
78 lines (55 loc) · 4.47 KB

filecoin-storage-flow.md

File metadata and controls

78 lines (55 loc) · 4.47 KB
Raw
title Filecoin Storage Flow
description Understand how background tasks store locally durable objects with Filecoin storage providers.

Filecoin Storage Flow

Filecoin storage starts after the S3 write is accepted. Background tasks read locally durable objects, store them with storage providers, and record the resulting remote copies.

Task Chain

flowchart TD
  put["S3 write accepted"] --> cached["cached"]
  cached --> uploading["uploading"]
  uploading --> committing["committing"]
  committing --> replicating["replicating"]
  replicating --> stored["stored"]
  stored --> policy{"cache eviction policy"}
  policy -->|"after_upload"| evict["queue after-upload eviction"]
  policy -->|"lru at high watermark"| evict
  policy -->|"none"| retain["retain local cache"]
  evict --> evicted["cache_evicted"]
Loading

Object States

State Meaning
cached Object is durable locally and queued for upload.
uploading A background task is preparing remote storage or uploading bytes.
committing The provider has a piece ready and the commit step is in progress.
replicating At least one readable committed copy exists, but the bucket's minimum durable copies are not yet met.
stored The bucket's minimum durable copies are readable and committed; remaining target copies may still be syncing.
failed The active lifecycle step failed and may be retried.
cache_evicted Local cache has been removed after remote durability.

Retries and Recovery

If SynapS3 is interrupted, unfinished tasks become eligible to continue after the service restarts.

Retries are bounded by background task settings. Tasks that exhaust retries need operator action:

synaps3 admin task list --status exhausted --limit 100
synaps3 admin task retry 42

Retry after restoring RPC connectivity, storage provider reachability, wallet funds, FWSS approval, or cache capacity.

Provider Health

Health checks record storage provider and local data set status. The dashboard uses those results to show copies that are unavailable, degraded, or unknown.

If an established provider becomes temporarily unavailable while the initial copies are still being stored, SynapS3 keeps using the other assigned writable copies. The unfinished copy waits without consuming retries and resumes automatically when the original provider becomes reachable again. SynapS3 does not automatically select a replacement provider. Repairing copies that became unavailable after storage completed remains part of the planned replica repair feature below.

Target and Minimum Replicas

The target replica count is frozen when an upload starts. By default, Release cache after is All replicas (strict): every target replica frozen for that upload must be readable and committed. A bucket can instead set an explicit count from 1 through the current target. An explicit count stays if Replicas later increases; lowering Replicas below that count is rejected until Release cache after is also lowered. All replicas (strict) follows each upload's frozen target. Once that threshold is met, the version becomes stored and its cache follows the configured eviction policy, while remaining replicas continue until the upload's target is reached. The dashboard keeps showing replica sync progress until every frozen target replica is done.

Changing the target affects new uploads. Changing the minimum also re-evaluates retained cache for current uploads. Increasing the minimum does not move versions that are already stored back to an earlier state and cannot restore cache that has already been deleted.

What Users See

  • S3 upload can succeed before Filecoin storage finishes.
  • Dashboard task and topology views show storage progress.
  • Reads prefer local cache. If remote metadata exists, SynapS3 can retrieve the object from the provider.
  • Cache eviction is an operational optimization, not the write acceptance point. after_upload removes a version after its minimum durable replicas are ready, lru waits for capacity pressure, and none retains it.

Planned Replica Repair

Replica repair is planned for a future release. After a storage provider becomes unavailable, it will:

  • identify stored copies affected by the provider outage,
  • create replacement copies until the configured target copy count is restored,
  • show repair progress and failures that require operator action.

This is distinct from completing the initial target copies and retrying failed storage tasks.