Provide fix for failing pg_rewind with non-superuser

Issue #829 was opened indicating, with a reproducible, that repmgr
was not able to run `node rejoin` with minimal privileged user. The
main obstacle is that pg_rewind is not able to execute the rewind
operation if the user has REPLICATION privileges, but the user
repmgr uses requires REPLICATION. This is a typical catch22.

The solution provided here adds a --superuser, similar to what
other commands have, to `node rejoin`

AI-assisted development notes:

    The approach was designed and directed by Martín Marqués, who
    also reviewed and refined the output. Code was written by Claude
    (AI), with some additions from Martín in the documentation.

Fixes #829

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Martín Marqués <martin.marques@enterprisedb.com>

doc/configuration-permissions.xml

@@ -192,6 +192,9 @@
           <listitem>
             <simpara><link linkend="repmgr-node-service">repmgr node service</link> (to execute <command>CHECKPOINT</command> via the <option>--checkpoint</option>; note this is also called by <link linkend="repmgr-standby-switchover">repmgr standby switchover</link>)</simpara>
           </listitem>
+          <listitem>
+            <simpara><link linkend="repmgr-node-rejoin">repmgr node rejoin</link> (to execute <command>repmgr node rejoin --force-rewind</command>)</simpara>
+          </listitem>
         </itemizedlist>
       </para>
     </sect3>

doc/repmgr-node-rejoin.xml

@@ -113,6 +113,29 @@
       </varlistentry>
 
 
+      <varlistentry>
+        <term><option>-S/--superuser</option></term>
+        <listitem>
+          <para>
+            Specify a superuser to be used by <application>pg_rewind</application>
+            for its source server connection.
+          </para>
+          <para>
+            <application>pg_rewind</application> requires a normal (non-replication)
+            connection with <literal>pg_read_server_files</literal> privilege or
+            superuser rights. If the &repmgr; user has the <literal>REPLICATION</literal>
+            attribute but lacks these privileges, use this option to specify
+            a suitably privileged user for the <application>pg_rewind</application>
+            connection. The superuser's password should be configured in
+            <filename>.pgpass</filename>.
+          </para>
+          <para>
+            This option is only effective in combination with
+            <option>--force-rewind</option>.
+          </para>
+        </listitem>
+      </varlistentry>
+
       <varlistentry>
         <term><option>-W/--no-wait</option></term>
         <listitem>
@@ -281,6 +304,23 @@
       a &quot;magic bullet&quot; which can resolve all problematic replication situations.
     </para>
 
+    <note>
+      <para>
+        <command>pg_rewind</command> requires a normal (non-replication) connection to
+        the source server. The user for this connection must have superuser rights or
+        the <literal>pg_read_server_files</literal> role.
+      </para>
+      <para>
+        If the &repmgr; user has the <literal>REPLICATION</literal> attribute but does
+        not have the privileges required by <command>pg_rewind</command>, use the
+        <option>-S/--superuser</option> option to specify a suitably privileged user
+        for the <command>pg_rewind</command> source connection. For example:
+        <programlisting>
+    repmgr node rejoin -f /etc/repmgr.conf -d 'host=node3 dbname=repmgr user=repmgr' \
+        --force-rewind -S postgres</programlisting>
+      </para>
+    </note>
+
     <para>
       A typical use-case for <command>pg_rewind</command> is when a scenario like the following
       is encountered:

repmgr-action-node.c

@@ -2838,9 +2838,29 @@ do_node_rejoin(void)
 		appendShellString(&command,
 						  config_file_options.data_directory);
 
+		if (runtime_options.superuser[0] != '\0')
+		{
+			t_conninfo_param_list rewind_conninfo = T_CONNINFO_PARAM_LIST_INITIALIZER;
+			char *rewind_conninfo_str = NULL;
+
+			initialize_conninfo_params(&rewind_conninfo, false);
+			parse_conninfo_string(primary_node_record.conninfo, &rewind_conninfo, NULL, false);
+			param_set(&rewind_conninfo, "user", runtime_options.superuser);
+			rewind_conninfo_str = param_list_to_string(&rewind_conninfo);
+
+			appendPQExpBuffer(&command,
+							  " --source-server='%s'",
+							  rewind_conninfo_str);
+
+			pfree(rewind_conninfo_str);
+			free_conninfo_params(&rewind_conninfo);
+		}
+		else
+		{
 			appendPQExpBuffer(&command,
 							  " --source-server='%s'",
 							  primary_node_record.conninfo);
+		}
 
 		if (runtime_options.dry_run == true)
 		{
@@ -3698,6 +3718,7 @@ do_node_help(void)
 	printf(_("    --config-archive-dir    directory to temporarily store retained configuration files\n" \
 			 "                              (default: /tmp)\n"));
 	printf(_("    -W, --no-wait           don't wait for the node to rejoin cluster\n"));
+	printf(_("    -S, --superuser=USERNAME  superuser to use for pg_rewind if repmgr user is not superuser\n"));
 	puts("");
 
 	printf(_("NODE SERVICE\n"));

repmgr-action-standby.c

@@ -5359,6 +5359,13 @@ do_standby_switchover(void)
 		}
 
 		appendPQExpBufferChar(&node_rejoin_options, ' ');
+
+		if (runtime_options.superuser[0] != '\0')
+		{
+			appendPQExpBuffer(&node_rejoin_options,
+							  "--superuser=%s ",
+							  runtime_options.superuser);
+		}
 	}
 
 	key_value_list_free(&remote_config_files);

repmgr-client.c

@@ -1761,6 +1761,7 @@ check_cli_parameters(const int action)
 			case STANDBY_SWITCHOVER:
 			case NODE_CHECK:
 			case NODE_SERVICE:
+			case NODE_REJOIN:
 				break;
 			default:
 				item_list_append_format(&cli_warnings,