From a4397d43e997247f703b28baa81d5ffa727a65bd Mon Sep 17 00:00:00 2001
From: Anastasia Lubennikova <anastasia@neon.tech>
Date: Wed, 14 Sep 2022 20:16:22 +0300
Subject: [PATCH] Rename waldecoder -> waldecoder_handler.rs. Add comments

---
 libs/postgres_ffi/src/lib.rs                          |  8 +++++---
 .../src/{waldecoder.rs => waldecoder_handler.rs}      | 11 +++++++++--
 2 files changed, 14 insertions(+), 5 deletions(-)
 rename libs/postgres_ffi/src/{waldecoder.rs => waldecoder_handler.rs} (95%)

diff --git a/libs/postgres_ffi/src/lib.rs b/libs/postgres_ffi/src/lib.rs
index 25e1f6029c..1a6620a180 100644
--- a/libs/postgres_ffi/src/lib.rs
+++ b/libs/postgres_ffi/src/lib.rs
@@ -31,7 +31,7 @@ macro_rules! postgres_ffi {
             }
             pub mod controlfile_utils;
             pub mod nonrelfile_utils;
-            pub mod waldecoder;
+            pub mod waldecoder_handler;
             pub mod xlog_utils;
 
             pub const PG_MAJORVERSION: &str = stringify!($version);
@@ -216,12 +216,14 @@ pub mod waldecoder {
 
         pub fn poll_decode(&mut self) -> Result<Option<(Lsn, Bytes)>, WalDecodeError> {
             match self.pg_version {
+                // This is a trick to support both versions simultaneously.
+                // See WalStreamDecoderHandler comments.
                 14 => {
-                    use self::v14::waldecoder::WalStreamDecoderHandler;
+                    use self::v14::waldecoder_handler::WalStreamDecoderHandler;
                     self.poll_decode_internal()
                 }
                 15 => {
-                    use self::v15::waldecoder::WalStreamDecoderHandler;
+                    use self::v15::waldecoder_handler::WalStreamDecoderHandler;
                     self.poll_decode_internal()
                 }
                 _ => Err(WalDecodeError {
diff --git a/libs/postgres_ffi/src/waldecoder.rs b/libs/postgres_ffi/src/waldecoder_handler.rs
similarity index 95%
rename from libs/postgres_ffi/src/waldecoder.rs
rename to libs/postgres_ffi/src/waldecoder_handler.rs
index 5b46d52321..b4d50375bd 100644
--- a/libs/postgres_ffi/src/waldecoder.rs
+++ b/libs/postgres_ffi/src/waldecoder_handler.rs
@@ -26,8 +26,15 @@ pub trait WalStreamDecoderHandler {
 }
 
 //
-// WalRecordStream is a Stream that returns a stream of WAL records
-// FIXME: This isn't a proper rust stream
+// This is a trick to support several postgres versions simultaneously.
+//
+// Page decoding code depends on postgres bindings, so it is compiled for each version.
+// Thus WalStreamDecoder implements several WalStreamDecoderHandler traits.
+// WalStreamDecoder poll_decode() method dispatches to the right handler based on the postgres version.
+// Other methods are internal and are not dispatched.
+//
+// It is similar to having several impl blocks for the same struct,
+// but the impls here are in different modules, so need to use a trait.
 //
 impl WalStreamDecoderHandler for WalStreamDecoder {
     fn validate_page_header(&self, hdr: &XLogPageHeaderData) -> Result<(), WalDecodeError> {