Merged PR 1766230: [Vacuum] Enable better vacuum cleanup Part 1

### Does this PR have any customer impact?
No

### Type (Feature, Refactoring, Bugfix, DevOps, Testing, Perf, etc)
Feature

### Does it involve schema level changes? (Table, Column, Index, UDF, etc level changes)
No

### Are you introducing any new config? If yes, do you have tests with and without them being set?
Yes

### ChangeLog (Refer [Template](../oss/CHANGELOG.md))

### Description

Rum/GIN Entry Tree pages can be pruned better - Currently, over time, indexes will bloat in size.
To handle this, we walk the entry leaves on vacuum and if empty, we prune them more eagerly.

This is the first part of many in cleanup of the entry tree in RUM.

Note that while this marks the buffers as HALFDEAD - it does not reclaim the page space - that will be done in a subsequent step where the XID horizon is past all active requests. Once that is done, the page is marked recyclable and reusable.

In its current shape, this prunes empty leaves in the RUM index only if the entire page is only posting lists and marks them as half-dead. It also leaves behind the right most child of an intermediate tree for correctness.

It also doesn't handle intermediate nodes currently so as-is we will have lots of skinny trees in the index once a lot of data is deleted.

Note that this is only intended for offline /adhoc use currently since more thorough testing is needed for vacuuming. pending further tests and stress handling

----
#### AI description  (iteration 1)
#### PR Classification
This pull request adds a new vacuum tree cleanup feature to the RUM index by enabling the pruning of empty pages during vacuum operations.

#### PR Summary
The update enhances the vacuum process by introducing logic to safely detect and remove empty leaf pages, improve tuple retrieval for half-dead states, and provide better logging and configuration control.
- **`pgmongo_rum/src/rumvacuum.c`**: Added the `CheckAndPruneEmptyRumPage` function and updated vacuum routines to identify, prune, and log empty pages.
- **`pgmongo_rum/src/rum.h` & `rumutil.c`**: Introduced new macros for half-dead page handling and defined the GUC variable `RumPruneEmptyPages` to control the cleanup behavior.
- **`pgmongo_rum/src/rumscan.c` & `rumentrypage.c`**: Refactored tuple retrieval functions to support the new cleanup logic by using `rumEntryGetRightMostTuple` and handling half-dead pages.
- **Test files & scripts**: Updated SQL tests and configuration scripts to validate and enable the new vacuum cleanup functionality.
<!-- GitOpsUserAgent=GitOps.Apps.Server.pullrequestcopilot -->

Author: visridha

internal/pg_documentdb_extended_rum/src/pg_documentdb_rum.h

@@ -71,6 +71,7 @@ typedef RumPageOpaqueData *RumPageOpaque;
 #define RUM_META (1 << 3)
 #define RUM_LIST (1 << 4)
 #define RUM_LIST_FULLROW (1 << 5)       /* makes sense only on RUM_LIST page */
+#define RUM_HALF_DEAD (1 << 6)
 
 /* Page numbers of fixed-location pages */
 #define RUM_METAPAGE_BLKNO (0)
@@ -139,6 +140,10 @@ typedef struct RumMetaPageData
 #define RumPageSetNonDeleted(page) (RumPageGetOpaque(page)->flags &= ~RUM_DELETED)
 #define RumPageForceSetDeleted(page) (RumPageGetOpaque(page)->flags = RUM_DELETED)
 
+#define RumPageIsHalfDead(page) ((RumPageGetOpaque(page)->flags & RUM_HALF_DEAD) != 0)
+#define RumPageSetHalfDead(page) (RumPageGetOpaque(page)->flags |= RUM_HALF_DEAD)
+#define RumPageSetNonHalfDead(page) (RumPageGetOpaque(page)->flags &= ~RUM_HALF_DEAD)
+
 #define RumPageRightMost(page) (RumPageGetOpaque(page)->rightlink == InvalidBlockNumber)
 #define RumPageLeftMost(page) (RumPageGetOpaque(page)->leftlink == InvalidBlockNumber)
 
