Skip to main content

Module versioning

s4_server

Module versioning 

Source
Expand description

v0.5 #34: First-class versioning state machine.

S4-server に object version の own state を持たせる module。これまで versioning は backend (s3s framework) への passthrough でしか機能していなかった が、本 module で S4 自身が

  • per-bucket の Versioning state (Enabled / Suspended / Unversioned)
  • per-(bucket, key) の version chain (Vec<VersionEntry>、最新が末尾)
  • delete marker
  • version-id 採番 (UUIDv4)

を所有する。crates/s4-server/src/service.rs の put_object / get_object / delete_object / list_object_versions / get_bucket_versioning / put_bucket_versioning handler が S4Service 経由で VersioningManager を呼び出して、AWS S3 wire-compat な振る舞いを 実現する。

§scope (v0.5 #34)

  • in-memory only (single instance scope)。multi-instance replication は v0.6+ で別 issue として扱う
  • to_json / from_json で snapshot を取る API は提供する。main.rs 側で --versioning-state-file flag を将来追加する hook として使える
  • MFA delete はサポートしない (本 task の scope 外)

§semantics

  • version_id format: UUIDv4 を 32-char hex (no dash) で表現。AWS 互換 実装では base64-url や custom encoding が多いが、UUIDv4 hex は十分一意で debug 容易、URL-safe 文字のみで構成され x-amz-version-id header / versionId query param に何の escape も不要
  • null version: Suspended bucket での PUT、または初期 Unversioned bucket で 作成された object の version_id は文字列 "null"。Suspended bucket の同 key への次 PUT は既存 null version を 上書き する (S3 仕様準拠)
  • delete marker: Enabled bucket への DELETE (version_id 指定なし) は 新規 delete marker (version_id 採番) を chain の末尾に追加する。GET (version_id 指定なし) は最新が delete marker なら NoSuchKey 404 を返す
  • specific-version DELETE: version_id を指定した DELETE は当該 entry を chain から物理削除する。delete marker を狙い撃ちで消すと、その下の version が再び latest として可視になる (= “undelete”)。Suspended / Unversioned bucket でも version_id 指定 DELETE は受け付ける (chain 中の null version も狙える)

Structs§

DeleteOutcome
ListVersionEntry
list_versions の戻り値 row。service.rs 側で s3s ObjectVersion / DeleteMarkerEntry に詰め直す。
ListVersionsPage
PutOutcome
record_put / record_delete の戻り値。handler 側で response の x-amz-version-id 等を組み立てるために使う。
VersionEntry
Per-version metadata. is_delete_marker が true の entry は backend storage に bytes を持たない (= tombstone) — etag は空 / size は 0 になる。
VersionIndex
per-(bucket, key) chain (最新版が Vec の末尾) の in-memory map。
VersioningManager
per-bucket versioning state + per-(bucket, key) version chain を一元管理する 上位 manager。すべての書き込み操作は RwLock write 経由で atomic、すべての 読み出しは read 経由 (chain は Vec<VersionEntry> の clone を返す)。
VersioningSnapshot
snapshot のシリアライズ format。to_json / from_json 用。

Enums§

VersioningState
Per-bucket versioning state。AWS S3 では Enabled / Suspended の二択 (作成直後の bucket は status 未設定 = Unversioned 相当) なので、3 値に分けて 管理する。

Constants§

NULL_VERSION_ID
AWS-style "null" literal は version-id 全体で唯一の予約名。chain 内に 同時に複数存在することは無い (= Suspended bucket は最大 1 entry を保持)。