From d72c31241b2d406bca69bbdead9731a4e1bb4c17 Mon Sep 17 00:00:00 2001 From: Andrew Wong Date: Thu, 27 Jun 2024 12:12:11 -0700 Subject: [PATCH] cloud_storage: add clarifying comments around naming and versions Adds some comments describing labeled and prefixed paths. This is review follow-up from #20149 --- src/v/cloud_storage/partition_path_utils.h | 10 ++++++++++ src/v/cloud_storage/segment_path_utils.h | 13 +++++++++++++ src/v/cloud_storage/topic_path_utils.h | 10 ++++++++++ 3 files changed, 33 insertions(+) diff --git a/src/v/cloud_storage/partition_path_utils.h b/src/v/cloud_storage/partition_path_utils.h index e995251e2710..d73542b20a5c 100644 --- a/src/v/cloud_storage/partition_path_utils.h +++ b/src/v/cloud_storage/partition_path_utils.h @@ -17,6 +17,16 @@ namespace cloud_storage { +// Redpanda has supported different formats and naming schemes for partition +// manifests through its lifetime: +// - v24.2 and up: cluster-uuid-labeled name, binary format +// - v23.2 and up: hash-prefixed name, binary format +// - below v23.2: hash-prefixed name, JSON format +// +// Because manifests are persistent state, we must be able to access older +// versions, in cases we need to read when newer manifests have not yet been +// written. This header contains methods to build paths for all versions. + // 806a0f4a-e691-4a2b-9352-ec4b769a5e6e/meta/kafka/panda-topic/0_123 ss::sstring labeled_partition_manifest_prefix( const remote_label& cluster_hint, diff --git a/src/v/cloud_storage/segment_path_utils.h b/src/v/cloud_storage/segment_path_utils.h index 0b9b51226485..d1cb3f962aa8 100644 --- a/src/v/cloud_storage/segment_path_utils.h +++ b/src/v/cloud_storage/segment_path_utils.h @@ -16,6 +16,19 @@ namespace cloud_storage { +// Redpanda has supported different naming schemes for segments through its +// lifetime: +// - v24.2 and up: cluster-uuid-labeled name +// - below v24.2: hash-prefixed name +// +// Because segments are persistent state, we must be able to access older +// versions, in cases we need to read when newer manifests have not yet been +// written. This header contains methods to build paths for all versions. +// +// NOTE: the exact segment-name format is still determined by manifest state. +// As such, this class only guides the prefix, and leaves filename generation +// to callers (typically via methods in partition_manifest). + // 806a0f4a-e691-4a2b-9352-ec4b769a5e6e/kafka/panda-topic/0_123/0-100-1024-16-v1.log.16 ss::sstring labeled_segment_path( const remote_label& remote_label, diff --git a/src/v/cloud_storage/topic_path_utils.h b/src/v/cloud_storage/topic_path_utils.h index adc7fe4bb546..f26afda5ada9 100644 --- a/src/v/cloud_storage/topic_path_utils.h +++ b/src/v/cloud_storage/topic_path_utils.h @@ -17,6 +17,16 @@ namespace cloud_storage { +// Redpanda has supported different formats and naming schemes for topic +// manifests through its lifetime: +// - v24.2 and up: cluster-uuid-labeled name, binary format +// - v24.1 and up: hash-prefixed name, binary format +// - below v24.1: hash-prefixed name, JSON format +// +// Because manifests are persistent state, we must be able to access older +// versions, in cases we need to read when newer manifests have not yet been +// written. This header contains methods to build paths for all versions. + // meta/kafka/panda-topic ss::sstring labeled_topic_manifest_root(const model::topic_namespace& topic);