write-path-cache.md

title	Write Path and Cache
description	Learn how SynapS3 accepts S3 writes, persists bytes locally, and uses cache during reads.

Write Path and Cache

SynapS3 uses a cache-first write model. A successful S3 write means object bytes are durable on local disk and metadata is committed to the database.

PutObject Flow

flowchart TD
  request["Receive write"] --> save["Save object locally"]
  save --> metadata["Record metadata"]
  metadata --> response["Return success with ETag"]
  response --> storage["Continue Filecoin storage in the background"]

Loading

SynapS3 validates the request, saves the object and its metadata, and returns an S3-compatible ETag. Filecoin storage continues after the client receives success.

Durability Invariant

Important

SynapS3 returns success only after both local cache persistence and database commit succeed.

The S3 response does not wait for Filecoin provider latency. After the write is accepted, a background task continues the upload.

Read Path

GetObject reads local cache first. If the cache entry is missing and an available remote copy is recorded, SynapS3 can retrieve the object from the storage provider, verify it, serve the response, and restore the local cache when possible.

Successful foreground cache opens refresh the entry's LRU access time. This includes S3 object and range reads, cached CopyObject sources, Admin content downloads, and version restores. Metadata-only operations such as HeadObject do not refresh it, and the background Uploader does not make an entry look recently used. A complete remote rehydration starts a new LRU age for the restored entry.

Repeated reads of the same version coalesce access-time updates to at most one database write per minute. Access tracking is best effort and never turns a successful read into an error.

Cache Eviction

Policy	Behavior
lru	At the high capacity watermark, queue the least recently accessed remotely safe versions until planned usage reaches the low watermark.
after_upload	Queue each version for removal after its bucket's minimum durable copies commit.
none	Do not create or run automatic cache eviction work.

Each bucket defaults to strict cache release, so the minimum equals the target replicas frozen for each upload. In the dashboard, set this on the bucket under Settings → Replica policy. An operator can set an explicit count from 1 through the current target. That count stays if Replicas later increases. Lowering Replicas below the stored count is rejected until Release cache after is also lowered. Lowering the threshold makes retained cache eligible for removal while remaining replicas continue syncing. Actual removal still follows after_upload, lru, or none. The minimum is clamped to each upload's target. Raising it affects cache that still exists; it cannot recreate cache that has already been deleted.

Only versions that currently meet their minimum and have a readable committed remote copy are eligible. Eviction checks the current minimum again before authorizing deletion and waits for active reads of the same version to close. Because cleanup is asynchronous, writes can still return 507 Insufficient Storage when cleanup cannot keep pace or no safe candidate exists.

Multipart Uploads

Multipart uploads keep parts in local storage until completion. Completing an upload validates the requested parts, assembles the final object, returns the S3 multipart ETag, and schedules background Filecoin storage.

Operational Impact

Condition	Meaning
Cache disk is full	New writes can fail before Filecoin storage is involved.
Background storage is not running	Confirmed writes remain local, but remote storage will not progress.
Cache entry is evicted	Reads can still succeed when remote metadata exists and retrieval works.
LRU has no safe candidate	Existing unsafe or in-progress data remains local; new writes can still fail with insufficient storage.
Database commit fails	The S3 write does not return success.

For capacity and recovery steps, see Runtime Data and Troubleshooting.