Write Path

Detailed flow of a PutObject request through backend selection, encryption, failover, and metadata recording. Hover over any component for implementation details.

Pending-Intent Pattern

The InsertPendingIntent → RecordObjectAndPromoteIntent two-phase pattern exists so a crash between the backend PUT and the metadata commit cannot leak orphan bytes. The intent row captures everything the recovery path needs (key, backend, size, encryption metadata) so on restart the PendingReaper worker can HEAD the backend and decide commit (HEAD 200 → promote the intent) or cleanup (HEAD 404 → drop the intent, enqueue cleanup).

The post-PUT IsDraining re-check guards a separate race: a drain can begin while the backend PUT is in flight. Without the re-check, the bytes would land on the draining backend and the drain worker would have to move them off again. With it, the orchestrator aborts the attempt and fails over to the next eligible backend, incrementing s3o_drain_race_aborted_total.

See internal/worker/pending.go for the reaper implementation and internal/proxy/writepath/coordinator.go for the coordinator-side helpers.

Legend