From 6219a268df4fefdd99bf64a3c2de9548338cbc62 Mon Sep 17 00:00:00 2001
From: Jacob Champion <jacob.champion@enterprisedb.com>
Date: Wed, 1 Apr 2026 10:29:16 -0700
Subject: [PATCH v3.1 2/6] squash! Split PGOAUTHDEBUG=UNSAFE into multiple
 options

- Rename user-facing options in parsing and documentation.
- Move dos-endpoint to UNSAFE.
- Realign lineannotations and update doc descriptions.
---
 doc/src/sgml/libpq.sgml                    | 45 ++++++++++------------
 src/interfaces/libpq/fe-auth-oauth-debug.c |  9 +++--
 2 files changed, 26 insertions(+), 28 deletions(-)

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 2e5fb9011e9..01a65419f99 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -10649,9 +10649,9 @@ typedef struct
     debug options:
 
     <programlisting>
-PGOAUTHDEBUG=option1,option2,...    <lineannotation>for safe options only</lineannotation>
-PGOAUTHDEBUG=UNSAFE:option1,option2,...    <lineannotation>when using unsafe options</lineannotation>
-PGOAUTHDEBUG=UNSAFE    <lineannotation>legacy format; enables all options</lineannotation>
+PGOAUTHDEBUG=option1,option2,...         <lineannotation>for safe options only</lineannotation>
+PGOAUTHDEBUG=UNSAFE:option1,option2,...  <lineannotation>when using unsafe options</lineannotation>
+PGOAUTHDEBUG=UNSAFE                      <lineannotation>legacy format; enables all options</lineannotation>
     </programlisting>
    </para>
 
@@ -10684,29 +10684,29 @@ PGOAUTHDEBUG=UNSAFE    <lineannotation>legacy format; enables all options</linea
      </varlistentry>
 
      <varlistentry>
-      <term><literal>fast-retry</literal> (safe)</term>
+      <term><literal>dos-endpoint</literal> (unsafe)</term>
       <listitem>
        <para>
         Permits the use of zero-second retry intervals instead of the normal
-        minimum of one second. This can speed up tests but may cause the client
-        to busy-loop and consume CPU unnecessarily.
+        minimum of one second. This speeds up tests, but in normal operation it
+        will cause the client to busy-loop, consuming CPU and network resources.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><literal>poll-counts</literal> (safe)</term>
+      <term><literal>call-count</literal> (safe)</term>
       <listitem>
        <para>
-        Prints the total number of poll() calls to standard error when the
-        OAuth flow completes. This helps developers debug the async multiplexer
-        behavior.
+        Prints the total number of calls to the flow plugin to standard error
+        when the OAuth flow completes. This helps developers debug the async
+        callback behavior.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><literal>print-plugin-errors</literal> (safe)</term>
+      <term><literal>plugin-errors</literal> (safe)</term>
       <listitem>
        <para>
         Prints plugin loading errors to standard error. This helps developers
@@ -10718,13 +10718,12 @@ PGOAUTHDEBUG=UNSAFE    <lineannotation>legacy format; enables all options</linea
    </para>
 
    <para>
-    Unsafe options (<literal>http</literal>, <literal>trace</literal>)
-    require the <literal>UNSAFE:</literal> prefix.
+    Unsafe options (<literal>http</literal>, <literal>trace</literal>,
+    <literal>dos-endpoint</literal>) require the <literal>UNSAFE:</literal> prefix.
     If unsafe options are specified without this prefix, a warning is printed
     to standard error and that option is ignored. Other valid options in the
-    list continue to work. Safe options (<literal>fast-retry</literal>,
-    <literal>poll-counts</literal>, <literal>print-plugin-errors</literal>) can
-    be used without the prefix.
+    list continue to work. Safe options (<literal>call-count</literal>,
+    <literal>plugin-errors</literal>) can be used without the prefix.
    </para>
 
    <para>
@@ -10736,19 +10735,17 @@ PGOAUTHDEBUG=UNSAFE    <lineannotation>legacy format; enables all options</linea
    <para>
     Examples:
     <programlisting>
-PGOAUTHDEBUG=fast-retry,poll-counts    <lineannotation>safe options only</lineannotation>
-PGOAUTHDEBUG=UNSAFE:http,trace    <lineannotation>enable HTTP and traffic logging</lineannotation>
-PGOAUTHDEBUG=UNSAFE:http,poll-counts    <lineannotation>mix of unsafe and safe</lineannotation>
-PGOAUTHDEBUG=UNSAFE    <lineannotation>legacy; enables all options</lineannotation>
+PGOAUTHDEBUG=call-count              <lineannotation>safe options only</lineannotation>
+PGOAUTHDEBUG=UNSAFE:http,trace       <lineannotation>enable HTTP and traffic logging</lineannotation>
+PGOAUTHDEBUG=UNSAFE:http,call-count  <lineannotation>mix of unsafe and safe</lineannotation>
     </programlisting>
    </para>
 
    <warning>
     <para>
-     Never use unsafe debug options in production environments. The
-     <literal>trace</literal> option in particular exposes secrets that can be
-     used to attack your clients and servers. Do not share the output with third
-     parties.
+     Never use unsafe debug options in production environments. They expose
+     secrets and behaviors that can be used to attack your clients and servers.
+     Do not share <literal>trace</literal> output with third parties.
     </para>
    </warning>
   </sect2>
diff --git a/src/interfaces/libpq/fe-auth-oauth-debug.c b/src/interfaces/libpq/fe-auth-oauth-debug.c
index f9a1b1f195f..957da5d4068 100644
--- a/src/interfaces/libpq/fe-auth-oauth-debug.c
+++ b/src/interfaces/libpq/fe-auth-oauth-debug.c
@@ -47,18 +47,19 @@ parse_debug_option(const char *option, oauth_debug_flags *flags, bool *is_unsafe
 		*is_unsafe = true;
 		return true;
 	}
-	/* Safe options */
-	else if (strcmp(option, "fast-retry") == 0)
+	else if (strcmp(option, "dos-endpoint") == 0)
 	{
 		flags->fast_retry = true;
+		*is_unsafe = true;
 		return true;
 	}
-	else if (strcmp(option, "poll-counts") == 0)
+	/* Safe options */
+	else if (strcmp(option, "call-count") == 0)
 	{
 		flags->poll_counts = true;
 		return true;
 	}
-	else if (strcmp(option, "print-plugin-errors") == 0)
+	else if (strcmp(option, "plugin-errors") == 0)
 	{
 		flags->print_plugin_errors = true;
 		return true;
-- 
2.34.1