From: Alvaro Herrera <alvherre@alvh.no-ip.org>
To: Jelte Fennema-Nio <postgres@jeltef.nl>
Cc: vignesh C <vignesh21@gmail.com>
Cc: Thomas Munro <thomas.munro@gmail.com>
Cc: Denis Laxalde <denis.laxalde@dalibo.com>
Cc: Greg Stark <stark@mit.edu>
Cc: Tom Lane <tgl@sss.pgh.pa.us>
Cc: Gregory Stark (as CFM) <stark.cfm@gmail.com>
Cc: Jelte Fennema <Jelte.Fennema@microsoft.com>
Cc: Daniel Gustafsson <daniel@yesql.se>
Cc: Peter Eisentraut <peter@eisentraut.org>
Cc: Andres Freund <andres@anarazel.de>
Cc: Justin Pryzby <pryzby@telsasoft.com>
Cc: Robert Haas <robertmhaas@gmail.com>
Cc: pgsql-hackers@lists.postgresql.org <pgsql-hackers@lists.postgresql.org>
Subject: Re: [EXTERNAL] Re: Add non-blocking version of PQcancel
Date: Fri, 2 Feb 2024 16:05:56 +0100
Message-ID: <202402021505.6cuvlqgqj5si@alvherre.pgsql> (raw)
In-Reply-To: <202402021219.mrrtsrwikgzc@alvherre.pgsql>
Hello,
The patched docs claim that PQrequestCancel is insecure, but neither the
code nor docs explain why. The docs for PQcancel on the other hand do
mention that encryption is not used; does that apply to PQrequestCancel
as well and is that the reason? If so, I think we should copy the
warning and perhaps include a code comment about that. Also, maybe that
final phrase in PQcancel should be a <caution> box: remove from "So, for
example" and add <caution><para>Because gssencmode and sslencmode are
not preserved from the original connection, the cancel request is not
encrypted.</para></caution> or something like that.
I wonder if Section 33.7 Canceling Queries in Progress should be split
in three subsections, and I propose the following order:
33.7.1 PGcancelConn-based Cancellation API
PQcancelConn -- we first document the basics
PQcancelSend
PQcancelFinish
PQcancelPoll -- the nonblocking interface is documented next
PQcancelReset -- reuse a cancelconn, later in docs because it's more advanced
PQcancelStatus -- accessors go last
PQcancelSocket
PQcancelErrorMessage
33.7.2 Obsolete interface
PQgetCancel
PQfreeCancel
PQcancel
33.7.3 Deprecated and Insecure Methods
PQrequestCancel
I have a hard time coming up with good subsection titles though.
Now, looking at this list, I think it's surprising that the nonblocking
request for a cancellation is called PQcancelPoll. PQcancelSend() is at
odds with the asynchronous query API, which uses the verb "send" for the
asynchronous variants. This would suggest that PQcancelPoll should
actually be called PQcancelSend or maybe PQcancelStart (mimicking
PQconnectStart). I'm not sure what's a good alternative name for the
blocking one, which you have called PQcancelSend.
I see upthread that the names of these functions were already quite
heavily debated. Sorry to beat that dead horse some more ... I'm just
not sure it's decided matter.
Lastly -- the doc blurbs that say simply "a version of XYZ that can be
used for cancellation connections" are a bit underwhelming. Shouldn't
we document these more fully instead of making users go read the docs
for the other functions and wonder what the differences might be, if
any?
--
Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/
"Before you were born your parents weren't as boring as they are now. They
got that way paying your bills, cleaning up your room and listening to you
tell them how idealistic you are." -- Charles J. Sykes' advice to teenagers
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-hackers@postgresql.org
Cc: alvherre@alvh.no-ip.org, postgres@jeltef.nl, vignesh21@gmail.com, thomas.munro@gmail.com, denis.laxalde@dalibo.com, stark@mit.edu, tgl@sss.pgh.pa.us, stark.cfm@gmail.com, Jelte.Fennema@microsoft.com, daniel@yesql.se, peter@eisentraut.org, andres@anarazel.de, pryzby@telsasoft.com, robertmhaas@gmail.com, pgsql-hackers@lists.postgresql.org
Subject: Re: [EXTERNAL] Re: Add non-blocking version of PQcancel
In-Reply-To: <202402021505.6cuvlqgqj5si@alvherre.pgsql>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox