Skip to main content

Module replication

s4_server

Module replication 

Source
Expand description

Bucket-to-bucket asynchronous replication (v0.6 #40).

AWS S3 Cross-Region Replication (CRR) lets a bucket owner declare a ReplicationConfiguration whose rules say “for every PUT to this bucket that matches <filter>, asynchronously copy the new object to <destination_bucket>”. The source object grows an x-amz-replication-status of PENDING → COMPLETED (or FAILED), the replica gets stamped REPLICA, and consumers can poll either HEAD to see how the replication is going.

§v0.6 #40 scope (single-instance only)

  • Same S4 endpoint — the source bucket and the destination bucket live on the same S4Service. True cross-region (multi-instance, wire-replicated) replication is a v0.7+ follow-up that needs a aws-sdk-s3 PUT to a remote endpoint with its own credentials.
  • Async only — the originating put_object returns as soon as the source backend write is done. The replica PUT happens on a detached tokio::spawn task and never blocks the client. There is no synchronous replication_required mode (would defeat the whole point of CRR being asynchronous in the first place).
  • Retry budget = 3 attempts with exponential backoff (50ms, 100ms, 200ms). On exhaustion the per-(bucket, key) status flips to Failed and dropped_total is bumped + a warn-level log line is emitted so operators see the loss in s4_replication_dropped_total.
  • Highest-priority rule wins when multiple rules match a single object key (S3 spec). Ties are broken by declaration order (deterministic for tests).
  • status_enabled = false rules never match, mirroring the AWS ReplicationRuleStatus::Disabled semantics — the rule sits in the configuration document but is inert.
  • Replica is full-body — there is no delta replication, no incremental fetch, no batching. Every matching PUT triggers one independent destination PUT.

§what is NOT in v0.6 #40

  • Delete-marker replication (S3’s DeleteMarkerReplication block) — v0.7+. Right now delete_object does not fan out a destination delete; the replica drifts on the source’s deletion.
  • Replication of multipart-completed objects through the per-part copy path. The whole compose-then-PUT result of CMU is replicated as a single PUT, which is fine for single-instance and matches what AWS does for source objects ≤ 5 GiB.
  • SSE-KMS-encrypted replicas with KMS-key-id rewriting per the SourceSelectionCriteria block (the source’s wrapped DEK is replicated as-is — fine for single-instance because the same KMS backend unwraps both copies).
  • Replication metrics (RTC) — a v0.7+ follow-up that wires a replication_lag_seconds histogram.

Structs§

ReplicationConfig
Per-bucket replication configuration.
ReplicationFilter
Filter on a ReplicationRule — the AND of a key-prefix predicate and a tag predicate. AWS S3’s wire form uses a sum type (Prefix | Tag | And { Prefix, Tags }); we collapse those into the single representation that the in-memory matcher needs.
ReplicationManager
In-memory manager of per-bucket replication configurations + per- (bucket, key) replication statuses.
ReplicationRule
One replication rule. Each rule independently decides whether to copy an object based on the (key, tags) tuple; the replication manager picks the highest-priority matching rule when multiple fire on the same object.
ReplicationStatusEntry
Per-(source_bucket, source_key) replication status entry, paired with the generation token of the source PUT that produced it.

Enums§

ReplicationStatus
Per-(bucket, key) replication state, surfaced as the x-amz-replication-status HEAD/GET response header. Values match the AWS wire form exactly.

Functions§

replicate_object
Replicate one source-bucket object to the rule’s destination bucket.
warn_lock_propagation_skipped
v0.8.3 #68 (audit M-1): emit a single WARN log line per (source_bucket, dest_bucket) pair the first time we observe a replication PUT that wanted to propagate Object Lock state but the destination side has no ObjectLockManager attached. The metric (s4_replication_lock_propagation_skipped_total) bumps every time (so dashboards see the rate); the log is dedup’d because operators only need to know once that the configuration is asymmetric.