From: Timo Sirainen <timo.sirainen@open-xchange.com>
Date: Mon, 12 Feb 2024 08:58:55 +0000 (+0200)
Subject: lib-index: Update comments about how transaction log corruption is handled
X-Git-Tag: 2.4.2~69
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=8dee235890ae9ac252b54aaa130963c4a7bd4d67;p=thirdparty%2Fdovecot%2Fcore.git

lib-index: Update comments about how transaction log corruption is handled
---

diff --git a/src/lib-index/mail-index-private.h b/src/lib-index/mail-index-private.h
index 856eb08b19..2f5e128111 100644
--- a/src/lib-index/mail-index-private.h
+++ b/src/lib-index/mail-index-private.h
@@ -358,7 +358,8 @@ struct mail_index_map *mail_index_map_alloc(struct mail_index *index);
 
    If we mmap()ed the index file, the map is returned locked.
 
-   Returns 1 = ok, 0 = corrupted, -1 = error. */
+   Returns 1 = ok, 0 = unusably corrupted, -1 = error. Corrupted records inside
+   the transaction log file doesn't cause this function to fail. */
 int mail_index_map(struct mail_index *index,
 		   enum mail_index_sync_handler_type type);
 /* Unreference given mapping and unmap it if it's dropped to zero. */
diff --git a/src/lib-index/mail-index-sync-private.h b/src/lib-index/mail-index-sync-private.h
index 094c83d90b..ab41a41006 100644
--- a/src/lib-index/mail-index-sync-private.h
+++ b/src/lib-index/mail-index-sync-private.h
@@ -54,6 +54,9 @@ void mail_index_sync_map_init(struct mail_index_sync_map_ctx *sync_map_ctx,
 void mail_index_sync_map_deinit(struct mail_index_sync_map_ctx *sync_map_ctx);
 bool mail_index_sync_map_want_index_reopen(struct mail_index_map *map,
 					   enum mail_index_sync_handler_type type);
+/* Returns 1 if synced, 0 if map's log file is lost (or more likely, seq number
+   is corrupted), -1 on I/O error. Corrupted records inside the transaction log
+   file doesn't cause this function to fail. */
 int mail_index_sync_map(struct mail_index_map **_map,
 			enum mail_index_sync_handler_type type,
 			const char **reason_r);
diff --git a/src/lib-index/mail-index-sync-update.c b/src/lib-index/mail-index-sync-update.c
index 16ea5aa088..82f03dda6b 100644
--- a/src/lib-index/mail-index-sync-update.c
+++ b/src/lib-index/mail-index-sync-update.c
@@ -1002,6 +1002,10 @@ int mail_index_sync_map(struct mail_index_map **_map,
 	}
 	map = NULL;
 
+	/* mail_transaction_log_view_next() returns -1 on corruption.
+	   Since the log file content before the corruption was found can be
+	   useful and important, we don't fail this sync entirely. Instead,
+	   we'll just mark the rest of the log file as synced. */
 	while ((ret = mail_transaction_log_view_next(view->log_view, &thdr,
 						     &tdata)) > 0) {
 		mail_transaction_log_view_get_prev_pos(view->log_view,
diff --git a/src/lib-index/mail-transaction-log.h b/src/lib-index/mail-transaction-log.h
index b04c3aafcc..6779e30914 100644
--- a/src/lib-index/mail-transaction-log.h
+++ b/src/lib-index/mail-transaction-log.h
@@ -421,7 +421,7 @@ void mail_transaction_log_view_clear(struct mail_transaction_log_view *view,
 				     uint32_t oldest_file_seq);
 
 /* Read next transaction record from current position. The position is updated.
-   Returns -1 if error, 0 if we're at end of the view, 1 if ok. */
+   Returns -1 if log is corrupted, 0 if we're at end of the view, 1 if ok. */
 int mail_transaction_log_view_next(struct mail_transaction_log_view *view,
 				   const struct mail_transaction_header **hdr_r,
 				   const void **data_r);