@@ -570,14 +575,14 @@ extern void rumReadTuple(RumState *rumstate, OffsetNumber attnum,
 						 IndexTuple itup, RumItem *items, bool copyAddInfo);
 extern void rumReadTuplePointers(RumState *rumstate, OffsetNumber attnum,
 								 IndexTuple itup, ItemPointerData *ipd);
-extern void updateItemIndexes(Page page, OffsetNumber attnum, RumState *rumstate);
-extern void checkLeafDataPage(RumState *rumstate, AttrNumber attrnum, Page page);
 bool entryIsMoveRight(RumBtree btree, Page page);
 bool entryLocateLeafEntryBounds(RumBtree btree, Page page,
 								OffsetNumber low, OffsetNumber high,
 								OffsetNumber *targetOffset);
+IndexTuple rumEntryGetRightMostTuple(Page page);
 
 /* rumdatapage.c */
+extern void updateItemIndexes(Page page, OffsetNumber attnum, RumState *rumstate);
 extern int rumCompareItemPointers(const ItemPointerData *a, const ItemPointerData *b);
 extern int compareRumItem(RumState *state, const AttrNumber attno,
 						  const RumItem *a, const RumItem *b);

internal/pg_documentdb_extended_rum/src/rumentrypage.c

@@ -112,8 +112,8 @@ RumFormInteriorTuple(RumBtree btree, IndexTuple itup, Page page,
  * Entry tree is a "static", ie tuple never deletes from it,
  * so we don't use right bound, we use rightmost key instead.
  */
-static IndexTuple
-getRightMostTuple(Page page)
+IndexTuple
+rumEntryGetRightMostTuple(Page page)
 {
 	OffsetNumber maxoff = PageGetMaxOffsetNumber(page);
 
@@ -136,7 +136,13 @@ entryIsMoveRight(RumBtree btree, Page page)
 		return false;
 	}
 
-	itup = getRightMostTuple(page);
+	if (RumPageIsHalfDead(page))
+	{
+		/* If on a half dead page, always move right */
+		return true;
+	}
+
+	itup = rumEntryGetRightMostTuple(page);
 	attnum = rumtuple_get_attrnum(btree->rumstate, itup);
 	key = rumtuple_get_key(btree->rumstate, itup, &category);
 
@@ -264,7 +270,6 @@ entryLocateLeafEntryBounds(RumBtree btree, Page page,
 						   OffsetNumber low, OffsetNumber high,
 						   OffsetNumber *targetOffset)
 {
-	Assert(RumPageIsLeaf(page));
 	Assert(!RumPageIsData(page));
 
 	if (high < low)
@@ -569,7 +574,7 @@ rumPageGetLinkItup(RumBtree btree, Buffer buf, Page page)
 	IndexTuple itup,
 			   nitup;
 
-	itup = getRightMostTuple(page);
+	itup = rumEntryGetRightMostTuple(page);
 	nitup = RumFormInteriorTuple(btree, itup, page, BufferGetBlockNumber(buf));
 
 	return nitup;

internal/pg_documentdb_extended_rum/src/rumscan.c

@@ -901,17 +901,15 @@ rumNewScanKey(IndexScanDesc scan)
 
 	if (scan->xs_want_itup)
 	{
-		so->projectIndexTupleData = palloc0(sizeof(RumProjectIndexTupleData));
-		so->projectIndexTupleData->iscan_tuple = NULL;
-		so->projectIndexTupleData->indexTupleDatum = (Datum) 0;
-
 		char *attributeName = NULL;
 		int attributeTypeModifier = -1;
 		int numDimensions = 0;
-
-
 		int natts = RelationGetNumberOfAttributes(scan->indexRelation);
 
+		so->projectIndexTupleData = palloc0(sizeof(RumProjectIndexTupleData));
+		so->projectIndexTupleData->iscan_tuple = NULL;
+		so->projectIndexTupleData->indexTupleDatum = (Datum) 0;
+
 		so->projectIndexTupleData->indexTupleDesc = CreateTemplateTupleDesc(natts);
 		for (i = 0; i < natts; i++)
 		{

internal/pg_documentdb_extended_rum/src/rumvacuum.c

@@ -12,6 +12,7 @@
  */
 
 #include "postgres.h"
+#include "miscadmin.h"
 
 #include "commands/vacuum.h"
 #include "postmaster/autovacuum.h"