doc: Correct the timeline for OAuth's shutdown_cb

During original feature development, the OAuth validator shutdown
callback was invoked via before_shmem_exit(). That was changed to use a
reset callback before commit, but I forgot to update the documentation
for validator developers.

Correct this and backport to 18, where OAuth was introduced. The
callback is invoked whenever the server is "finished" with token
validation. (We make no stronger guarantees here, in the hopes that this
API might successfully navigate future multifactor authentication
support and/or changes to the server threading model.)

Reported-by: Zsolt Parragi <zsolt.parragi@percona.com>
Reviewed-by: Zsolt Parragi <zsolt.parragi@percona.com>
Reviewed-by: Chao Li <li.evan.chao@gmail.com>
Discussion: https://postgr.es/m/CAN4CZFOuMb_gnLvCwRdMybg_k8WRNJTjcij%2BPoQkuQHDUzxGWg%40mail.gmail.com
Backpatch-through: 18

diff --git a/doc/src/sgml/oauth-validators.sgml b/doc/src/sgml/oauth-validators.sgml
index 7c9e3dd931a85702f5e6a118457b397600d4118d..8aad470a46418f818366afe50681d72c1b80d75f 100644 (file)
--- a/doc/src/sgml/oauth-validators.sgml
+++ b/doc/src/sgml/oauth-validators.sgml
@@ -428,9 +428,10 @@ typedef struct ValidatorModuleResult
   <sect2 id="oauth-validator-callback-shutdown">
    <title>Shutdown Callback</title>
    <para>
-    The <function>shutdown_cb</function> callback is executed when the backend
-    process associated with the connection exits. If the validator module has
-    any allocated state, this callback should free it to avoid resource leaks.
+    The <function>shutdown_cb</function> callback is executed when the server
+    backend has finished validating tokens for the connection. If the validator
+    module has any allocated state, this callback should free it to avoid
+    resource leaks.
 <programlisting>
 typedef void (*ValidatorShutdownCB) (ValidatorModuleState *state);
 </programlisting>