public inbox for [email protected]  

help / color / mirror / Atom feed

[PATCH] fixes to docs and comments
22+ messages / 2 participants
[nested] [flat]

* [PATCH] fixes to docs and comments
@ 2021-01-09 15:49  Justin Pryzby <[email protected]>
  0 siblings, 0 replies; 22+ messages in thread

From: Justin Pryzby @ 2021-01-09 15:49 UTC (permalink / raw)

---
 doc/src/sgml/config.sgml            | 10 +++---
 doc/src/sgml/libpq.sgml             | 23 ++++++++----
 doc/src/sgml/protocol.sgml          | 54 +++++++++++++----------------
 src/backend/libpq/pqcomm.c          |  2 +-
 src/common/zpq_stream.c             | 16 ++++-----
 src/include/common/zpq_stream.h     |  2 +-
 src/interfaces/libpq/fe-connect.c   |  2 +-
 src/interfaces/libpq/fe-protocol3.c | 26 +++++++-------
 8 files changed, 69 insertions(+), 66 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 3b132dcf27..8b5a6525ac 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1004,12 +1004,10 @@ include_dir 'conf.d'
       </term>
       <listitem>
        <para>
-        When this parameter is <literal>on</literal> (default), the <productname>PostgreSQL</productname>
-        server can switch on compression of traffic between server and client if it is requested by client.
-        Client sends to the server list of compression algorithms supported by frontend library,
-        server chooses one which is supported by backend library and sends it in compression acknowledgement message
-        to the client. This option allows to reject compression request even if it is supported by server
-        (due to security, CPU consumption or whatever else reasons...).
+        This parameter enables compression of libpq traffic between client and server.
+        The default is <literal>on</literal>.
+        This option allows rejecting compression requests even if it is supported by server
+        (for example, due to security, or CPU consumption).
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 2934908520..d4da390ca9 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1244,13 +1244,22 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>compression</literal></term>
       <listitem>
       <para>
-        Request compression of libpq traffic. Client sends to the server list of compression algorithms, supported by client library.
-        If server supports one of this algorithms, then it acknowledges use of this algorithm and then all libpq messages send both from client to server and
-        visa versa will be compressed. If server is not supporting any of the suggested algorithms, then it rejects client request to use compression
-        and it is up to the client whether to continue work without compression or report error.
-        Supported compression algorithms are chosen at configure time. Right now two libraries are supported: zlib (default) and zstd (if Postgres was
-        configured with --with-zstd option). In both cases streaming mode is used.
-        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+        Request compression of libpq traffic. The client sends a request with a list of compression algorithms.
+        Compression can be requested by a client by including the "compression" option in its connection string.
+        This can either be a boolean value to enable or disable compression
+        ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto", or an explicit list of comma-separated compression algorithms
+        which can optionally include compression level ("zlib,zstd:5").
+        If compression is enabled but an algorithm is not explicitly specified, the client library sends its full list of
+        supported algorithms and the server chooses a preferred algorithm.
+
+        If the server accepts one of the algorithms, it replies with an acknowledgment and all future libpq messages between client and server
+        will be compressed.
+        If the server rejects the compression request, it is up to the client whether to continue without compression or to report an error.
+        Support for compression algorithms must be enabled when the server is compiled.
+        Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
+        configured with --with-zstd option). In both cases, streaming mode is used.
+        By default, compression is not requested by the client.
+        Please note that using compression together with SSL may expose extra vulnerabilities:
         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;
       </para>
       </listitem>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 9f30aad8bd..a69f9bfc26 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -94,10 +94,10 @@
 
   <para>
     It is possible to compress protocol data to reduce traffic and speed-up client-server interaction.
-    Compression is especially useful for importing/exporting data to/from database using COPY command
-    and for replication (both physical and logical). Also compression can reduce server response time
-    in case of queries returning large amount of data (for example returning JSON, BLOBs, text,...)
-    Right now two libraries are supported: zlib (default) and zstd (if Postgres was
+    Compression is especially useful for importing/exporting data to/from the database using the <literal>COPY</literal> command
+    and for replication (both physical and logical). Compression can also reduce the server's response time
+    for queries returning a large amount of data (for example, JSON, BLOBs, text, ...).
+    Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
     configured with --with-zstd option).
   </para>
 
@@ -275,19 +275,14 @@
       <term>CompressionAck</term>
       <listitem>
        <para>
-         Server acknowledges using compression for client-server communication protocol.
-         Compression can be requested by client by including "compression" option in connection string.
-         It can be just boolean values enabling or disabling compression
-         ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto" or explicit list of compression algorithms
-         separated by comma with optional specification of compression level: "zlib,zstd:5".
-         If compression algorithm is not explicitly specified the most efficient one supported both by
-         client and server is chosen. Client sends to the server list of compression algorithms,
-         supported by client library.
-         If server supports one of this algorithms, then it acknowledges use of this algorithm and
-         all subsequent libpq messages send both from client to server and
-         visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-         index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-         and it is up to the client whether to continue work without compression or report error.
+         The server accepts the client's compression request.
+         Compression is requested when a client connection includes the "compression" option, which includes
+         a list of requested compression algorithms.
+         If the server accepts one of these algorithms, it acknowledges use of compression and
+         all subsequent libpq messages between the client and server will be compressed.
+         The server chooses an algorithm from the list specified by client and responds with the index of the chosen algorithm from the client-supplied list.
+         If the server does not accept any of the requested algorithms, then it replies with an index of -1
+         and it is up to the client whether to continue without compression or to report an error.
        </para>
       </listitem>
      </varlistentry>
@@ -3460,12 +3455,14 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-  Acknowledge use of compression for protocol data. Client sends to the server list of compression algorithms, supported by client library.
-  If server supports one of this algorithms, then it acknowledges use of this algorithm and all subsequent libpq messages send both from client to server and
-  visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-  index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-  and it is up to the client whether to continue work without compression or report error.
-  After receiving this message with algorithm index other than -1, both server and client are switched to compression mode
+  Acknowledge use of compression for protocol data. The client sends to the server a list of requested compression algorithms.
+  If the server supports any of these algorithms, it acknowledges use of this algorithm and all subsequent libpq messages between client and server
+  will be compressed.
+  The server selects the preferred algorithm from the list specified by client and responds with the
+  index of the chosen algorithm in this list.
+  If the server does not support any of the requested algorithms, it replies with -1
+  and it is up to the client whether to continue without compression or to report an error.
+  After receiving this message with algorithm index other than -1, both server and client switch to compressed mode
   and exchange compressed messages.
 </para>
 </listitem>
@@ -3486,7 +3483,7 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-        Index of algorithm in the list of supported algotihms specified by client or -1 if none of them is supported.
+        Index of algorithm in the list of supported algorithms specified by client or -1 if none of them are supported.
 </para>
 </listitem>
 </varlistentry>
@@ -6069,12 +6066,11 @@ StartupMessage (F)
 </term>
 <listitem>
 <para>
-                        Request compression of libpq traffic. Value is list of compression algorithms supported by client with optional
+                        Request compression of libpq traffic. The value is a list of compression algorithms requested by the client with an optional
                         specification of compression level: <literal>"zlib,zstd:5"</literal>.
-                        When connecting to an older backend, which does not support compression, or in case when the backend support compression
-                        but for some reason wants to disable it, the backend will just ignore the _pq_.compression parameter and won’t send
-                        the compressionAck message to the frontend.
-                        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+                        If the server does not accept compression, the backend will ignore the _pq_.compression
+                        parameter and will not send the CompressionAck message to the frontend.
+                        By default, compression is disabled. Please note that using compression together with SSL may expose extra vulnerabilities:
                         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;.
 </para>
 </listitem>
diff --git a/src/backend/libpq/pqcomm.c b/src/backend/libpq/pqcomm.c
index 8be1ce18de..f3293faf01 100644
--- a/src/backend/libpq/pqcomm.c
+++ b/src/backend/libpq/pqcomm.c
@@ -1073,7 +1073,7 @@ pq_recvbuf(bool nowait)
 	/* Can fill buffer from PqRecvLength and upwards */
 	for (;;)
 	{
-		/* If streaming compression is enabled then use correspondent compression read function. */
+		/* If streaming compression is enabled then use corresponding compression read function. */
 		r = PqStream
 			? zpq_read(PqStream, PqRecvBuffer + PqRecvLength,
 					   PQ_RECV_BUFFER_SIZE - PqRecvLength)
diff --git a/src/common/zpq_stream.c b/src/common/zpq_stream.c
index 459566228a..e044e83e7c 100644
--- a/src/common/zpq_stream.c
+++ b/src/common/zpq_stream.c
@@ -9,15 +9,15 @@
 typedef struct
 {
 	/*
-	 * Returns name of compression algorithm.
+	 * Name of compression algorithm.
 	 */
 	char const* (*name)(void);
 
 	/*
-	 * Create compression stream with using rx/tx function for fetching/sending compressed data.
+	 * Create compression stream with rx/tx function for reading/sending compressed data.
 	 * level: compression level
 	 * tx_func: function for writing compressed data in underlying stream
-	 * rx_func: function for receiving compressed data from underlying stream
+	 * rx_func: function for reading compressed data from underlying stream
 	 * arg: context passed to the function
      * rx_data: received data (compressed data already fetched from input stream)
 	 * rx_data_size: size of data fetched from input stream
@@ -27,14 +27,14 @@ typedef struct
 	/*
 	 * Read up to "size" raw (decompressed) bytes.
 	 * Returns number of decompressed bytes or error code.
-	 * Error code is either ZPQ_DECOMPRESS_ERROR either error code returned by the rx function.
+	 * Error code is either ZPQ_DECOMPRESS_ERROR or error code returned by the rx function.
 	 */
 	ssize_t (*read)(ZpqStream *zs, void *buf, size_t size);
 
 	/*
 	 * Write up to "size" raw (decompressed) bytes.
 	 * Returns number of written raw bytes or error code returned by tx function.
-	 * In the last case amount of written raw bytes is stored in *processed.
+	 * In the last case number of bytes written is stored in *processed.
 	 */
 	ssize_t (*write)(ZpqStream *zs, void const *buf, size_t size, size_t *processed);
 
@@ -49,12 +49,12 @@ typedef struct
 	char const* (*error)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal tx decompression buffer.
+	 * Return amount of data in internal tx decompression buffer.
 	 */
 	size_t  (*buffered_tx)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal rx compression buffer.
+	 * Return amount of data in internal rx compression buffer.
 	 */
 	size_t  (*buffered_rx)(ZpqStream *zs);
 } ZpqAlgorithm;
@@ -265,7 +265,7 @@ zstd_name(void)
 
 #define ZLIB_BUFFER_SIZE       8192 /* We have to flush stream after each protocol command
 									 * and command is mostly limited by record length,
-									 * which in turn usually less than page size (except TOAST)
+									 * which in turn is usually less than page size (except TOAST)
 									 */
 
 typedef struct ZlibStream
diff --git a/src/include/common/zpq_stream.h b/src/include/common/zpq_stream.h
index 27aef0aab9..991e2c0165 100644
--- a/src/include/common/zpq_stream.h
+++ b/src/include/common/zpq_stream.h
@@ -1,6 +1,6 @@
 /*
  * zpq_stream.h
- *     Streaiming compression for libpq
+ *     Streaming compression for libpq
  */
 
 #ifndef ZPQ_STREAM_H
diff --git a/src/interfaces/libpq/fe-connect.c b/src/interfaces/libpq/fe-connect.c
index eac6ef66cc..679f8cde9f 100644
--- a/src/interfaces/libpq/fe-connect.c
+++ b/src/interfaces/libpq/fe-connect.c
@@ -3269,7 +3269,7 @@ keep_going:						/* We will come back to here until there is
 						{
 							appendPQExpBuffer(&conn->errorMessage,
 											  libpq_gettext(
-												  "server is not supported requested compression algorithms %s\n"),
+												  "server does not support requested compression algorithms %s\n"),
 											  conn->compression);
 							goto error_return;
 						}
diff --git a/src/interfaces/libpq/fe-protocol3.c b/src/interfaces/libpq/fe-protocol3.c
index 095866bba0..5b879569b4 100644
--- a/src/interfaces/libpq/fe-protocol3.c
+++ b/src/interfaces/libpq/fe-protocol3.c
@@ -2135,15 +2135,15 @@ pqBuildStartupPacket3(PGconn *conn, int *packetlen,
 }
 
 /*
- * Build comma-separated list of compression algorithms suggested by client to the server.
- * It can be either explicitly specified by user in connection string, either
- * include all algorithms supported by clit library.
- * This functions returns true if compression string is successfully parsed and
- * stores comma-separated list of algorithms in *client_compressors.
- * If compression is disabled, then NULL is assigned to  *client_compressors.
- * Also it creates array of compressor descriptors, each element of which corresponds
- * the correspondent algorithm name in *client_compressors list. This array is stored in PGconn
- * and is used during handshake when compassion acknowledgment response is received from the server.
+ * Build comma-separated list of compression algorithms requested by client.
+ * It can be either explicitly specified by user in connection string, or
+ * include all algorithms supported by client library.
+ * This function returns true if the compression string is successfully parsed and
+ * stores a comma-separated list of algorithms in *client_compressors.
+ * If compression is disabled, then NULL is assigned to *client_compressors.
+ * Also it creates an array of compressor descriptors, each element of which corresponds to
+ * the corresponding algorithm name in *client_compressors list. This array is stored in PGconn
+ * and is used during handshake when a compression acknowledgment response is received from the server.
  */
 static bool
 build_compressors_list(PGconn *conn, char** client_compressors, bool build_descriptors)
@@ -2170,7 +2170,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 
 		if (n_supported_algorithms == 0)
 		{
-			*client_compressors = NULL; /* no compressors are avaialable */
+			*client_compressors = NULL; /* no compressors are available */
 			conn->compressors = NULL;
 			return true;
 		}
@@ -2204,7 +2204,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 	}
 	else
 	{
-		/* List of compresison algorithms separated by commas */
+		/* List of compression algorithms separated by commas */
 		char *src, *dst;
 		int n_suggested_algorithms = 0;
 		char* suggested_algorithms = strdup(value);
@@ -2232,7 +2232,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 				if (sscanf(col+1, "%d", &compression_level) != 1 && !build_descriptors)
 				{
 					fprintf(stderr,
-							libpq_gettext("WARNING: invlaid compression level %s in compression option '%s'\n"),
+							libpq_gettext("WARNING: invalid compression level %s in compression option '%s'\n"),
 							col+1, value);
 					return false;
 				}
@@ -2262,7 +2262,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 		{
 			if (!build_descriptors)
 				fprintf(stderr,
-						libpq_gettext("WARNING: none of specified algirthms %s is supported by client\n"),
+						libpq_gettext("WARNING: none of the specified algorithms are supported by client: %s\n"),
 						value);
 			else
 			{
-- 
2.17.0


--yudcn1FV7Hsu/q59--





^ permalink  raw  reply  [nested|flat] 22+ messages in thread

* [PATCH] fixes to docs and comments
@ 2021-01-09 15:49  Justin Pryzby <[email protected]>
  0 siblings, 0 replies; 22+ messages in thread

From: Justin Pryzby @ 2021-01-09 15:49 UTC (permalink / raw)

---
 doc/src/sgml/config.sgml            | 10 +++---
 doc/src/sgml/libpq.sgml             | 23 ++++++++----
 doc/src/sgml/protocol.sgml          | 54 +++++++++++++----------------
 src/backend/libpq/pqcomm.c          |  2 +-
 src/common/zpq_stream.c             | 16 ++++-----
 src/include/common/zpq_stream.h     |  2 +-
 src/interfaces/libpq/fe-connect.c   |  2 +-
 src/interfaces/libpq/fe-protocol3.c | 26 +++++++-------
 8 files changed, 69 insertions(+), 66 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 3b132dcf27..8b5a6525ac 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1004,12 +1004,10 @@ include_dir 'conf.d'
       </term>
       <listitem>
        <para>
-        When this parameter is <literal>on</literal> (default), the <productname>PostgreSQL</productname>
-        server can switch on compression of traffic between server and client if it is requested by client.
-        Client sends to the server list of compression algorithms supported by frontend library,
-        server chooses one which is supported by backend library and sends it in compression acknowledgement message
-        to the client. This option allows to reject compression request even if it is supported by server
-        (due to security, CPU consumption or whatever else reasons...).
+        This parameter enables compression of libpq traffic between client and server.
+        The default is <literal>on</literal>.
+        This option allows rejecting compression requests even if it is supported by server
+        (for example, due to security, or CPU consumption).
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 2934908520..d4da390ca9 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1244,13 +1244,22 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>compression</literal></term>
       <listitem>
       <para>
-        Request compression of libpq traffic. Client sends to the server list of compression algorithms, supported by client library.
-        If server supports one of this algorithms, then it acknowledges use of this algorithm and then all libpq messages send both from client to server and
-        visa versa will be compressed. If server is not supporting any of the suggested algorithms, then it rejects client request to use compression
-        and it is up to the client whether to continue work without compression or report error.
-        Supported compression algorithms are chosen at configure time. Right now two libraries are supported: zlib (default) and zstd (if Postgres was
-        configured with --with-zstd option). In both cases streaming mode is used.
-        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+        Request compression of libpq traffic. The client sends a request with a list of compression algorithms.
+        Compression can be requested by a client by including the "compression" option in its connection string.
+        This can either be a boolean value to enable or disable compression
+        ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto", or an explicit list of comma-separated compression algorithms
+        which can optionally include compression level ("zlib,zstd:5").
+        If compression is enabled but an algorithm is not explicitly specified, the client library sends its full list of
+        supported algorithms and the server chooses a preferred algorithm.
+
+        If the server accepts one of the algorithms, it replies with an acknowledgment and all future libpq messages between client and server
+        will be compressed.
+        If the server rejects the compression request, it is up to the client whether to continue without compression or to report an error.
+        Support for compression algorithms must be enabled when the server is compiled.
+        Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
+        configured with --with-zstd option). In both cases, streaming mode is used.
+        By default, compression is not requested by the client.
+        Please note that using compression together with SSL may expose extra vulnerabilities:
         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;
       </para>
       </listitem>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 9f30aad8bd..a69f9bfc26 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -94,10 +94,10 @@
 
   <para>
     It is possible to compress protocol data to reduce traffic and speed-up client-server interaction.
-    Compression is especially useful for importing/exporting data to/from database using COPY command
-    and for replication (both physical and logical). Also compression can reduce server response time
-    in case of queries returning large amount of data (for example returning JSON, BLOBs, text,...)
-    Right now two libraries are supported: zlib (default) and zstd (if Postgres was
+    Compression is especially useful for importing/exporting data to/from the database using the <literal>COPY</literal> command
+    and for replication (both physical and logical). Compression can also reduce the server's response time
+    for queries returning a large amount of data (for example, JSON, BLOBs, text, ...).
+    Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
     configured with --with-zstd option).
   </para>
 
@@ -275,19 +275,14 @@
       <term>CompressionAck</term>
       <listitem>
        <para>
-         Server acknowledges using compression for client-server communication protocol.
-         Compression can be requested by client by including "compression" option in connection string.
-         It can be just boolean values enabling or disabling compression
-         ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto" or explicit list of compression algorithms
-         separated by comma with optional specification of compression level: "zlib,zstd:5".
-         If compression algorithm is not explicitly specified the most efficient one supported both by
-         client and server is chosen. Client sends to the server list of compression algorithms,
-         supported by client library.
-         If server supports one of this algorithms, then it acknowledges use of this algorithm and
-         all subsequent libpq messages send both from client to server and
-         visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-         index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-         and it is up to the client whether to continue work without compression or report error.
+         The server accepts the client's compression request.
+         Compression is requested when a client connection includes the "compression" option, which includes
+         a list of requested compression algorithms.
+         If the server accepts one of these algorithms, it acknowledges use of compression and
+         all subsequent libpq messages between the client and server will be compressed.
+         The server chooses an algorithm from the list specified by client and responds with the index of the chosen algorithm from the client-supplied list.
+         If the server does not accept any of the requested algorithms, then it replies with an index of -1
+         and it is up to the client whether to continue without compression or to report an error.
        </para>
       </listitem>
      </varlistentry>
@@ -3460,12 +3455,14 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-  Acknowledge use of compression for protocol data. Client sends to the server list of compression algorithms, supported by client library.
-  If server supports one of this algorithms, then it acknowledges use of this algorithm and all subsequent libpq messages send both from client to server and
-  visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-  index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-  and it is up to the client whether to continue work without compression or report error.
-  After receiving this message with algorithm index other than -1, both server and client are switched to compression mode
+  Acknowledge use of compression for protocol data. The client sends to the server a list of requested compression algorithms.
+  If the server supports any of these algorithms, it acknowledges use of this algorithm and all subsequent libpq messages between client and server
+  will be compressed.
+  The server selects the preferred algorithm from the list specified by client and responds with the
+  index of the chosen algorithm in this list.
+  If the server does not support any of the requested algorithms, it replies with -1
+  and it is up to the client whether to continue without compression or to report an error.
+  After receiving this message with algorithm index other than -1, both server and client switch to compressed mode
   and exchange compressed messages.
 </para>
 </listitem>
@@ -3486,7 +3483,7 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-        Index of algorithm in the list of supported algotihms specified by client or -1 if none of them is supported.
+        Index of algorithm in the list of supported algorithms specified by client or -1 if none of them are supported.
 </para>
 </listitem>
 </varlistentry>
@@ -6069,12 +6066,11 @@ StartupMessage (F)
 </term>
 <listitem>
 <para>
-                        Request compression of libpq traffic. Value is list of compression algorithms supported by client with optional
+                        Request compression of libpq traffic. The value is a list of compression algorithms requested by the client with an optional
                         specification of compression level: <literal>"zlib,zstd:5"</literal>.
-                        When connecting to an older backend, which does not support compression, or in case when the backend support compression
-                        but for some reason wants to disable it, the backend will just ignore the _pq_.compression parameter and won’t send
-                        the compressionAck message to the frontend.
-                        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+                        If the server does not accept compression, the backend will ignore the _pq_.compression
+                        parameter and will not send the CompressionAck message to the frontend.
+                        By default, compression is disabled. Please note that using compression together with SSL may expose extra vulnerabilities:
                         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;.
 </para>
 </listitem>
diff --git a/src/backend/libpq/pqcomm.c b/src/backend/libpq/pqcomm.c
index 8be1ce18de..f3293faf01 100644
--- a/src/backend/libpq/pqcomm.c
+++ b/src/backend/libpq/pqcomm.c
@@ -1073,7 +1073,7 @@ pq_recvbuf(bool nowait)
 	/* Can fill buffer from PqRecvLength and upwards */
 	for (;;)
 	{
-		/* If streaming compression is enabled then use correspondent compression read function. */
+		/* If streaming compression is enabled then use corresponding compression read function. */
 		r = PqStream
 			? zpq_read(PqStream, PqRecvBuffer + PqRecvLength,
 					   PQ_RECV_BUFFER_SIZE - PqRecvLength)
diff --git a/src/common/zpq_stream.c b/src/common/zpq_stream.c
index 459566228a..e044e83e7c 100644
--- a/src/common/zpq_stream.c
+++ b/src/common/zpq_stream.c
@@ -9,15 +9,15 @@
 typedef struct
 {
 	/*
-	 * Returns name of compression algorithm.
+	 * Name of compression algorithm.
 	 */
 	char const* (*name)(void);
 
 	/*
-	 * Create compression stream with using rx/tx function for fetching/sending compressed data.
+	 * Create compression stream with rx/tx function for reading/sending compressed data.
 	 * level: compression level
 	 * tx_func: function for writing compressed data in underlying stream
-	 * rx_func: function for receiving compressed data from underlying stream
+	 * rx_func: function for reading compressed data from underlying stream
 	 * arg: context passed to the function
      * rx_data: received data (compressed data already fetched from input stream)
 	 * rx_data_size: size of data fetched from input stream
@@ -27,14 +27,14 @@ typedef struct
 	/*
 	 * Read up to "size" raw (decompressed) bytes.
 	 * Returns number of decompressed bytes or error code.
-	 * Error code is either ZPQ_DECOMPRESS_ERROR either error code returned by the rx function.
+	 * Error code is either ZPQ_DECOMPRESS_ERROR or error code returned by the rx function.
 	 */
 	ssize_t (*read)(ZpqStream *zs, void *buf, size_t size);
 
 	/*
 	 * Write up to "size" raw (decompressed) bytes.
 	 * Returns number of written raw bytes or error code returned by tx function.
-	 * In the last case amount of written raw bytes is stored in *processed.
+	 * In the last case number of bytes written is stored in *processed.
 	 */
 	ssize_t (*write)(ZpqStream *zs, void const *buf, size_t size, size_t *processed);
 
@@ -49,12 +49,12 @@ typedef struct
 	char const* (*error)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal tx decompression buffer.
+	 * Return amount of data in internal tx decompression buffer.
 	 */
 	size_t  (*buffered_tx)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal rx compression buffer.
+	 * Return amount of data in internal rx compression buffer.
 	 */
 	size_t  (*buffered_rx)(ZpqStream *zs);
 } ZpqAlgorithm;
@@ -265,7 +265,7 @@ zstd_name(void)
 
 #define ZLIB_BUFFER_SIZE       8192 /* We have to flush stream after each protocol command
 									 * and command is mostly limited by record length,
-									 * which in turn usually less than page size (except TOAST)
+									 * which in turn is usually less than page size (except TOAST)
 									 */
 
 typedef struct ZlibStream
diff --git a/src/include/common/zpq_stream.h b/src/include/common/zpq_stream.h
index 27aef0aab9..991e2c0165 100644
--- a/src/include/common/zpq_stream.h
+++ b/src/include/common/zpq_stream.h
@@ -1,6 +1,6 @@
 /*
  * zpq_stream.h
- *     Streaiming compression for libpq
+ *     Streaming compression for libpq
  */
 
 #ifndef ZPQ_STREAM_H
diff --git a/src/interfaces/libpq/fe-connect.c b/src/interfaces/libpq/fe-connect.c
index eac6ef66cc..679f8cde9f 100644
--- a/src/interfaces/libpq/fe-connect.c
+++ b/src/interfaces/libpq/fe-connect.c
@@ -3269,7 +3269,7 @@ keep_going:						/* We will come back to here until there is
 						{
 							appendPQExpBuffer(&conn->errorMessage,
 											  libpq_gettext(
-												  "server is not supported requested compression algorithms %s\n"),
+												  "server does not support requested compression algorithms %s\n"),
 											  conn->compression);
 							goto error_return;
 						}
diff --git a/src/interfaces/libpq/fe-protocol3.c b/src/interfaces/libpq/fe-protocol3.c
index 095866bba0..5b879569b4 100644
--- a/src/interfaces/libpq/fe-protocol3.c
+++ b/src/interfaces/libpq/fe-protocol3.c
@@ -2135,15 +2135,15 @@ pqBuildStartupPacket3(PGconn *conn, int *packetlen,
 }
 
 /*
- * Build comma-separated list of compression algorithms suggested by client to the server.
- * It can be either explicitly specified by user in connection string, either
- * include all algorithms supported by clit library.
- * This functions returns true if compression string is successfully parsed and
- * stores comma-separated list of algorithms in *client_compressors.
- * If compression is disabled, then NULL is assigned to  *client_compressors.
- * Also it creates array of compressor descriptors, each element of which corresponds
- * the correspondent algorithm name in *client_compressors list. This array is stored in PGconn
- * and is used during handshake when compassion acknowledgment response is received from the server.
+ * Build comma-separated list of compression algorithms requested by client.
+ * It can be either explicitly specified by user in connection string, or
+ * include all algorithms supported by client library.
+ * This function returns true if the compression string is successfully parsed and
+ * stores a comma-separated list of algorithms in *client_compressors.
+ * If compression is disabled, then NULL is assigned to *client_compressors.
+ * Also it creates an array of compressor descriptors, each element of which corresponds to
+ * the corresponding algorithm name in *client_compressors list. This array is stored in PGconn
+ * and is used during handshake when a compression acknowledgment response is received from the server.
  */
 static bool
 build_compressors_list(PGconn *conn, char** client_compressors, bool build_descriptors)
@@ -2170,7 +2170,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 
 		if (n_supported_algorithms == 0)
 		{
-			*client_compressors = NULL; /* no compressors are avaialable */
+			*client_compressors = NULL; /* no compressors are available */
 			conn->compressors = NULL;
 			return true;
 		}
@@ -2204,7 +2204,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 	}
 	else
 	{
-		/* List of compresison algorithms separated by commas */
+		/* List of compression algorithms separated by commas */
 		char *src, *dst;
 		int n_suggested_algorithms = 0;
 		char* suggested_algorithms = strdup(value);
@@ -2232,7 +2232,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 				if (sscanf(col+1, "%d", &compression_level) != 1 && !build_descriptors)
 				{
 					fprintf(stderr,
-							libpq_gettext("WARNING: invlaid compression level %s in compression option '%s'\n"),
+							libpq_gettext("WARNING: invalid compression level %s in compression option '%s'\n"),
 							col+1, value);
 					return false;
 				}
@@ -2262,7 +2262,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 		{
 			if (!build_descriptors)
 				fprintf(stderr,
-						libpq_gettext("WARNING: none of specified algirthms %s is supported by client\n"),
+						libpq_gettext("WARNING: none of the specified algorithms are supported by client: %s\n"),
 						value);
 			else
 			{
-- 
2.17.0


--yudcn1FV7Hsu/q59--





^ permalink  raw  reply  [nested|flat] 22+ messages in thread

* [PATCH] fixes to docs and comments
@ 2021-01-09 15:49  Justin Pryzby <[email protected]>
  0 siblings, 0 replies; 22+ messages in thread

From: Justin Pryzby @ 2021-01-09 15:49 UTC (permalink / raw)

---
 doc/src/sgml/config.sgml            | 10 +++---
 doc/src/sgml/libpq.sgml             | 23 ++++++++----
 doc/src/sgml/protocol.sgml          | 54 +++++++++++++----------------
 src/backend/libpq/pqcomm.c          |  2 +-
 src/common/zpq_stream.c             | 16 ++++-----
 src/include/common/zpq_stream.h     |  2 +-
 src/interfaces/libpq/fe-connect.c   |  2 +-
 src/interfaces/libpq/fe-protocol3.c | 26 +++++++-------
 8 files changed, 69 insertions(+), 66 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 3b132dcf27..8b5a6525ac 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1004,12 +1004,10 @@ include_dir 'conf.d'
       </term>
       <listitem>
        <para>
-        When this parameter is <literal>on</literal> (default), the <productname>PostgreSQL</productname>
-        server can switch on compression of traffic between server and client if it is requested by client.
-        Client sends to the server list of compression algorithms supported by frontend library,
-        server chooses one which is supported by backend library and sends it in compression acknowledgement message
-        to the client. This option allows to reject compression request even if it is supported by server
-        (due to security, CPU consumption or whatever else reasons...).
+        This parameter enables compression of libpq traffic between client and server.
+        The default is <literal>on</literal>.
+        This option allows rejecting compression requests even if it is supported by server
+        (for example, due to security, or CPU consumption).
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 2934908520..d4da390ca9 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1244,13 +1244,22 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>compression</literal></term>
       <listitem>
       <para>
-        Request compression of libpq traffic. Client sends to the server list of compression algorithms, supported by client library.
-        If server supports one of this algorithms, then it acknowledges use of this algorithm and then all libpq messages send both from client to server and
-        visa versa will be compressed. If server is not supporting any of the suggested algorithms, then it rejects client request to use compression
-        and it is up to the client whether to continue work without compression or report error.
-        Supported compression algorithms are chosen at configure time. Right now two libraries are supported: zlib (default) and zstd (if Postgres was
-        configured with --with-zstd option). In both cases streaming mode is used.
-        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+        Request compression of libpq traffic. The client sends a request with a list of compression algorithms.
+        Compression can be requested by a client by including the "compression" option in its connection string.
+        This can either be a boolean value to enable or disable compression
+        ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto", or an explicit list of comma-separated compression algorithms
+        which can optionally include compression level ("zlib,zstd:5").
+        If compression is enabled but an algorithm is not explicitly specified, the client library sends its full list of
+        supported algorithms and the server chooses a preferred algorithm.
+
+        If the server accepts one of the algorithms, it replies with an acknowledgment and all future libpq messages between client and server
+        will be compressed.
+        If the server rejects the compression request, it is up to the client whether to continue without compression or to report an error.
+        Support for compression algorithms must be enabled when the server is compiled.
+        Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
+        configured with --with-zstd option). In both cases, streaming mode is used.
+        By default, compression is not requested by the client.
+        Please note that using compression together with SSL may expose extra vulnerabilities:
         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;
       </para>
       </listitem>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 9f30aad8bd..a69f9bfc26 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -94,10 +94,10 @@
 
   <para>
     It is possible to compress protocol data to reduce traffic and speed-up client-server interaction.
-    Compression is especially useful for importing/exporting data to/from database using COPY command
-    and for replication (both physical and logical). Also compression can reduce server response time
-    in case of queries returning large amount of data (for example returning JSON, BLOBs, text,...)
-    Right now two libraries are supported: zlib (default) and zstd (if Postgres was
+    Compression is especially useful for importing/exporting data to/from the database using the <literal>COPY</literal> command
+    and for replication (both physical and logical). Compression can also reduce the server's response time
+    for queries returning a large amount of data (for example, JSON, BLOBs, text, ...).
+    Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
     configured with --with-zstd option).
   </para>
 
@@ -275,19 +275,14 @@
       <term>CompressionAck</term>
       <listitem>
        <para>
-         Server acknowledges using compression for client-server communication protocol.
-         Compression can be requested by client by including "compression" option in connection string.
-         It can be just boolean values enabling or disabling compression
-         ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto" or explicit list of compression algorithms
-         separated by comma with optional specification of compression level: "zlib,zstd:5".
-         If compression algorithm is not explicitly specified the most efficient one supported both by
-         client and server is chosen. Client sends to the server list of compression algorithms,
-         supported by client library.
-         If server supports one of this algorithms, then it acknowledges use of this algorithm and
-         all subsequent libpq messages send both from client to server and
-         visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-         index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-         and it is up to the client whether to continue work without compression or report error.
+         The server accepts the client's compression request.
+         Compression is requested when a client connection includes the "compression" option, which includes
+         a list of requested compression algorithms.
+         If the server accepts one of these algorithms, it acknowledges use of compression and
+         all subsequent libpq messages between the client and server will be compressed.
+         The server chooses an algorithm from the list specified by client and responds with the index of the chosen algorithm from the client-supplied list.
+         If the server does not accept any of the requested algorithms, then it replies with an index of -1
+         and it is up to the client whether to continue without compression or to report an error.
        </para>
       </listitem>
      </varlistentry>
@@ -3460,12 +3455,14 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-  Acknowledge use of compression for protocol data. Client sends to the server list of compression algorithms, supported by client library.
-  If server supports one of this algorithms, then it acknowledges use of this algorithm and all subsequent libpq messages send both from client to server and
-  visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-  index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-  and it is up to the client whether to continue work without compression or report error.
-  After receiving this message with algorithm index other than -1, both server and client are switched to compression mode
+  Acknowledge use of compression for protocol data. The client sends to the server a list of requested compression algorithms.
+  If the server supports any of these algorithms, it acknowledges use of this algorithm and all subsequent libpq messages between client and server
+  will be compressed.
+  The server selects the preferred algorithm from the list specified by client and responds with the
+  index of the chosen algorithm in this list.
+  If the server does not support any of the requested algorithms, it replies with -1
+  and it is up to the client whether to continue without compression or to report an error.
+  After receiving this message with algorithm index other than -1, both server and client switch to compressed mode
   and exchange compressed messages.
 </para>
 </listitem>
@@ -3486,7 +3483,7 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-        Index of algorithm in the list of supported algotihms specified by client or -1 if none of them is supported.
+        Index of algorithm in the list of supported algorithms specified by client or -1 if none of them are supported.
 </para>
 </listitem>
 </varlistentry>
@@ -6069,12 +6066,11 @@ StartupMessage (F)
 </term>
 <listitem>
 <para>
-                        Request compression of libpq traffic. Value is list of compression algorithms supported by client with optional
+                        Request compression of libpq traffic. The value is a list of compression algorithms requested by the client with an optional
                         specification of compression level: <literal>"zlib,zstd:5"</literal>.
-                        When connecting to an older backend, which does not support compression, or in case when the backend support compression
-                        but for some reason wants to disable it, the backend will just ignore the _pq_.compression parameter and won’t send
-                        the compressionAck message to the frontend.
-                        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+                        If the server does not accept compression, the backend will ignore the _pq_.compression
+                        parameter and will not send the CompressionAck message to the frontend.
+                        By default, compression is disabled. Please note that using compression together with SSL may expose extra vulnerabilities:
                         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;.
 </para>
 </listitem>
diff --git a/src/backend/libpq/pqcomm.c b/src/backend/libpq/pqcomm.c
index 8be1ce18de..f3293faf01 100644
--- a/src/backend/libpq/pqcomm.c
+++ b/src/backend/libpq/pqcomm.c
@@ -1073,7 +1073,7 @@ pq_recvbuf(bool nowait)
 	/* Can fill buffer from PqRecvLength and upwards */
 	for (;;)
 	{
-		/* If streaming compression is enabled then use correspondent compression read function. */
+		/* If streaming compression is enabled then use corresponding compression read function. */
 		r = PqStream
 			? zpq_read(PqStream, PqRecvBuffer + PqRecvLength,
 					   PQ_RECV_BUFFER_SIZE - PqRecvLength)
diff --git a/src/common/zpq_stream.c b/src/common/zpq_stream.c
index 459566228a..e044e83e7c 100644
--- a/src/common/zpq_stream.c
+++ b/src/common/zpq_stream.c
@@ -9,15 +9,15 @@
 typedef struct
 {
 	/*
-	 * Returns name of compression algorithm.
+	 * Name of compression algorithm.
 	 */
 	char const* (*name)(void);
 
 	/*
-	 * Create compression stream with using rx/tx function for fetching/sending compressed data.
+	 * Create compression stream with rx/tx function for reading/sending compressed data.
 	 * level: compression level
 	 * tx_func: function for writing compressed data in underlying stream
-	 * rx_func: function for receiving compressed data from underlying stream
+	 * rx_func: function for reading compressed data from underlying stream
 	 * arg: context passed to the function
      * rx_data: received data (compressed data already fetched from input stream)
 	 * rx_data_size: size of data fetched from input stream
@@ -27,14 +27,14 @@ typedef struct
 	/*
 	 * Read up to "size" raw (decompressed) bytes.
 	 * Returns number of decompressed bytes or error code.
-	 * Error code is either ZPQ_DECOMPRESS_ERROR either error code returned by the rx function.
+	 * Error code is either ZPQ_DECOMPRESS_ERROR or error code returned by the rx function.
 	 */
 	ssize_t (*read)(ZpqStream *zs, void *buf, size_t size);
 
 	/*
 	 * Write up to "size" raw (decompressed) bytes.
 	 * Returns number of written raw bytes or error code returned by tx function.
-	 * In the last case amount of written raw bytes is stored in *processed.
+	 * In the last case number of bytes written is stored in *processed.
 	 */
 	ssize_t (*write)(ZpqStream *zs, void const *buf, size_t size, size_t *processed);
 
@@ -49,12 +49,12 @@ typedef struct
 	char const* (*error)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal tx decompression buffer.
+	 * Return amount of data in internal tx decompression buffer.
 	 */
 	size_t  (*buffered_tx)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal rx compression buffer.
+	 * Return amount of data in internal rx compression buffer.
 	 */
 	size_t  (*buffered_rx)(ZpqStream *zs);
 } ZpqAlgorithm;
@@ -265,7 +265,7 @@ zstd_name(void)
 
 #define ZLIB_BUFFER_SIZE       8192 /* We have to flush stream after each protocol command
 									 * and command is mostly limited by record length,
-									 * which in turn usually less than page size (except TOAST)
+									 * which in turn is usually less than page size (except TOAST)
 									 */
 
 typedef struct ZlibStream
diff --git a/src/include/common/zpq_stream.h b/src/include/common/zpq_stream.h
index 27aef0aab9..991e2c0165 100644
--- a/src/include/common/zpq_stream.h
+++ b/src/include/common/zpq_stream.h
@@ -1,6 +1,6 @@
 /*
  * zpq_stream.h
- *     Streaiming compression for libpq
+ *     Streaming compression for libpq
  */
 
 #ifndef ZPQ_STREAM_H
diff --git a/src/interfaces/libpq/fe-connect.c b/src/interfaces/libpq/fe-connect.c
index eac6ef66cc..679f8cde9f 100644
--- a/src/interfaces/libpq/fe-connect.c
+++ b/src/interfaces/libpq/fe-connect.c
@@ -3269,7 +3269,7 @@ keep_going:						/* We will come back to here until there is
 						{
 							appendPQExpBuffer(&conn->errorMessage,
 											  libpq_gettext(
-												  "server is not supported requested compression algorithms %s\n"),
+												  "server does not support requested compression algorithms %s\n"),
 											  conn->compression);
 							goto error_return;
 						}
diff --git a/src/interfaces/libpq/fe-protocol3.c b/src/interfaces/libpq/fe-protocol3.c
index 095866bba0..5b879569b4 100644
--- a/src/interfaces/libpq/fe-protocol3.c
+++ b/src/interfaces/libpq/fe-protocol3.c
@@ -2135,15 +2135,15 @@ pqBuildStartupPacket3(PGconn *conn, int *packetlen,
 }
 
 /*
- * Build comma-separated list of compression algorithms suggested by client to the server.
- * It can be either explicitly specified by user in connection string, either
- * include all algorithms supported by clit library.
- * This functions returns true if compression string is successfully parsed and
- * stores comma-separated list of algorithms in *client_compressors.
- * If compression is disabled, then NULL is assigned to  *client_compressors.
- * Also it creates array of compressor descriptors, each element of which corresponds
- * the correspondent algorithm name in *client_compressors list. This array is stored in PGconn
- * and is used during handshake when compassion acknowledgment response is received from the server.
+ * Build comma-separated list of compression algorithms requested by client.
+ * It can be either explicitly specified by user in connection string, or
+ * include all algorithms supported by client library.
+ * This function returns true if the compression string is successfully parsed and
+ * stores a comma-separated list of algorithms in *client_compressors.
+ * If compression is disabled, then NULL is assigned to *client_compressors.
+ * Also it creates an array of compressor descriptors, each element of which corresponds to
+ * the corresponding algorithm name in *client_compressors list. This array is stored in PGconn
+ * and is used during handshake when a compression acknowledgment response is received from the server.
  */
 static bool
 build_compressors_list(PGconn *conn, char** client_compressors, bool build_descriptors)
@@ -2170,7 +2170,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 
 		if (n_supported_algorithms == 0)
 		{
-			*client_compressors = NULL; /* no compressors are avaialable */
+			*client_compressors = NULL; /* no compressors are available */
 			conn->compressors = NULL;
 			return true;
 		}
@@ -2204,7 +2204,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 	}
 	else
 	{
-		/* List of compresison algorithms separated by commas */
+		/* List of compression algorithms separated by commas */
 		char *src, *dst;
 		int n_suggested_algorithms = 0;
 		char* suggested_algorithms = strdup(value);
@@ -2232,7 +2232,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 				if (sscanf(col+1, "%d", &compression_level) != 1 && !build_descriptors)
 				{
 					fprintf(stderr,
-							libpq_gettext("WARNING: invlaid compression level %s in compression option '%s'\n"),
+							libpq_gettext("WARNING: invalid compression level %s in compression option '%s'\n"),
 							col+1, value);
 					return false;
 				}
@@ -2262,7 +2262,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 		{
 			if (!build_descriptors)
 				fprintf(stderr,
-						libpq_gettext("WARNING: none of specified algirthms %s is supported by client\n"),
+						libpq_gettext("WARNING: none of the specified algorithms are supported by client: %s\n"),
 						value);
 			else
 			{
-- 
2.17.0


--yudcn1FV7Hsu/q59--





^ permalink  raw  reply  [nested|flat] 22+ messages in thread

* [PATCH] fixes to docs and comments
@ 2021-01-09 15:49  Justin Pryzby <[email protected]>
  0 siblings, 0 replies; 22+ messages in thread

From: Justin Pryzby @ 2021-01-09 15:49 UTC (permalink / raw)

---
 doc/src/sgml/config.sgml            | 10 +++---
 doc/src/sgml/libpq.sgml             | 23 ++++++++----
 doc/src/sgml/protocol.sgml          | 54 +++++++++++++----------------
 src/backend/libpq/pqcomm.c          |  2 +-
 src/common/zpq_stream.c             | 16 ++++-----
 src/include/common/zpq_stream.h     |  2 +-
 src/interfaces/libpq/fe-connect.c   |  2 +-
 src/interfaces/libpq/fe-protocol3.c | 26 +++++++-------
 8 files changed, 69 insertions(+), 66 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 3b132dcf27..8b5a6525ac 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1004,12 +1004,10 @@ include_dir 'conf.d'
       </term>
       <listitem>
        <para>
-        When this parameter is <literal>on</literal> (default), the <productname>PostgreSQL</productname>
-        server can switch on compression of traffic between server and client if it is requested by client.
-        Client sends to the server list of compression algorithms supported by frontend library,
-        server chooses one which is supported by backend library and sends it in compression acknowledgement message
-        to the client. This option allows to reject compression request even if it is supported by server
-        (due to security, CPU consumption or whatever else reasons...).
+        This parameter enables compression of libpq traffic between client and server.
+        The default is <literal>on</literal>.
+        This option allows rejecting compression requests even if it is supported by server
+        (for example, due to security, or CPU consumption).
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 2934908520..d4da390ca9 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1244,13 +1244,22 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>compression</literal></term>
       <listitem>
       <para>
-        Request compression of libpq traffic. Client sends to the server list of compression algorithms, supported by client library.
-        If server supports one of this algorithms, then it acknowledges use of this algorithm and then all libpq messages send both from client to server and
-        visa versa will be compressed. If server is not supporting any of the suggested algorithms, then it rejects client request to use compression
-        and it is up to the client whether to continue work without compression or report error.
-        Supported compression algorithms are chosen at configure time. Right now two libraries are supported: zlib (default) and zstd (if Postgres was
-        configured with --with-zstd option). In both cases streaming mode is used.
-        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+        Request compression of libpq traffic. The client sends a request with a list of compression algorithms.
+        Compression can be requested by a client by including the "compression" option in its connection string.
+        This can either be a boolean value to enable or disable compression
+        ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto", or an explicit list of comma-separated compression algorithms
+        which can optionally include compression level ("zlib,zstd:5").
+        If compression is enabled but an algorithm is not explicitly specified, the client library sends its full list of
+        supported algorithms and the server chooses a preferred algorithm.
+
+        If the server accepts one of the algorithms, it replies with an acknowledgment and all future libpq messages between client and server
+        will be compressed.
+        If the server rejects the compression request, it is up to the client whether to continue without compression or to report an error.
+        Support for compression algorithms must be enabled when the server is compiled.
+        Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
+        configured with --with-zstd option). In both cases, streaming mode is used.
+        By default, compression is not requested by the client.
+        Please note that using compression together with SSL may expose extra vulnerabilities:
         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;
       </para>
       </listitem>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 9f30aad8bd..a69f9bfc26 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -94,10 +94,10 @@
 
   <para>
     It is possible to compress protocol data to reduce traffic and speed-up client-server interaction.
-    Compression is especially useful for importing/exporting data to/from database using COPY command
-    and for replication (both physical and logical). Also compression can reduce server response time
-    in case of queries returning large amount of data (for example returning JSON, BLOBs, text,...)
-    Right now two libraries are supported: zlib (default) and zstd (if Postgres was
+    Compression is especially useful for importing/exporting data to/from the database using the <literal>COPY</literal> command
+    and for replication (both physical and logical). Compression can also reduce the server's response time
+    for queries returning a large amount of data (for example, JSON, BLOBs, text, ...).
+    Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
     configured with --with-zstd option).
   </para>
 
@@ -275,19 +275,14 @@
       <term>CompressionAck</term>
       <listitem>
        <para>
-         Server acknowledges using compression for client-server communication protocol.
-         Compression can be requested by client by including "compression" option in connection string.
-         It can be just boolean values enabling or disabling compression
-         ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto" or explicit list of compression algorithms
-         separated by comma with optional specification of compression level: "zlib,zstd:5".
-         If compression algorithm is not explicitly specified the most efficient one supported both by
-         client and server is chosen. Client sends to the server list of compression algorithms,
-         supported by client library.
-         If server supports one of this algorithms, then it acknowledges use of this algorithm and
-         all subsequent libpq messages send both from client to server and
-         visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-         index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-         and it is up to the client whether to continue work without compression or report error.
+         The server accepts the client's compression request.
+         Compression is requested when a client connection includes the "compression" option, which includes
+         a list of requested compression algorithms.
+         If the server accepts one of these algorithms, it acknowledges use of compression and
+         all subsequent libpq messages between the client and server will be compressed.
+         The server chooses an algorithm from the list specified by client and responds with the index of the chosen algorithm from the client-supplied list.
+         If the server does not accept any of the requested algorithms, then it replies with an index of -1
+         and it is up to the client whether to continue without compression or to report an error.
        </para>
       </listitem>
      </varlistentry>
@@ -3460,12 +3455,14 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-  Acknowledge use of compression for protocol data. Client sends to the server list of compression algorithms, supported by client library.
-  If server supports one of this algorithms, then it acknowledges use of this algorithm and all subsequent libpq messages send both from client to server and
-  visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-  index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-  and it is up to the client whether to continue work without compression or report error.
-  After receiving this message with algorithm index other than -1, both server and client are switched to compression mode
+  Acknowledge use of compression for protocol data. The client sends to the server a list of requested compression algorithms.
+  If the server supports any of these algorithms, it acknowledges use of this algorithm and all subsequent libpq messages between client and server
+  will be compressed.
+  The server selects the preferred algorithm from the list specified by client and responds with the
+  index of the chosen algorithm in this list.
+  If the server does not support any of the requested algorithms, it replies with -1
+  and it is up to the client whether to continue without compression or to report an error.
+  After receiving this message with algorithm index other than -1, both server and client switch to compressed mode
   and exchange compressed messages.
 </para>
 </listitem>
@@ -3486,7 +3483,7 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-        Index of algorithm in the list of supported algotihms specified by client or -1 if none of them is supported.
+        Index of algorithm in the list of supported algorithms specified by client or -1 if none of them are supported.
 </para>
 </listitem>
 </varlistentry>
@@ -6069,12 +6066,11 @@ StartupMessage (F)
 </term>
 <listitem>
 <para>
-                        Request compression of libpq traffic. Value is list of compression algorithms supported by client with optional
+                        Request compression of libpq traffic. The value is a list of compression algorithms requested by the client with an optional
                         specification of compression level: <literal>"zlib,zstd:5"</literal>.
-                        When connecting to an older backend, which does not support compression, or in case when the backend support compression
-                        but for some reason wants to disable it, the backend will just ignore the _pq_.compression parameter and won’t send
-                        the compressionAck message to the frontend.
-                        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+                        If the server does not accept compression, the backend will ignore the _pq_.compression
+                        parameter and will not send the CompressionAck message to the frontend.
+                        By default, compression is disabled. Please note that using compression together with SSL may expose extra vulnerabilities:
                         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;.
 </para>
 </listitem>
diff --git a/src/backend/libpq/pqcomm.c b/src/backend/libpq/pqcomm.c
index 8be1ce18de..f3293faf01 100644
--- a/src/backend/libpq/pqcomm.c
+++ b/src/backend/libpq/pqcomm.c
@@ -1073,7 +1073,7 @@ pq_recvbuf(bool nowait)
 	/* Can fill buffer from PqRecvLength and upwards */
 	for (;;)
 	{
-		/* If streaming compression is enabled then use correspondent compression read function. */
+		/* If streaming compression is enabled then use corresponding compression read function. */
 		r = PqStream
 			? zpq_read(PqStream, PqRecvBuffer + PqRecvLength,
 					   PQ_RECV_BUFFER_SIZE - PqRecvLength)
diff --git a/src/common/zpq_stream.c b/src/common/zpq_stream.c
index 459566228a..e044e83e7c 100644
--- a/src/common/zpq_stream.c
+++ b/src/common/zpq_stream.c
@@ -9,15 +9,15 @@
 typedef struct
 {
 	/*
-	 * Returns name of compression algorithm.
+	 * Name of compression algorithm.
 	 */
 	char const* (*name)(void);
 
 	/*
-	 * Create compression stream with using rx/tx function for fetching/sending compressed data.
+	 * Create compression stream with rx/tx function for reading/sending compressed data.
 	 * level: compression level
 	 * tx_func: function for writing compressed data in underlying stream
-	 * rx_func: function for receiving compressed data from underlying stream
+	 * rx_func: function for reading compressed data from underlying stream
 	 * arg: context passed to the function
      * rx_data: received data (compressed data already fetched from input stream)
 	 * rx_data_size: size of data fetched from input stream
@@ -27,14 +27,14 @@ typedef struct
 	/*
 	 * Read up to "size" raw (decompressed) bytes.
 	 * Returns number of decompressed bytes or error code.
-	 * Error code is either ZPQ_DECOMPRESS_ERROR either error code returned by the rx function.
+	 * Error code is either ZPQ_DECOMPRESS_ERROR or error code returned by the rx function.
 	 */
 	ssize_t (*read)(ZpqStream *zs, void *buf, size_t size);
 
 	/*
 	 * Write up to "size" raw (decompressed) bytes.
 	 * Returns number of written raw bytes or error code returned by tx function.
-	 * In the last case amount of written raw bytes is stored in *processed.
+	 * In the last case number of bytes written is stored in *processed.
 	 */
 	ssize_t (*write)(ZpqStream *zs, void const *buf, size_t size, size_t *processed);
 
@@ -49,12 +49,12 @@ typedef struct
 	char const* (*error)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal tx decompression buffer.
+	 * Return amount of data in internal tx decompression buffer.
 	 */
 	size_t  (*buffered_tx)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal rx compression buffer.
+	 * Return amount of data in internal rx compression buffer.
 	 */
 	size_t  (*buffered_rx)(ZpqStream *zs);
 } ZpqAlgorithm;
@@ -265,7 +265,7 @@ zstd_name(void)
 
 #define ZLIB_BUFFER_SIZE       8192 /* We have to flush stream after each protocol command
 									 * and command is mostly limited by record length,
-									 * which in turn usually less than page size (except TOAST)
+									 * which in turn is usually less than page size (except TOAST)
 									 */
 
 typedef struct ZlibStream
diff --git a/src/include/common/zpq_stream.h b/src/include/common/zpq_stream.h
index 27aef0aab9..991e2c0165 100644
--- a/src/include/common/zpq_stream.h
+++ b/src/include/common/zpq_stream.h
@@ -1,6 +1,6 @@
 /*
  * zpq_stream.h
- *     Streaiming compression for libpq
+ *     Streaming compression for libpq
  */
 
 #ifndef ZPQ_STREAM_H
diff --git a/src/interfaces/libpq/fe-connect.c b/src/interfaces/libpq/fe-connect.c
index eac6ef66cc..679f8cde9f 100644
--- a/src/interfaces/libpq/fe-connect.c
+++ b/src/interfaces/libpq/fe-connect.c
@@ -3269,7 +3269,7 @@ keep_going:						/* We will come back to here until there is
 						{
 							appendPQExpBuffer(&conn->errorMessage,
 											  libpq_gettext(
-												  "server is not supported requested compression algorithms %s\n"),
+												  "server does not support requested compression algorithms %s\n"),
 											  conn->compression);
 							goto error_return;
 						}
diff --git a/src/interfaces/libpq/fe-protocol3.c b/src/interfaces/libpq/fe-protocol3.c
index 095866bba0..5b879569b4 100644
--- a/src/interfaces/libpq/fe-protocol3.c
+++ b/src/interfaces/libpq/fe-protocol3.c
@@ -2135,15 +2135,15 @@ pqBuildStartupPacket3(PGconn *conn, int *packetlen,
 }
 
 /*
- * Build comma-separated list of compression algorithms suggested by client to the server.
- * It can be either explicitly specified by user in connection string, either
- * include all algorithms supported by clit library.
- * This functions returns true if compression string is successfully parsed and
- * stores comma-separated list of algorithms in *client_compressors.
- * If compression is disabled, then NULL is assigned to  *client_compressors.
- * Also it creates array of compressor descriptors, each element of which corresponds
- * the correspondent algorithm name in *client_compressors list. This array is stored in PGconn
- * and is used during handshake when compassion acknowledgment response is received from the server.
+ * Build comma-separated list of compression algorithms requested by client.
+ * It can be either explicitly specified by user in connection string, or
+ * include all algorithms supported by client library.
+ * This function returns true if the compression string is successfully parsed and
+ * stores a comma-separated list of algorithms in *client_compressors.
+ * If compression is disabled, then NULL is assigned to *client_compressors.
+ * Also it creates an array of compressor descriptors, each element of which corresponds to
+ * the corresponding algorithm name in *client_compressors list. This array is stored in PGconn
+ * and is used during handshake when a compression acknowledgment response is received from the server.
  */
 static bool
 build_compressors_list(PGconn *conn, char** client_compressors, bool build_descriptors)
@@ -2170,7 +2170,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 
 		if (n_supported_algorithms == 0)
 		{
-			*client_compressors = NULL; /* no compressors are avaialable */
+			*client_compressors = NULL; /* no compressors are available */
 			conn->compressors = NULL;
 			return true;
 		}
@@ -2204,7 +2204,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 	}
 	else
 	{
-		/* List of compresison algorithms separated by commas */
+		/* List of compression algorithms separated by commas */
 		char *src, *dst;
 		int n_suggested_algorithms = 0;
 		char* suggested_algorithms = strdup(value);
@@ -2232,7 +2232,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 				if (sscanf(col+1, "%d", &compression_level) != 1 && !build_descriptors)
 				{
 					fprintf(stderr,
-							libpq_gettext("WARNING: invlaid compression level %s in compression option '%s'\n"),
+							libpq_gettext("WARNING: invalid compression level %s in compression option '%s'\n"),
 							col+1, value);
 					return false;
 				}
@@ -2262,7 +2262,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 		{
 			if (!build_descriptors)
 				fprintf(stderr,
-						libpq_gettext("WARNING: none of specified algirthms %s is supported by client\n"),
+						libpq_gettext("WARNING: none of the specified algorithms are supported by client: %s\n"),
 						value);
 			else
 			{
-- 
2.17.0


--yudcn1FV7Hsu/q59--





^ permalink  raw  reply  [nested|flat] 22+ messages in thread

* [PATCH] fixes to docs and comments
@ 2021-01-09 15:49  Justin Pryzby <[email protected]>
  0 siblings, 0 replies; 22+ messages in thread

From: Justin Pryzby @ 2021-01-09 15:49 UTC (permalink / raw)

---
 doc/src/sgml/config.sgml            | 10 +++---
 doc/src/sgml/libpq.sgml             | 23 ++++++++----
 doc/src/sgml/protocol.sgml          | 54 +++++++++++++----------------
 src/backend/libpq/pqcomm.c          |  2 +-
 src/common/zpq_stream.c             | 16 ++++-----
 src/include/common/zpq_stream.h     |  2 +-
 src/interfaces/libpq/fe-connect.c   |  2 +-
 src/interfaces/libpq/fe-protocol3.c | 26 +++++++-------
 8 files changed, 69 insertions(+), 66 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 3b132dcf27..8b5a6525ac 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1004,12 +1004,10 @@ include_dir 'conf.d'
       </term>
       <listitem>
        <para>
-        When this parameter is <literal>on</literal> (default), the <productname>PostgreSQL</productname>
-        server can switch on compression of traffic between server and client if it is requested by client.
-        Client sends to the server list of compression algorithms supported by frontend library,
-        server chooses one which is supported by backend library and sends it in compression acknowledgement message
-        to the client. This option allows to reject compression request even if it is supported by server
-        (due to security, CPU consumption or whatever else reasons...).
+        This parameter enables compression of libpq traffic between client and server.
+        The default is <literal>on</literal>.
+        This option allows rejecting compression requests even if it is supported by server
+        (for example, due to security, or CPU consumption).
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 2934908520..d4da390ca9 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1244,13 +1244,22 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>compression</literal></term>
       <listitem>
       <para>
-        Request compression of libpq traffic. Client sends to the server list of compression algorithms, supported by client library.
-        If server supports one of this algorithms, then it acknowledges use of this algorithm and then all libpq messages send both from client to server and
-        visa versa will be compressed. If server is not supporting any of the suggested algorithms, then it rejects client request to use compression
-        and it is up to the client whether to continue work without compression or report error.
-        Supported compression algorithms are chosen at configure time. Right now two libraries are supported: zlib (default) and zstd (if Postgres was
-        configured with --with-zstd option). In both cases streaming mode is used.
-        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+        Request compression of libpq traffic. The client sends a request with a list of compression algorithms.
+        Compression can be requested by a client by including the "compression" option in its connection string.
+        This can either be a boolean value to enable or disable compression
+        ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto", or an explicit list of comma-separated compression algorithms
+        which can optionally include compression level ("zlib,zstd:5").
+        If compression is enabled but an algorithm is not explicitly specified, the client library sends its full list of
+        supported algorithms and the server chooses a preferred algorithm.
+
+        If the server accepts one of the algorithms, it replies with an acknowledgment and all future libpq messages between client and server
+        will be compressed.
+        If the server rejects the compression request, it is up to the client whether to continue without compression or to report an error.
+        Support for compression algorithms must be enabled when the server is compiled.
+        Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
+        configured with --with-zstd option). In both cases, streaming mode is used.
+        By default, compression is not requested by the client.
+        Please note that using compression together with SSL may expose extra vulnerabilities:
         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;
       </para>
       </listitem>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 9f30aad8bd..a69f9bfc26 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -94,10 +94,10 @@
 
   <para>
     It is possible to compress protocol data to reduce traffic and speed-up client-server interaction.
-    Compression is especially useful for importing/exporting data to/from database using COPY command
-    and for replication (both physical and logical). Also compression can reduce server response time
-    in case of queries returning large amount of data (for example returning JSON, BLOBs, text,...)
-    Right now two libraries are supported: zlib (default) and zstd (if Postgres was
+    Compression is especially useful for importing/exporting data to/from the database using the <literal>COPY</literal> command
+    and for replication (both physical and logical). Compression can also reduce the server's response time
+    for queries returning a large amount of data (for example, JSON, BLOBs, text, ...).
+    Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
     configured with --with-zstd option).
   </para>
 
@@ -275,19 +275,14 @@
       <term>CompressionAck</term>
       <listitem>
        <para>
-         Server acknowledges using compression for client-server communication protocol.
-         Compression can be requested by client by including "compression" option in connection string.
-         It can be just boolean values enabling or disabling compression
-         ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto" or explicit list of compression algorithms
-         separated by comma with optional specification of compression level: "zlib,zstd:5".
-         If compression algorithm is not explicitly specified the most efficient one supported both by
-         client and server is chosen. Client sends to the server list of compression algorithms,
-         supported by client library.
-         If server supports one of this algorithms, then it acknowledges use of this algorithm and
-         all subsequent libpq messages send both from client to server and
-         visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-         index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-         and it is up to the client whether to continue work without compression or report error.
+         The server accepts the client's compression request.
+         Compression is requested when a client connection includes the "compression" option, which includes
+         a list of requested compression algorithms.
+         If the server accepts one of these algorithms, it acknowledges use of compression and
+         all subsequent libpq messages between the client and server will be compressed.
+         The server chooses an algorithm from the list specified by client and responds with the index of the chosen algorithm from the client-supplied list.
+         If the server does not accept any of the requested algorithms, then it replies with an index of -1
+         and it is up to the client whether to continue without compression or to report an error.
        </para>
       </listitem>
      </varlistentry>
@@ -3460,12 +3455,14 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-  Acknowledge use of compression for protocol data. Client sends to the server list of compression algorithms, supported by client library.
-  If server supports one of this algorithms, then it acknowledges use of this algorithm and all subsequent libpq messages send both from client to server and
-  visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-  index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-  and it is up to the client whether to continue work without compression or report error.
-  After receiving this message with algorithm index other than -1, both server and client are switched to compression mode
+  Acknowledge use of compression for protocol data. The client sends to the server a list of requested compression algorithms.
+  If the server supports any of these algorithms, it acknowledges use of this algorithm and all subsequent libpq messages between client and server
+  will be compressed.
+  The server selects the preferred algorithm from the list specified by client and responds with the
+  index of the chosen algorithm in this list.
+  If the server does not support any of the requested algorithms, it replies with -1
+  and it is up to the client whether to continue without compression or to report an error.
+  After receiving this message with algorithm index other than -1, both server and client switch to compressed mode
   and exchange compressed messages.
 </para>
 </listitem>
@@ -3486,7 +3483,7 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-        Index of algorithm in the list of supported algotihms specified by client or -1 if none of them is supported.
+        Index of algorithm in the list of supported algorithms specified by client or -1 if none of them are supported.
 </para>
 </listitem>
 </varlistentry>
@@ -6069,12 +6066,11 @@ StartupMessage (F)
 </term>
 <listitem>
 <para>
-                        Request compression of libpq traffic. Value is list of compression algorithms supported by client with optional
+                        Request compression of libpq traffic. The value is a list of compression algorithms requested by the client with an optional
                         specification of compression level: <literal>"zlib,zstd:5"</literal>.
-                        When connecting to an older backend, which does not support compression, or in case when the backend support compression
-                        but for some reason wants to disable it, the backend will just ignore the _pq_.compression parameter and won’t send
-                        the compressionAck message to the frontend.
-                        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+                        If the server does not accept compression, the backend will ignore the _pq_.compression
+                        parameter and will not send the CompressionAck message to the frontend.
+                        By default, compression is disabled. Please note that using compression together with SSL may expose extra vulnerabilities:
                         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;.
 </para>
 </listitem>
diff --git a/src/backend/libpq/pqcomm.c b/src/backend/libpq/pqcomm.c
index 8be1ce18de..f3293faf01 100644
--- a/src/backend/libpq/pqcomm.c
+++ b/src/backend/libpq/pqcomm.c
@@ -1073,7 +1073,7 @@ pq_recvbuf(bool nowait)
 	/* Can fill buffer from PqRecvLength and upwards */
 	for (;;)
 	{
-		/* If streaming compression is enabled then use correspondent compression read function. */
+		/* If streaming compression is enabled then use corresponding compression read function. */
 		r = PqStream
 			? zpq_read(PqStream, PqRecvBuffer + PqRecvLength,
 					   PQ_RECV_BUFFER_SIZE - PqRecvLength)
diff --git a/src/common/zpq_stream.c b/src/common/zpq_stream.c
index 459566228a..e044e83e7c 100644
--- a/src/common/zpq_stream.c
+++ b/src/common/zpq_stream.c
@@ -9,15 +9,15 @@
 typedef struct
 {
 	/*
-	 * Returns name of compression algorithm.
+	 * Name of compression algorithm.
 	 */
 	char const* (*name)(void);
 
 	/*
-	 * Create compression stream with using rx/tx function for fetching/sending compressed data.
+	 * Create compression stream with rx/tx function for reading/sending compressed data.
 	 * level: compression level
 	 * tx_func: function for writing compressed data in underlying stream
-	 * rx_func: function for receiving compressed data from underlying stream
+	 * rx_func: function for reading compressed data from underlying stream
 	 * arg: context passed to the function
      * rx_data: received data (compressed data already fetched from input stream)
 	 * rx_data_size: size of data fetched from input stream
@@ -27,14 +27,14 @@ typedef struct
 	/*
 	 * Read up to "size" raw (decompressed) bytes.
 	 * Returns number of decompressed bytes or error code.
-	 * Error code is either ZPQ_DECOMPRESS_ERROR either error code returned by the rx function.
+	 * Error code is either ZPQ_DECOMPRESS_ERROR or error code returned by the rx function.
 	 */
 	ssize_t (*read)(ZpqStream *zs, void *buf, size_t size);
 
 	/*
 	 * Write up to "size" raw (decompressed) bytes.
 	 * Returns number of written raw bytes or error code returned by tx function.
-	 * In the last case amount of written raw bytes is stored in *processed.
+	 * In the last case number of bytes written is stored in *processed.
 	 */
 	ssize_t (*write)(ZpqStream *zs, void const *buf, size_t size, size_t *processed);
 
@@ -49,12 +49,12 @@ typedef struct
 	char const* (*error)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal tx decompression buffer.
+	 * Return amount of data in internal tx decompression buffer.
 	 */
 	size_t  (*buffered_tx)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal rx compression buffer.
+	 * Return amount of data in internal rx compression buffer.
 	 */
 	size_t  (*buffered_rx)(ZpqStream *zs);
 } ZpqAlgorithm;
@@ -265,7 +265,7 @@ zstd_name(void)
 
 #define ZLIB_BUFFER_SIZE       8192 /* We have to flush stream after each protocol command
 									 * and command is mostly limited by record length,
-									 * which in turn usually less than page size (except TOAST)
+									 * which in turn is usually less than page size (except TOAST)
 									 */
 
 typedef struct ZlibStream
diff --git a/src/include/common/zpq_stream.h b/src/include/common/zpq_stream.h
index 27aef0aab9..991e2c0165 100644
--- a/src/include/common/zpq_stream.h
+++ b/src/include/common/zpq_stream.h
@@ -1,6 +1,6 @@
 /*
  * zpq_stream.h
- *     Streaiming compression for libpq
+ *     Streaming compression for libpq
  */
 
 #ifndef ZPQ_STREAM_H
diff --git a/src/interfaces/libpq/fe-connect.c b/src/interfaces/libpq/fe-connect.c
index eac6ef66cc..679f8cde9f 100644
--- a/src/interfaces/libpq/fe-connect.c
+++ b/src/interfaces/libpq/fe-connect.c
@@ -3269,7 +3269,7 @@ keep_going:						/* We will come back to here until there is
 						{
 							appendPQExpBuffer(&conn->errorMessage,
 											  libpq_gettext(
-												  "server is not supported requested compression algorithms %s\n"),
+												  "server does not support requested compression algorithms %s\n"),
 											  conn->compression);
 							goto error_return;
 						}
diff --git a/src/interfaces/libpq/fe-protocol3.c b/src/interfaces/libpq/fe-protocol3.c
index 095866bba0..5b879569b4 100644
--- a/src/interfaces/libpq/fe-protocol3.c
+++ b/src/interfaces/libpq/fe-protocol3.c
@@ -2135,15 +2135,15 @@ pqBuildStartupPacket3(PGconn *conn, int *packetlen,
 }
 
 /*
- * Build comma-separated list of compression algorithms suggested by client to the server.
- * It can be either explicitly specified by user in connection string, either
- * include all algorithms supported by clit library.
- * This functions returns true if compression string is successfully parsed and
- * stores comma-separated list of algorithms in *client_compressors.
- * If compression is disabled, then NULL is assigned to  *client_compressors.
- * Also it creates array of compressor descriptors, each element of which corresponds
- * the correspondent algorithm name in *client_compressors list. This array is stored in PGconn
- * and is used during handshake when compassion acknowledgment response is received from the server.
+ * Build comma-separated list of compression algorithms requested by client.
+ * It can be either explicitly specified by user in connection string, or
+ * include all algorithms supported by client library.
+ * This function returns true if the compression string is successfully parsed and
+ * stores a comma-separated list of algorithms in *client_compressors.
+ * If compression is disabled, then NULL is assigned to *client_compressors.
+ * Also it creates an array of compressor descriptors, each element of which corresponds to
+ * the corresponding algorithm name in *client_compressors list. This array is stored in PGconn
+ * and is used during handshake when a compression acknowledgment response is received from the server.
  */
 static bool
 build_compressors_list(PGconn *conn, char** client_compressors, bool build_descriptors)
@@ -2170,7 +2170,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 
 		if (n_supported_algorithms == 0)
 		{
-			*client_compressors = NULL; /* no compressors are avaialable */
+			*client_compressors = NULL; /* no compressors are available */
 			conn->compressors = NULL;
 			return true;
 		}
@@ -2204,7 +2204,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 	}
 	else
 	{
-		/* List of compresison algorithms separated by commas */
+		/* List of compression algorithms separated by commas */
 		char *src, *dst;
 		int n_suggested_algorithms = 0;
 		char* suggested_algorithms = strdup(value);
@@ -2232,7 +2232,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 				if (sscanf(col+1, "%d", &compression_level) != 1 && !build_descriptors)
 				{
 					fprintf(stderr,
-							libpq_gettext("WARNING: invlaid compression level %s in compression option '%s'\n"),
+							libpq_gettext("WARNING: invalid compression level %s in compression option '%s'\n"),
 							col+1, value);
 					return false;
 				}
@@ -2262,7 +2262,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 		{
 			if (!build_descriptors)
 				fprintf(stderr,
-						libpq_gettext("WARNING: none of specified algirthms %s is supported by client\n"),
+						libpq_gettext("WARNING: none of the specified algorithms are supported by client: %s\n"),
 						value);
 			else
 			{
-- 
2.17.0


--yudcn1FV7Hsu/q59--





^ permalink  raw  reply  [nested|flat] 22+ messages in thread

* [PATCH] fixes to docs and comments
@ 2021-01-09 15:49  Justin Pryzby <[email protected]>
  0 siblings, 0 replies; 22+ messages in thread

From: Justin Pryzby @ 2021-01-09 15:49 UTC (permalink / raw)

---
 doc/src/sgml/config.sgml            | 10 +++---
 doc/src/sgml/libpq.sgml             | 23 ++++++++----
 doc/src/sgml/protocol.sgml          | 54 +++++++++++++----------------
 src/backend/libpq/pqcomm.c          |  2 +-
 src/common/zpq_stream.c             | 16 ++++-----
 src/include/common/zpq_stream.h     |  2 +-
 src/interfaces/libpq/fe-connect.c   |  2 +-
 src/interfaces/libpq/fe-protocol3.c | 26 +++++++-------
 8 files changed, 69 insertions(+), 66 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 3b132dcf27..8b5a6525ac 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1004,12 +1004,10 @@ include_dir 'conf.d'
       </term>
       <listitem>
        <para>
-        When this parameter is <literal>on</literal> (default), the <productname>PostgreSQL</productname>
-        server can switch on compression of traffic between server and client if it is requested by client.
-        Client sends to the server list of compression algorithms supported by frontend library,
-        server chooses one which is supported by backend library and sends it in compression acknowledgement message
-        to the client. This option allows to reject compression request even if it is supported by server
-        (due to security, CPU consumption or whatever else reasons...).
+        This parameter enables compression of libpq traffic between client and server.
+        The default is <literal>on</literal>.
+        This option allows rejecting compression requests even if it is supported by server
+        (for example, due to security, or CPU consumption).
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 2934908520..d4da390ca9 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1244,13 +1244,22 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>compression</literal></term>
       <listitem>
       <para>
-        Request compression of libpq traffic. Client sends to the server list of compression algorithms, supported by client library.
-        If server supports one of this algorithms, then it acknowledges use of this algorithm and then all libpq messages send both from client to server and
-        visa versa will be compressed. If server is not supporting any of the suggested algorithms, then it rejects client request to use compression
-        and it is up to the client whether to continue work without compression or report error.
-        Supported compression algorithms are chosen at configure time. Right now two libraries are supported: zlib (default) and zstd (if Postgres was
-        configured with --with-zstd option). In both cases streaming mode is used.
-        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+        Request compression of libpq traffic. The client sends a request with a list of compression algorithms.
+        Compression can be requested by a client by including the "compression" option in its connection string.
+        This can either be a boolean value to enable or disable compression
+        ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto", or an explicit list of comma-separated compression algorithms
+        which can optionally include compression level ("zlib,zstd:5").
+        If compression is enabled but an algorithm is not explicitly specified, the client library sends its full list of
+        supported algorithms and the server chooses a preferred algorithm.
+
+        If the server accepts one of the algorithms, it replies with an acknowledgment and all future libpq messages between client and server
+        will be compressed.
+        If the server rejects the compression request, it is up to the client whether to continue without compression or to report an error.
+        Support for compression algorithms must be enabled when the server is compiled.
+        Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
+        configured with --with-zstd option). In both cases, streaming mode is used.
+        By default, compression is not requested by the client.
+        Please note that using compression together with SSL may expose extra vulnerabilities:
         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;
       </para>
       </listitem>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 9f30aad8bd..a69f9bfc26 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -94,10 +94,10 @@
 
   <para>
     It is possible to compress protocol data to reduce traffic and speed-up client-server interaction.
-    Compression is especially useful for importing/exporting data to/from database using COPY command
-    and for replication (both physical and logical). Also compression can reduce server response time
-    in case of queries returning large amount of data (for example returning JSON, BLOBs, text,...)
-    Right now two libraries are supported: zlib (default) and zstd (if Postgres was
+    Compression is especially useful for importing/exporting data to/from the database using the <literal>COPY</literal> command
+    and for replication (both physical and logical). Compression can also reduce the server's response time
+    for queries returning a large amount of data (for example, JSON, BLOBs, text, ...).
+    Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
     configured with --with-zstd option).
   </para>
 
@@ -275,19 +275,14 @@
       <term>CompressionAck</term>
       <listitem>
        <para>
-         Server acknowledges using compression for client-server communication protocol.
-         Compression can be requested by client by including "compression" option in connection string.
-         It can be just boolean values enabling or disabling compression
-         ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto" or explicit list of compression algorithms
-         separated by comma with optional specification of compression level: "zlib,zstd:5".
-         If compression algorithm is not explicitly specified the most efficient one supported both by
-         client and server is chosen. Client sends to the server list of compression algorithms,
-         supported by client library.
-         If server supports one of this algorithms, then it acknowledges use of this algorithm and
-         all subsequent libpq messages send both from client to server and
-         visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-         index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-         and it is up to the client whether to continue work without compression or report error.
+         The server accepts the client's compression request.
+         Compression is requested when a client connection includes the "compression" option, which includes
+         a list of requested compression algorithms.
+         If the server accepts one of these algorithms, it acknowledges use of compression and
+         all subsequent libpq messages between the client and server will be compressed.
+         The server chooses an algorithm from the list specified by client and responds with the index of the chosen algorithm from the client-supplied list.
+         If the server does not accept any of the requested algorithms, then it replies with an index of -1
+         and it is up to the client whether to continue without compression or to report an error.
        </para>
       </listitem>
      </varlistentry>
@@ -3460,12 +3455,14 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-  Acknowledge use of compression for protocol data. Client sends to the server list of compression algorithms, supported by client library.
-  If server supports one of this algorithms, then it acknowledges use of this algorithm and all subsequent libpq messages send both from client to server and
-  visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-  index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-  and it is up to the client whether to continue work without compression or report error.
-  After receiving this message with algorithm index other than -1, both server and client are switched to compression mode
+  Acknowledge use of compression for protocol data. The client sends to the server a list of requested compression algorithms.
+  If the server supports any of these algorithms, it acknowledges use of this algorithm and all subsequent libpq messages between client and server
+  will be compressed.
+  The server selects the preferred algorithm from the list specified by client and responds with the
+  index of the chosen algorithm in this list.
+  If the server does not support any of the requested algorithms, it replies with -1
+  and it is up to the client whether to continue without compression or to report an error.
+  After receiving this message with algorithm index other than -1, both server and client switch to compressed mode
   and exchange compressed messages.
 </para>
 </listitem>
@@ -3486,7 +3483,7 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-        Index of algorithm in the list of supported algotihms specified by client or -1 if none of them is supported.
+        Index of algorithm in the list of supported algorithms specified by client or -1 if none of them are supported.
 </para>
 </listitem>
 </varlistentry>
@@ -6069,12 +6066,11 @@ StartupMessage (F)
 </term>
 <listitem>
 <para>
-                        Request compression of libpq traffic. Value is list of compression algorithms supported by client with optional
+                        Request compression of libpq traffic. The value is a list of compression algorithms requested by the client with an optional
                         specification of compression level: <literal>"zlib,zstd:5"</literal>.
-                        When connecting to an older backend, which does not support compression, or in case when the backend support compression
-                        but for some reason wants to disable it, the backend will just ignore the _pq_.compression parameter and won’t send
-                        the compressionAck message to the frontend.
-                        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+                        If the server does not accept compression, the backend will ignore the _pq_.compression
+                        parameter and will not send the CompressionAck message to the frontend.
+                        By default, compression is disabled. Please note that using compression together with SSL may expose extra vulnerabilities:
                         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;.
 </para>
 </listitem>
diff --git a/src/backend/libpq/pqcomm.c b/src/backend/libpq/pqcomm.c
index 8be1ce18de..f3293faf01 100644
--- a/src/backend/libpq/pqcomm.c
+++ b/src/backend/libpq/pqcomm.c
@@ -1073,7 +1073,7 @@ pq_recvbuf(bool nowait)
 	/* Can fill buffer from PqRecvLength and upwards */
 	for (;;)
 	{
-		/* If streaming compression is enabled then use correspondent compression read function. */
+		/* If streaming compression is enabled then use corresponding compression read function. */
 		r = PqStream
 			? zpq_read(PqStream, PqRecvBuffer + PqRecvLength,
 					   PQ_RECV_BUFFER_SIZE - PqRecvLength)
diff --git a/src/common/zpq_stream.c b/src/common/zpq_stream.c
index 459566228a..e044e83e7c 100644
--- a/src/common/zpq_stream.c
+++ b/src/common/zpq_stream.c
@@ -9,15 +9,15 @@
 typedef struct
 {
 	/*
-	 * Returns name of compression algorithm.
+	 * Name of compression algorithm.
 	 */
 	char const* (*name)(void);
 
 	/*
-	 * Create compression stream with using rx/tx function for fetching/sending compressed data.
+	 * Create compression stream with rx/tx function for reading/sending compressed data.
 	 * level: compression level
 	 * tx_func: function for writing compressed data in underlying stream
-	 * rx_func: function for receiving compressed data from underlying stream
+	 * rx_func: function for reading compressed data from underlying stream
 	 * arg: context passed to the function
      * rx_data: received data (compressed data already fetched from input stream)
 	 * rx_data_size: size of data fetched from input stream
@@ -27,14 +27,14 @@ typedef struct
 	/*
 	 * Read up to "size" raw (decompressed) bytes.
 	 * Returns number of decompressed bytes or error code.
-	 * Error code is either ZPQ_DECOMPRESS_ERROR either error code returned by the rx function.
+	 * Error code is either ZPQ_DECOMPRESS_ERROR or error code returned by the rx function.
 	 */
 	ssize_t (*read)(ZpqStream *zs, void *buf, size_t size);
 
 	/*
 	 * Write up to "size" raw (decompressed) bytes.
 	 * Returns number of written raw bytes or error code returned by tx function.
-	 * In the last case amount of written raw bytes is stored in *processed.
+	 * In the last case number of bytes written is stored in *processed.
 	 */
 	ssize_t (*write)(ZpqStream *zs, void const *buf, size_t size, size_t *processed);
 
@@ -49,12 +49,12 @@ typedef struct
 	char const* (*error)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal tx decompression buffer.
+	 * Return amount of data in internal tx decompression buffer.
 	 */
 	size_t  (*buffered_tx)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal rx compression buffer.
+	 * Return amount of data in internal rx compression buffer.
 	 */
 	size_t  (*buffered_rx)(ZpqStream *zs);
 } ZpqAlgorithm;
@@ -265,7 +265,7 @@ zstd_name(void)
 
 #define ZLIB_BUFFER_SIZE       8192 /* We have to flush stream after each protocol command
 									 * and command is mostly limited by record length,
-									 * which in turn usually less than page size (except TOAST)
+									 * which in turn is usually less than page size (except TOAST)
 									 */
 
 typedef struct ZlibStream
diff --git a/src/include/common/zpq_stream.h b/src/include/common/zpq_stream.h
index 27aef0aab9..991e2c0165 100644
--- a/src/include/common/zpq_stream.h
+++ b/src/include/common/zpq_stream.h
@@ -1,6 +1,6 @@
 /*
  * zpq_stream.h
- *     Streaiming compression for libpq
+ *     Streaming compression for libpq
  */
 
 #ifndef ZPQ_STREAM_H
diff --git a/src/interfaces/libpq/fe-connect.c b/src/interfaces/libpq/fe-connect.c
index eac6ef66cc..679f8cde9f 100644
--- a/src/interfaces/libpq/fe-connect.c
+++ b/src/interfaces/libpq/fe-connect.c
@@ -3269,7 +3269,7 @@ keep_going:						/* We will come back to here until there is
 						{
 							appendPQExpBuffer(&conn->errorMessage,
 											  libpq_gettext(
-												  "server is not supported requested compression algorithms %s\n"),
+												  "server does not support requested compression algorithms %s\n"),
 											  conn->compression);
 							goto error_return;
 						}
diff --git a/src/interfaces/libpq/fe-protocol3.c b/src/interfaces/libpq/fe-protocol3.c
index 095866bba0..5b879569b4 100644
--- a/src/interfaces/libpq/fe-protocol3.c
+++ b/src/interfaces/libpq/fe-protocol3.c
@@ -2135,15 +2135,15 @@ pqBuildStartupPacket3(PGconn *conn, int *packetlen,
 }
 
 /*
- * Build comma-separated list of compression algorithms suggested by client to the server.
- * It can be either explicitly specified by user in connection string, either
- * include all algorithms supported by clit library.
- * This functions returns true if compression string is successfully parsed and
- * stores comma-separated list of algorithms in *client_compressors.
- * If compression is disabled, then NULL is assigned to  *client_compressors.
- * Also it creates array of compressor descriptors, each element of which corresponds
- * the correspondent algorithm name in *client_compressors list. This array is stored in PGconn
- * and is used during handshake when compassion acknowledgment response is received from the server.
+ * Build comma-separated list of compression algorithms requested by client.
+ * It can be either explicitly specified by user in connection string, or
+ * include all algorithms supported by client library.
+ * This function returns true if the compression string is successfully parsed and
+ * stores a comma-separated list of algorithms in *client_compressors.
+ * If compression is disabled, then NULL is assigned to *client_compressors.
+ * Also it creates an array of compressor descriptors, each element of which corresponds to
+ * the corresponding algorithm name in *client_compressors list. This array is stored in PGconn
+ * and is used during handshake when a compression acknowledgment response is received from the server.
  */
 static bool
 build_compressors_list(PGconn *conn, char** client_compressors, bool build_descriptors)
@@ -2170,7 +2170,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 
 		if (n_supported_algorithms == 0)
 		{
-			*client_compressors = NULL; /* no compressors are avaialable */
+			*client_compressors = NULL; /* no compressors are available */
 			conn->compressors = NULL;
 			return true;
 		}
@@ -2204,7 +2204,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 	}
 	else
 	{
-		/* List of compresison algorithms separated by commas */
+		/* List of compression algorithms separated by commas */
 		char *src, *dst;
 		int n_suggested_algorithms = 0;
 		char* suggested_algorithms = strdup(value);
@@ -2232,7 +2232,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 				if (sscanf(col+1, "%d", &compression_level) != 1 && !build_descriptors)
 				{
 					fprintf(stderr,
-							libpq_gettext("WARNING: invlaid compression level %s in compression option '%s'\n"),
+							libpq_gettext("WARNING: invalid compression level %s in compression option '%s'\n"),
 							col+1, value);
 					return false;
 				}
@@ -2262,7 +2262,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 		{
 			if (!build_descriptors)
 				fprintf(stderr,
-						libpq_gettext("WARNING: none of specified algirthms %s is supported by client\n"),
+						libpq_gettext("WARNING: none of the specified algorithms are supported by client: %s\n"),
 						value);
 			else
 			{
-- 
2.17.0


--yudcn1FV7Hsu/q59--





^ permalink  raw  reply  [nested|flat] 22+ messages in thread

* [PATCH] fixes to docs and comments
@ 2021-01-09 15:49  Justin Pryzby <[email protected]>
  0 siblings, 0 replies; 22+ messages in thread

From: Justin Pryzby @ 2021-01-09 15:49 UTC (permalink / raw)

---
 doc/src/sgml/config.sgml            | 10 +++---
 doc/src/sgml/libpq.sgml             | 23 ++++++++----
 doc/src/sgml/protocol.sgml          | 54 +++++++++++++----------------
 src/backend/libpq/pqcomm.c          |  2 +-
 src/common/zpq_stream.c             | 16 ++++-----
 src/include/common/zpq_stream.h     |  2 +-
 src/interfaces/libpq/fe-connect.c   |  2 +-
 src/interfaces/libpq/fe-protocol3.c | 26 +++++++-------
 8 files changed, 69 insertions(+), 66 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 3b132dcf27..8b5a6525ac 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1004,12 +1004,10 @@ include_dir 'conf.d'
       </term>
       <listitem>
        <para>
-        When this parameter is <literal>on</literal> (default), the <productname>PostgreSQL</productname>
-        server can switch on compression of traffic between server and client if it is requested by client.
-        Client sends to the server list of compression algorithms supported by frontend library,
-        server chooses one which is supported by backend library and sends it in compression acknowledgement message
-        to the client. This option allows to reject compression request even if it is supported by server
-        (due to security, CPU consumption or whatever else reasons...).
+        This parameter enables compression of libpq traffic between client and server.
+        The default is <literal>on</literal>.
+        This option allows rejecting compression requests even if it is supported by server
+        (for example, due to security, or CPU consumption).
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 2934908520..d4da390ca9 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1244,13 +1244,22 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>compression</literal></term>
       <listitem>
       <para>
-        Request compression of libpq traffic. Client sends to the server list of compression algorithms, supported by client library.
-        If server supports one of this algorithms, then it acknowledges use of this algorithm and then all libpq messages send both from client to server and
-        visa versa will be compressed. If server is not supporting any of the suggested algorithms, then it rejects client request to use compression
-        and it is up to the client whether to continue work without compression or report error.
-        Supported compression algorithms are chosen at configure time. Right now two libraries are supported: zlib (default) and zstd (if Postgres was
-        configured with --with-zstd option). In both cases streaming mode is used.
-        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+        Request compression of libpq traffic. The client sends a request with a list of compression algorithms.
+        Compression can be requested by a client by including the "compression" option in its connection string.
+        This can either be a boolean value to enable or disable compression
+        ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto", or an explicit list of comma-separated compression algorithms
+        which can optionally include compression level ("zlib,zstd:5").
+        If compression is enabled but an algorithm is not explicitly specified, the client library sends its full list of
+        supported algorithms and the server chooses a preferred algorithm.
+
+        If the server accepts one of the algorithms, it replies with an acknowledgment and all future libpq messages between client and server
+        will be compressed.
+        If the server rejects the compression request, it is up to the client whether to continue without compression or to report an error.
+        Support for compression algorithms must be enabled when the server is compiled.
+        Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
+        configured with --with-zstd option). In both cases, streaming mode is used.
+        By default, compression is not requested by the client.
+        Please note that using compression together with SSL may expose extra vulnerabilities:
         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;
       </para>
       </listitem>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 9f30aad8bd..a69f9bfc26 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -94,10 +94,10 @@
 
   <para>
     It is possible to compress protocol data to reduce traffic and speed-up client-server interaction.
-    Compression is especially useful for importing/exporting data to/from database using COPY command
-    and for replication (both physical and logical). Also compression can reduce server response time
-    in case of queries returning large amount of data (for example returning JSON, BLOBs, text,...)
-    Right now two libraries are supported: zlib (default) and zstd (if Postgres was
+    Compression is especially useful for importing/exporting data to/from the database using the <literal>COPY</literal> command
+    and for replication (both physical and logical). Compression can also reduce the server's response time
+    for queries returning a large amount of data (for example, JSON, BLOBs, text, ...).
+    Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
     configured with --with-zstd option).
   </para>
 
@@ -275,19 +275,14 @@
       <term>CompressionAck</term>
       <listitem>
        <para>
-         Server acknowledges using compression for client-server communication protocol.
-         Compression can be requested by client by including "compression" option in connection string.
-         It can be just boolean values enabling or disabling compression
-         ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto" or explicit list of compression algorithms
-         separated by comma with optional specification of compression level: "zlib,zstd:5".
-         If compression algorithm is not explicitly specified the most efficient one supported both by
-         client and server is chosen. Client sends to the server list of compression algorithms,
-         supported by client library.
-         If server supports one of this algorithms, then it acknowledges use of this algorithm and
-         all subsequent libpq messages send both from client to server and
-         visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-         index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-         and it is up to the client whether to continue work without compression or report error.
+         The server accepts the client's compression request.
+         Compression is requested when a client connection includes the "compression" option, which includes
+         a list of requested compression algorithms.
+         If the server accepts one of these algorithms, it acknowledges use of compression and
+         all subsequent libpq messages between the client and server will be compressed.
+         The server chooses an algorithm from the list specified by client and responds with the index of the chosen algorithm from the client-supplied list.
+         If the server does not accept any of the requested algorithms, then it replies with an index of -1
+         and it is up to the client whether to continue without compression or to report an error.
        </para>
       </listitem>
      </varlistentry>
@@ -3460,12 +3455,14 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-  Acknowledge use of compression for protocol data. Client sends to the server list of compression algorithms, supported by client library.
-  If server supports one of this algorithms, then it acknowledges use of this algorithm and all subsequent libpq messages send both from client to server and
-  visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-  index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-  and it is up to the client whether to continue work without compression or report error.
-  After receiving this message with algorithm index other than -1, both server and client are switched to compression mode
+  Acknowledge use of compression for protocol data. The client sends to the server a list of requested compression algorithms.
+  If the server supports any of these algorithms, it acknowledges use of this algorithm and all subsequent libpq messages between client and server
+  will be compressed.
+  The server selects the preferred algorithm from the list specified by client and responds with the
+  index of the chosen algorithm in this list.
+  If the server does not support any of the requested algorithms, it replies with -1
+  and it is up to the client whether to continue without compression or to report an error.
+  After receiving this message with algorithm index other than -1, both server and client switch to compressed mode
   and exchange compressed messages.
 </para>
 </listitem>
@@ -3486,7 +3483,7 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-        Index of algorithm in the list of supported algotihms specified by client or -1 if none of them is supported.
+        Index of algorithm in the list of supported algorithms specified by client or -1 if none of them are supported.
 </para>
 </listitem>
 </varlistentry>
@@ -6069,12 +6066,11 @@ StartupMessage (F)
 </term>
 <listitem>
 <para>
-                        Request compression of libpq traffic. Value is list of compression algorithms supported by client with optional
+                        Request compression of libpq traffic. The value is a list of compression algorithms requested by the client with an optional
                         specification of compression level: <literal>"zlib,zstd:5"</literal>.
-                        When connecting to an older backend, which does not support compression, or in case when the backend support compression
-                        but for some reason wants to disable it, the backend will just ignore the _pq_.compression parameter and won’t send
-                        the compressionAck message to the frontend.
-                        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+                        If the server does not accept compression, the backend will ignore the _pq_.compression
+                        parameter and will not send the CompressionAck message to the frontend.
+                        By default, compression is disabled. Please note that using compression together with SSL may expose extra vulnerabilities:
                         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;.
 </para>
 </listitem>
diff --git a/src/backend/libpq/pqcomm.c b/src/backend/libpq/pqcomm.c
index 8be1ce18de..f3293faf01 100644
--- a/src/backend/libpq/pqcomm.c
+++ b/src/backend/libpq/pqcomm.c
@@ -1073,7 +1073,7 @@ pq_recvbuf(bool nowait)
 	/* Can fill buffer from PqRecvLength and upwards */
 	for (;;)
 	{
-		/* If streaming compression is enabled then use correspondent compression read function. */
+		/* If streaming compression is enabled then use corresponding compression read function. */
 		r = PqStream
 			? zpq_read(PqStream, PqRecvBuffer + PqRecvLength,
 					   PQ_RECV_BUFFER_SIZE - PqRecvLength)
diff --git a/src/common/zpq_stream.c b/src/common/zpq_stream.c
index 459566228a..e044e83e7c 100644
--- a/src/common/zpq_stream.c
+++ b/src/common/zpq_stream.c
@@ -9,15 +9,15 @@
 typedef struct
 {
 	/*
-	 * Returns name of compression algorithm.
+	 * Name of compression algorithm.
 	 */
 	char const* (*name)(void);
 
 	/*
-	 * Create compression stream with using rx/tx function for fetching/sending compressed data.
+	 * Create compression stream with rx/tx function for reading/sending compressed data.
 	 * level: compression level
 	 * tx_func: function for writing compressed data in underlying stream
-	 * rx_func: function for receiving compressed data from underlying stream
+	 * rx_func: function for reading compressed data from underlying stream
 	 * arg: context passed to the function
      * rx_data: received data (compressed data already fetched from input stream)
 	 * rx_data_size: size of data fetched from input stream
@@ -27,14 +27,14 @@ typedef struct
 	/*
 	 * Read up to "size" raw (decompressed) bytes.
 	 * Returns number of decompressed bytes or error code.
-	 * Error code is either ZPQ_DECOMPRESS_ERROR either error code returned by the rx function.
+	 * Error code is either ZPQ_DECOMPRESS_ERROR or error code returned by the rx function.
 	 */
 	ssize_t (*read)(ZpqStream *zs, void *buf, size_t size);
 
 	/*
 	 * Write up to "size" raw (decompressed) bytes.
 	 * Returns number of written raw bytes or error code returned by tx function.
-	 * In the last case amount of written raw bytes is stored in *processed.
+	 * In the last case number of bytes written is stored in *processed.
 	 */
 	ssize_t (*write)(ZpqStream *zs, void const *buf, size_t size, size_t *processed);
 
@@ -49,12 +49,12 @@ typedef struct
 	char const* (*error)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal tx decompression buffer.
+	 * Return amount of data in internal tx decompression buffer.
 	 */
 	size_t  (*buffered_tx)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal rx compression buffer.
+	 * Return amount of data in internal rx compression buffer.
 	 */
 	size_t  (*buffered_rx)(ZpqStream *zs);
 } ZpqAlgorithm;
@@ -265,7 +265,7 @@ zstd_name(void)
 
 #define ZLIB_BUFFER_SIZE       8192 /* We have to flush stream after each protocol command
 									 * and command is mostly limited by record length,
-									 * which in turn usually less than page size (except TOAST)
+									 * which in turn is usually less than page size (except TOAST)
 									 */
 
 typedef struct ZlibStream
diff --git a/src/include/common/zpq_stream.h b/src/include/common/zpq_stream.h
index 27aef0aab9..991e2c0165 100644
--- a/src/include/common/zpq_stream.h
+++ b/src/include/common/zpq_stream.h
@@ -1,6 +1,6 @@
 /*
  * zpq_stream.h
- *     Streaiming compression for libpq
+ *     Streaming compression for libpq
  */
 
 #ifndef ZPQ_STREAM_H
diff --git a/src/interfaces/libpq/fe-connect.c b/src/interfaces/libpq/fe-connect.c
index eac6ef66cc..679f8cde9f 100644
--- a/src/interfaces/libpq/fe-connect.c
+++ b/src/interfaces/libpq/fe-connect.c
@@ -3269,7 +3269,7 @@ keep_going:						/* We will come back to here until there is
 						{
 							appendPQExpBuffer(&conn->errorMessage,
 											  libpq_gettext(
-												  "server is not supported requested compression algorithms %s\n"),
+												  "server does not support requested compression algorithms %s\n"),
 											  conn->compression);
 							goto error_return;
 						}
diff --git a/src/interfaces/libpq/fe-protocol3.c b/src/interfaces/libpq/fe-protocol3.c
index 095866bba0..5b879569b4 100644
--- a/src/interfaces/libpq/fe-protocol3.c
+++ b/src/interfaces/libpq/fe-protocol3.c
@@ -2135,15 +2135,15 @@ pqBuildStartupPacket3(PGconn *conn, int *packetlen,
 }
 
 /*
- * Build comma-separated list of compression algorithms suggested by client to the server.
- * It can be either explicitly specified by user in connection string, either
- * include all algorithms supported by clit library.
- * This functions returns true if compression string is successfully parsed and
- * stores comma-separated list of algorithms in *client_compressors.
- * If compression is disabled, then NULL is assigned to  *client_compressors.
- * Also it creates array of compressor descriptors, each element of which corresponds
- * the correspondent algorithm name in *client_compressors list. This array is stored in PGconn
- * and is used during handshake when compassion acknowledgment response is received from the server.
+ * Build comma-separated list of compression algorithms requested by client.
+ * It can be either explicitly specified by user in connection string, or
+ * include all algorithms supported by client library.
+ * This function returns true if the compression string is successfully parsed and
+ * stores a comma-separated list of algorithms in *client_compressors.
+ * If compression is disabled, then NULL is assigned to *client_compressors.
+ * Also it creates an array of compressor descriptors, each element of which corresponds to
+ * the corresponding algorithm name in *client_compressors list. This array is stored in PGconn
+ * and is used during handshake when a compression acknowledgment response is received from the server.
  */
 static bool
 build_compressors_list(PGconn *conn, char** client_compressors, bool build_descriptors)
@@ -2170,7 +2170,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 
 		if (n_supported_algorithms == 0)
 		{
-			*client_compressors = NULL; /* no compressors are avaialable */
+			*client_compressors = NULL; /* no compressors are available */
 			conn->compressors = NULL;
 			return true;
 		}
@@ -2204,7 +2204,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 	}
 	else
 	{
-		/* List of compresison algorithms separated by commas */
+		/* List of compression algorithms separated by commas */
 		char *src, *dst;
 		int n_suggested_algorithms = 0;
 		char* suggested_algorithms = strdup(value);
@@ -2232,7 +2232,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 				if (sscanf(col+1, "%d", &compression_level) != 1 && !build_descriptors)
 				{
 					fprintf(stderr,
-							libpq_gettext("WARNING: invlaid compression level %s in compression option '%s'\n"),
+							libpq_gettext("WARNING: invalid compression level %s in compression option '%s'\n"),
 							col+1, value);
 					return false;
 				}
@@ -2262,7 +2262,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 		{
 			if (!build_descriptors)
 				fprintf(stderr,
-						libpq_gettext("WARNING: none of specified algirthms %s is supported by client\n"),
+						libpq_gettext("WARNING: none of the specified algorithms are supported by client: %s\n"),
 						value);
 			else
 			{
-- 
2.17.0


--yudcn1FV7Hsu/q59--





^ permalink  raw  reply  [nested|flat] 22+ messages in thread

* [PATCH] fixes to docs and comments
@ 2021-01-09 15:49  Justin Pryzby <[email protected]>
  0 siblings, 0 replies; 22+ messages in thread

From: Justin Pryzby @ 2021-01-09 15:49 UTC (permalink / raw)

---
 doc/src/sgml/config.sgml            | 10 +++---
 doc/src/sgml/libpq.sgml             | 23 ++++++++----
 doc/src/sgml/protocol.sgml          | 54 +++++++++++++----------------
 src/backend/libpq/pqcomm.c          |  2 +-
 src/common/zpq_stream.c             | 16 ++++-----
 src/include/common/zpq_stream.h     |  2 +-
 src/interfaces/libpq/fe-connect.c   |  2 +-
 src/interfaces/libpq/fe-protocol3.c | 26 +++++++-------
 8 files changed, 69 insertions(+), 66 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 3b132dcf27..8b5a6525ac 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1004,12 +1004,10 @@ include_dir 'conf.d'
       </term>
       <listitem>
        <para>
-        When this parameter is <literal>on</literal> (default), the <productname>PostgreSQL</productname>
-        server can switch on compression of traffic between server and client if it is requested by client.
-        Client sends to the server list of compression algorithms supported by frontend library,
-        server chooses one which is supported by backend library and sends it in compression acknowledgement message
-        to the client. This option allows to reject compression request even if it is supported by server
-        (due to security, CPU consumption or whatever else reasons...).
+        This parameter enables compression of libpq traffic between client and server.
+        The default is <literal>on</literal>.
+        This option allows rejecting compression requests even if it is supported by server
+        (for example, due to security, or CPU consumption).
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 2934908520..d4da390ca9 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1244,13 +1244,22 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>compression</literal></term>
       <listitem>
       <para>
-        Request compression of libpq traffic. Client sends to the server list of compression algorithms, supported by client library.
-        If server supports one of this algorithms, then it acknowledges use of this algorithm and then all libpq messages send both from client to server and
-        visa versa will be compressed. If server is not supporting any of the suggested algorithms, then it rejects client request to use compression
-        and it is up to the client whether to continue work without compression or report error.
-        Supported compression algorithms are chosen at configure time. Right now two libraries are supported: zlib (default) and zstd (if Postgres was
-        configured with --with-zstd option). In both cases streaming mode is used.
-        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+        Request compression of libpq traffic. The client sends a request with a list of compression algorithms.
+        Compression can be requested by a client by including the "compression" option in its connection string.
+        This can either be a boolean value to enable or disable compression
+        ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto", or an explicit list of comma-separated compression algorithms
+        which can optionally include compression level ("zlib,zstd:5").
+        If compression is enabled but an algorithm is not explicitly specified, the client library sends its full list of
+        supported algorithms and the server chooses a preferred algorithm.
+
+        If the server accepts one of the algorithms, it replies with an acknowledgment and all future libpq messages between client and server
+        will be compressed.
+        If the server rejects the compression request, it is up to the client whether to continue without compression or to report an error.
+        Support for compression algorithms must be enabled when the server is compiled.
+        Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
+        configured with --with-zstd option). In both cases, streaming mode is used.
+        By default, compression is not requested by the client.
+        Please note that using compression together with SSL may expose extra vulnerabilities:
         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;
       </para>
       </listitem>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 9f30aad8bd..a69f9bfc26 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -94,10 +94,10 @@
 
   <para>
     It is possible to compress protocol data to reduce traffic and speed-up client-server interaction.
-    Compression is especially useful for importing/exporting data to/from database using COPY command
-    and for replication (both physical and logical). Also compression can reduce server response time
-    in case of queries returning large amount of data (for example returning JSON, BLOBs, text,...)
-    Right now two libraries are supported: zlib (default) and zstd (if Postgres was
+    Compression is especially useful for importing/exporting data to/from the database using the <literal>COPY</literal> command
+    and for replication (both physical and logical). Compression can also reduce the server's response time
+    for queries returning a large amount of data (for example, JSON, BLOBs, text, ...).
+    Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
     configured with --with-zstd option).
   </para>
 
@@ -275,19 +275,14 @@
       <term>CompressionAck</term>
       <listitem>
        <para>
-         Server acknowledges using compression for client-server communication protocol.
-         Compression can be requested by client by including "compression" option in connection string.
-         It can be just boolean values enabling or disabling compression
-         ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto" or explicit list of compression algorithms
-         separated by comma with optional specification of compression level: "zlib,zstd:5".
-         If compression algorithm is not explicitly specified the most efficient one supported both by
-         client and server is chosen. Client sends to the server list of compression algorithms,
-         supported by client library.
-         If server supports one of this algorithms, then it acknowledges use of this algorithm and
-         all subsequent libpq messages send both from client to server and
-         visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-         index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-         and it is up to the client whether to continue work without compression or report error.
+         The server accepts the client's compression request.
+         Compression is requested when a client connection includes the "compression" option, which includes
+         a list of requested compression algorithms.
+         If the server accepts one of these algorithms, it acknowledges use of compression and
+         all subsequent libpq messages between the client and server will be compressed.
+         The server chooses an algorithm from the list specified by client and responds with the index of the chosen algorithm from the client-supplied list.
+         If the server does not accept any of the requested algorithms, then it replies with an index of -1
+         and it is up to the client whether to continue without compression or to report an error.
        </para>
       </listitem>
      </varlistentry>
@@ -3460,12 +3455,14 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-  Acknowledge use of compression for protocol data. Client sends to the server list of compression algorithms, supported by client library.
-  If server supports one of this algorithms, then it acknowledges use of this algorithm and all subsequent libpq messages send both from client to server and
-  visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-  index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-  and it is up to the client whether to continue work without compression or report error.
-  After receiving this message with algorithm index other than -1, both server and client are switched to compression mode
+  Acknowledge use of compression for protocol data. The client sends to the server a list of requested compression algorithms.
+  If the server supports any of these algorithms, it acknowledges use of this algorithm and all subsequent libpq messages between client and server
+  will be compressed.
+  The server selects the preferred algorithm from the list specified by client and responds with the
+  index of the chosen algorithm in this list.
+  If the server does not support any of the requested algorithms, it replies with -1
+  and it is up to the client whether to continue without compression or to report an error.
+  After receiving this message with algorithm index other than -1, both server and client switch to compressed mode
   and exchange compressed messages.
 </para>
 </listitem>
@@ -3486,7 +3483,7 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-        Index of algorithm in the list of supported algotihms specified by client or -1 if none of them is supported.
+        Index of algorithm in the list of supported algorithms specified by client or -1 if none of them are supported.
 </para>
 </listitem>
 </varlistentry>
@@ -6069,12 +6066,11 @@ StartupMessage (F)
 </term>
 <listitem>
 <para>
-                        Request compression of libpq traffic. Value is list of compression algorithms supported by client with optional
+                        Request compression of libpq traffic. The value is a list of compression algorithms requested by the client with an optional
                         specification of compression level: <literal>"zlib,zstd:5"</literal>.
-                        When connecting to an older backend, which does not support compression, or in case when the backend support compression
-                        but for some reason wants to disable it, the backend will just ignore the _pq_.compression parameter and won’t send
-                        the compressionAck message to the frontend.
-                        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+                        If the server does not accept compression, the backend will ignore the _pq_.compression
+                        parameter and will not send the CompressionAck message to the frontend.
+                        By default, compression is disabled. Please note that using compression together with SSL may expose extra vulnerabilities:
                         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;.
 </para>
 </listitem>
diff --git a/src/backend/libpq/pqcomm.c b/src/backend/libpq/pqcomm.c
index 8be1ce18de..f3293faf01 100644
--- a/src/backend/libpq/pqcomm.c
+++ b/src/backend/libpq/pqcomm.c
@@ -1073,7 +1073,7 @@ pq_recvbuf(bool nowait)
 	/* Can fill buffer from PqRecvLength and upwards */
 	for (;;)
 	{
-		/* If streaming compression is enabled then use correspondent compression read function. */
+		/* If streaming compression is enabled then use corresponding compression read function. */
 		r = PqStream
 			? zpq_read(PqStream, PqRecvBuffer + PqRecvLength,
 					   PQ_RECV_BUFFER_SIZE - PqRecvLength)
diff --git a/src/common/zpq_stream.c b/src/common/zpq_stream.c
index 459566228a..e044e83e7c 100644
--- a/src/common/zpq_stream.c
+++ b/src/common/zpq_stream.c
@@ -9,15 +9,15 @@
 typedef struct
 {
 	/*
-	 * Returns name of compression algorithm.
+	 * Name of compression algorithm.
 	 */
 	char const* (*name)(void);
 
 	/*
-	 * Create compression stream with using rx/tx function for fetching/sending compressed data.
+	 * Create compression stream with rx/tx function for reading/sending compressed data.
 	 * level: compression level
 	 * tx_func: function for writing compressed data in underlying stream
-	 * rx_func: function for receiving compressed data from underlying stream
+	 * rx_func: function for reading compressed data from underlying stream
 	 * arg: context passed to the function
      * rx_data: received data (compressed data already fetched from input stream)
 	 * rx_data_size: size of data fetched from input stream
@@ -27,14 +27,14 @@ typedef struct
 	/*
 	 * Read up to "size" raw (decompressed) bytes.
 	 * Returns number of decompressed bytes or error code.
-	 * Error code is either ZPQ_DECOMPRESS_ERROR either error code returned by the rx function.
+	 * Error code is either ZPQ_DECOMPRESS_ERROR or error code returned by the rx function.
 	 */
 	ssize_t (*read)(ZpqStream *zs, void *buf, size_t size);
 
 	/*
 	 * Write up to "size" raw (decompressed) bytes.
 	 * Returns number of written raw bytes or error code returned by tx function.
-	 * In the last case amount of written raw bytes is stored in *processed.
+	 * In the last case number of bytes written is stored in *processed.
 	 */
 	ssize_t (*write)(ZpqStream *zs, void const *buf, size_t size, size_t *processed);
 
@@ -49,12 +49,12 @@ typedef struct
 	char const* (*error)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal tx decompression buffer.
+	 * Return amount of data in internal tx decompression buffer.
 	 */
 	size_t  (*buffered_tx)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal rx compression buffer.
+	 * Return amount of data in internal rx compression buffer.
 	 */
 	size_t  (*buffered_rx)(ZpqStream *zs);
 } ZpqAlgorithm;
@@ -265,7 +265,7 @@ zstd_name(void)
 
 #define ZLIB_BUFFER_SIZE       8192 /* We have to flush stream after each protocol command
 									 * and command is mostly limited by record length,
-									 * which in turn usually less than page size (except TOAST)
+									 * which in turn is usually less than page size (except TOAST)
 									 */
 
 typedef struct ZlibStream
diff --git a/src/include/common/zpq_stream.h b/src/include/common/zpq_stream.h
index 27aef0aab9..991e2c0165 100644
--- a/src/include/common/zpq_stream.h
+++ b/src/include/common/zpq_stream.h
@@ -1,6 +1,6 @@
 /*
  * zpq_stream.h
- *     Streaiming compression for libpq
+ *     Streaming compression for libpq
  */
 
 #ifndef ZPQ_STREAM_H
diff --git a/src/interfaces/libpq/fe-connect.c b/src/interfaces/libpq/fe-connect.c
index eac6ef66cc..679f8cde9f 100644
--- a/src/interfaces/libpq/fe-connect.c
+++ b/src/interfaces/libpq/fe-connect.c
@@ -3269,7 +3269,7 @@ keep_going:						/* We will come back to here until there is
 						{
 							appendPQExpBuffer(&conn->errorMessage,
 											  libpq_gettext(
-												  "server is not supported requested compression algorithms %s\n"),
+												  "server does not support requested compression algorithms %s\n"),
 											  conn->compression);
 							goto error_return;
 						}
diff --git a/src/interfaces/libpq/fe-protocol3.c b/src/interfaces/libpq/fe-protocol3.c
index 095866bba0..5b879569b4 100644
--- a/src/interfaces/libpq/fe-protocol3.c
+++ b/src/interfaces/libpq/fe-protocol3.c
@@ -2135,15 +2135,15 @@ pqBuildStartupPacket3(PGconn *conn, int *packetlen,
 }
 
 /*
- * Build comma-separated list of compression algorithms suggested by client to the server.
- * It can be either explicitly specified by user in connection string, either
- * include all algorithms supported by clit library.
- * This functions returns true if compression string is successfully parsed and
- * stores comma-separated list of algorithms in *client_compressors.
- * If compression is disabled, then NULL is assigned to  *client_compressors.
- * Also it creates array of compressor descriptors, each element of which corresponds
- * the correspondent algorithm name in *client_compressors list. This array is stored in PGconn
- * and is used during handshake when compassion acknowledgment response is received from the server.
+ * Build comma-separated list of compression algorithms requested by client.
+ * It can be either explicitly specified by user in connection string, or
+ * include all algorithms supported by client library.
+ * This function returns true if the compression string is successfully parsed and
+ * stores a comma-separated list of algorithms in *client_compressors.
+ * If compression is disabled, then NULL is assigned to *client_compressors.
+ * Also it creates an array of compressor descriptors, each element of which corresponds to
+ * the corresponding algorithm name in *client_compressors list. This array is stored in PGconn
+ * and is used during handshake when a compression acknowledgment response is received from the server.
  */
 static bool
 build_compressors_list(PGconn *conn, char** client_compressors, bool build_descriptors)
@@ -2170,7 +2170,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 
 		if (n_supported_algorithms == 0)
 		{
-			*client_compressors = NULL; /* no compressors are avaialable */
+			*client_compressors = NULL; /* no compressors are available */
 			conn->compressors = NULL;
 			return true;
 		}
@@ -2204,7 +2204,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 	}
 	else
 	{
-		/* List of compresison algorithms separated by commas */
+		/* List of compression algorithms separated by commas */
 		char *src, *dst;
 		int n_suggested_algorithms = 0;
 		char* suggested_algorithms = strdup(value);
@@ -2232,7 +2232,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 				if (sscanf(col+1, "%d", &compression_level) != 1 && !build_descriptors)
 				{
 					fprintf(stderr,
-							libpq_gettext("WARNING: invlaid compression level %s in compression option '%s'\n"),
+							libpq_gettext("WARNING: invalid compression level %s in compression option '%s'\n"),
 							col+1, value);
 					return false;
 				}
@@ -2262,7 +2262,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 		{
 			if (!build_descriptors)
 				fprintf(stderr,
-						libpq_gettext("WARNING: none of specified algirthms %s is supported by client\n"),
+						libpq_gettext("WARNING: none of the specified algorithms are supported by client: %s\n"),
 						value);
 			else
 			{
-- 
2.17.0


--yudcn1FV7Hsu/q59--





^ permalink  raw  reply  [nested|flat] 22+ messages in thread

* [PATCH] fixes to docs and comments
@ 2021-01-09 15:49  Justin Pryzby <[email protected]>
  0 siblings, 0 replies; 22+ messages in thread

From: Justin Pryzby @ 2021-01-09 15:49 UTC (permalink / raw)

---
 doc/src/sgml/config.sgml            | 10 +++---
 doc/src/sgml/libpq.sgml             | 23 ++++++++----
 doc/src/sgml/protocol.sgml          | 54 +++++++++++++----------------
 src/backend/libpq/pqcomm.c          |  2 +-
 src/common/zpq_stream.c             | 16 ++++-----
 src/include/common/zpq_stream.h     |  2 +-
 src/interfaces/libpq/fe-connect.c   |  2 +-
 src/interfaces/libpq/fe-protocol3.c | 26 +++++++-------
 8 files changed, 69 insertions(+), 66 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 3b132dcf27..8b5a6525ac 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1004,12 +1004,10 @@ include_dir 'conf.d'
       </term>
       <listitem>
        <para>
-        When this parameter is <literal>on</literal> (default), the <productname>PostgreSQL</productname>
-        server can switch on compression of traffic between server and client if it is requested by client.
-        Client sends to the server list of compression algorithms supported by frontend library,
-        server chooses one which is supported by backend library and sends it in compression acknowledgement message
-        to the client. This option allows to reject compression request even if it is supported by server
-        (due to security, CPU consumption or whatever else reasons...).
+        This parameter enables compression of libpq traffic between client and server.
+        The default is <literal>on</literal>.
+        This option allows rejecting compression requests even if it is supported by server
+        (for example, due to security, or CPU consumption).
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 2934908520..d4da390ca9 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1244,13 +1244,22 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>compression</literal></term>
       <listitem>
       <para>
-        Request compression of libpq traffic. Client sends to the server list of compression algorithms, supported by client library.
-        If server supports one of this algorithms, then it acknowledges use of this algorithm and then all libpq messages send both from client to server and
-        visa versa will be compressed. If server is not supporting any of the suggested algorithms, then it rejects client request to use compression
-        and it is up to the client whether to continue work without compression or report error.
-        Supported compression algorithms are chosen at configure time. Right now two libraries are supported: zlib (default) and zstd (if Postgres was
-        configured with --with-zstd option). In both cases streaming mode is used.
-        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+        Request compression of libpq traffic. The client sends a request with a list of compression algorithms.
+        Compression can be requested by a client by including the "compression" option in its connection string.
+        This can either be a boolean value to enable or disable compression
+        ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto", or an explicit list of comma-separated compression algorithms
+        which can optionally include compression level ("zlib,zstd:5").
+        If compression is enabled but an algorithm is not explicitly specified, the client library sends its full list of
+        supported algorithms and the server chooses a preferred algorithm.
+
+        If the server accepts one of the algorithms, it replies with an acknowledgment and all future libpq messages between client and server
+        will be compressed.
+        If the server rejects the compression request, it is up to the client whether to continue without compression or to report an error.
+        Support for compression algorithms must be enabled when the server is compiled.
+        Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
+        configured with --with-zstd option). In both cases, streaming mode is used.
+        By default, compression is not requested by the client.
+        Please note that using compression together with SSL may expose extra vulnerabilities:
         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;
       </para>
       </listitem>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 9f30aad8bd..a69f9bfc26 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -94,10 +94,10 @@
 
   <para>
     It is possible to compress protocol data to reduce traffic and speed-up client-server interaction.
-    Compression is especially useful for importing/exporting data to/from database using COPY command
-    and for replication (both physical and logical). Also compression can reduce server response time
-    in case of queries returning large amount of data (for example returning JSON, BLOBs, text,...)
-    Right now two libraries are supported: zlib (default) and zstd (if Postgres was
+    Compression is especially useful for importing/exporting data to/from the database using the <literal>COPY</literal> command
+    and for replication (both physical and logical). Compression can also reduce the server's response time
+    for queries returning a large amount of data (for example, JSON, BLOBs, text, ...).
+    Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
     configured with --with-zstd option).
   </para>
 
@@ -275,19 +275,14 @@
       <term>CompressionAck</term>
       <listitem>
        <para>
-         Server acknowledges using compression for client-server communication protocol.
-         Compression can be requested by client by including "compression" option in connection string.
-         It can be just boolean values enabling or disabling compression
-         ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto" or explicit list of compression algorithms
-         separated by comma with optional specification of compression level: "zlib,zstd:5".
-         If compression algorithm is not explicitly specified the most efficient one supported both by
-         client and server is chosen. Client sends to the server list of compression algorithms,
-         supported by client library.
-         If server supports one of this algorithms, then it acknowledges use of this algorithm and
-         all subsequent libpq messages send both from client to server and
-         visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-         index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-         and it is up to the client whether to continue work without compression or report error.
+         The server accepts the client's compression request.
+         Compression is requested when a client connection includes the "compression" option, which includes
+         a list of requested compression algorithms.
+         If the server accepts one of these algorithms, it acknowledges use of compression and
+         all subsequent libpq messages between the client and server will be compressed.
+         The server chooses an algorithm from the list specified by client and responds with the index of the chosen algorithm from the client-supplied list.
+         If the server does not accept any of the requested algorithms, then it replies with an index of -1
+         and it is up to the client whether to continue without compression or to report an error.
        </para>
       </listitem>
      </varlistentry>
@@ -3460,12 +3455,14 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-  Acknowledge use of compression for protocol data. Client sends to the server list of compression algorithms, supported by client library.
-  If server supports one of this algorithms, then it acknowledges use of this algorithm and all subsequent libpq messages send both from client to server and
-  visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-  index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-  and it is up to the client whether to continue work without compression or report error.
-  After receiving this message with algorithm index other than -1, both server and client are switched to compression mode
+  Acknowledge use of compression for protocol data. The client sends to the server a list of requested compression algorithms.
+  If the server supports any of these algorithms, it acknowledges use of this algorithm and all subsequent libpq messages between client and server
+  will be compressed.
+  The server selects the preferred algorithm from the list specified by client and responds with the
+  index of the chosen algorithm in this list.
+  If the server does not support any of the requested algorithms, it replies with -1
+  and it is up to the client whether to continue without compression or to report an error.
+  After receiving this message with algorithm index other than -1, both server and client switch to compressed mode
   and exchange compressed messages.
 </para>
 </listitem>
@@ -3486,7 +3483,7 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-        Index of algorithm in the list of supported algotihms specified by client or -1 if none of them is supported.
+        Index of algorithm in the list of supported algorithms specified by client or -1 if none of them are supported.
 </para>
 </listitem>
 </varlistentry>
@@ -6069,12 +6066,11 @@ StartupMessage (F)
 </term>
 <listitem>
 <para>
-                        Request compression of libpq traffic. Value is list of compression algorithms supported by client with optional
+                        Request compression of libpq traffic. The value is a list of compression algorithms requested by the client with an optional
                         specification of compression level: <literal>"zlib,zstd:5"</literal>.
-                        When connecting to an older backend, which does not support compression, or in case when the backend support compression
-                        but for some reason wants to disable it, the backend will just ignore the _pq_.compression parameter and won’t send
-                        the compressionAck message to the frontend.
-                        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+                        If the server does not accept compression, the backend will ignore the _pq_.compression
+                        parameter and will not send the CompressionAck message to the frontend.
+                        By default, compression is disabled. Please note that using compression together with SSL may expose extra vulnerabilities:
                         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;.
 </para>
 </listitem>
diff --git a/src/backend/libpq/pqcomm.c b/src/backend/libpq/pqcomm.c
index 8be1ce18de..f3293faf01 100644
--- a/src/backend/libpq/pqcomm.c
+++ b/src/backend/libpq/pqcomm.c
@@ -1073,7 +1073,7 @@ pq_recvbuf(bool nowait)
 	/* Can fill buffer from PqRecvLength and upwards */
 	for (;;)
 	{
-		/* If streaming compression is enabled then use correspondent compression read function. */
+		/* If streaming compression is enabled then use corresponding compression read function. */
 		r = PqStream
 			? zpq_read(PqStream, PqRecvBuffer + PqRecvLength,
 					   PQ_RECV_BUFFER_SIZE - PqRecvLength)
diff --git a/src/common/zpq_stream.c b/src/common/zpq_stream.c
index 459566228a..e044e83e7c 100644
--- a/src/common/zpq_stream.c
+++ b/src/common/zpq_stream.c
@@ -9,15 +9,15 @@
 typedef struct
 {
 	/*
-	 * Returns name of compression algorithm.
+	 * Name of compression algorithm.
 	 */
 	char const* (*name)(void);
 
 	/*
-	 * Create compression stream with using rx/tx function for fetching/sending compressed data.
+	 * Create compression stream with rx/tx function for reading/sending compressed data.
 	 * level: compression level
 	 * tx_func: function for writing compressed data in underlying stream
-	 * rx_func: function for receiving compressed data from underlying stream
+	 * rx_func: function for reading compressed data from underlying stream
 	 * arg: context passed to the function
      * rx_data: received data (compressed data already fetched from input stream)
 	 * rx_data_size: size of data fetched from input stream
@@ -27,14 +27,14 @@ typedef struct
 	/*
 	 * Read up to "size" raw (decompressed) bytes.
 	 * Returns number of decompressed bytes or error code.
-	 * Error code is either ZPQ_DECOMPRESS_ERROR either error code returned by the rx function.
+	 * Error code is either ZPQ_DECOMPRESS_ERROR or error code returned by the rx function.
 	 */
 	ssize_t (*read)(ZpqStream *zs, void *buf, size_t size);
 
 	/*
 	 * Write up to "size" raw (decompressed) bytes.
 	 * Returns number of written raw bytes or error code returned by tx function.
-	 * In the last case amount of written raw bytes is stored in *processed.
+	 * In the last case number of bytes written is stored in *processed.
 	 */
 	ssize_t (*write)(ZpqStream *zs, void const *buf, size_t size, size_t *processed);
 
@@ -49,12 +49,12 @@ typedef struct
 	char const* (*error)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal tx decompression buffer.
+	 * Return amount of data in internal tx decompression buffer.
 	 */
 	size_t  (*buffered_tx)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal rx compression buffer.
+	 * Return amount of data in internal rx compression buffer.
 	 */
 	size_t  (*buffered_rx)(ZpqStream *zs);
 } ZpqAlgorithm;
@@ -265,7 +265,7 @@ zstd_name(void)
 
 #define ZLIB_BUFFER_SIZE       8192 /* We have to flush stream after each protocol command
 									 * and command is mostly limited by record length,
-									 * which in turn usually less than page size (except TOAST)
+									 * which in turn is usually less than page size (except TOAST)
 									 */
 
 typedef struct ZlibStream
diff --git a/src/include/common/zpq_stream.h b/src/include/common/zpq_stream.h
index 27aef0aab9..991e2c0165 100644
--- a/src/include/common/zpq_stream.h
+++ b/src/include/common/zpq_stream.h
@@ -1,6 +1,6 @@
 /*
  * zpq_stream.h
- *     Streaiming compression for libpq
+ *     Streaming compression for libpq
  */
 
 #ifndef ZPQ_STREAM_H
diff --git a/src/interfaces/libpq/fe-connect.c b/src/interfaces/libpq/fe-connect.c
index eac6ef66cc..679f8cde9f 100644
--- a/src/interfaces/libpq/fe-connect.c
+++ b/src/interfaces/libpq/fe-connect.c
@@ -3269,7 +3269,7 @@ keep_going:						/* We will come back to here until there is
 						{
 							appendPQExpBuffer(&conn->errorMessage,
 											  libpq_gettext(
-												  "server is not supported requested compression algorithms %s\n"),
+												  "server does not support requested compression algorithms %s\n"),
 											  conn->compression);
 							goto error_return;
 						}
diff --git a/src/interfaces/libpq/fe-protocol3.c b/src/interfaces/libpq/fe-protocol3.c
index 095866bba0..5b879569b4 100644
--- a/src/interfaces/libpq/fe-protocol3.c
+++ b/src/interfaces/libpq/fe-protocol3.c
@@ -2135,15 +2135,15 @@ pqBuildStartupPacket3(PGconn *conn, int *packetlen,
 }
 
 /*
- * Build comma-separated list of compression algorithms suggested by client to the server.
- * It can be either explicitly specified by user in connection string, either
- * include all algorithms supported by clit library.
- * This functions returns true if compression string is successfully parsed and
- * stores comma-separated list of algorithms in *client_compressors.
- * If compression is disabled, then NULL is assigned to  *client_compressors.
- * Also it creates array of compressor descriptors, each element of which corresponds
- * the correspondent algorithm name in *client_compressors list. This array is stored in PGconn
- * and is used during handshake when compassion acknowledgment response is received from the server.
+ * Build comma-separated list of compression algorithms requested by client.
+ * It can be either explicitly specified by user in connection string, or
+ * include all algorithms supported by client library.
+ * This function returns true if the compression string is successfully parsed and
+ * stores a comma-separated list of algorithms in *client_compressors.
+ * If compression is disabled, then NULL is assigned to *client_compressors.
+ * Also it creates an array of compressor descriptors, each element of which corresponds to
+ * the corresponding algorithm name in *client_compressors list. This array is stored in PGconn
+ * and is used during handshake when a compression acknowledgment response is received from the server.
  */
 static bool
 build_compressors_list(PGconn *conn, char** client_compressors, bool build_descriptors)
@@ -2170,7 +2170,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 
 		if (n_supported_algorithms == 0)
 		{
-			*client_compressors = NULL; /* no compressors are avaialable */
+			*client_compressors = NULL; /* no compressors are available */
 			conn->compressors = NULL;
 			return true;
 		}
@@ -2204,7 +2204,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 	}
 	else
 	{
-		/* List of compresison algorithms separated by commas */
+		/* List of compression algorithms separated by commas */
 		char *src, *dst;
 		int n_suggested_algorithms = 0;
 		char* suggested_algorithms = strdup(value);
@@ -2232,7 +2232,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 				if (sscanf(col+1, "%d", &compression_level) != 1 && !build_descriptors)
 				{
 					fprintf(stderr,
-							libpq_gettext("WARNING: invlaid compression level %s in compression option '%s'\n"),
+							libpq_gettext("WARNING: invalid compression level %s in compression option '%s'\n"),
 							col+1, value);
 					return false;
 				}
@@ -2262,7 +2262,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 		{
 			if (!build_descriptors)
 				fprintf(stderr,
-						libpq_gettext("WARNING: none of specified algirthms %s is supported by client\n"),
+						libpq_gettext("WARNING: none of the specified algorithms are supported by client: %s\n"),
 						value);
 			else
 			{
-- 
2.17.0


--yudcn1FV7Hsu/q59--





^ permalink  raw  reply  [nested|flat] 22+ messages in thread

* [PATCH] fixes to docs and comments
@ 2021-01-09 15:49  Justin Pryzby <[email protected]>
  0 siblings, 0 replies; 22+ messages in thread

From: Justin Pryzby @ 2021-01-09 15:49 UTC (permalink / raw)

---
 doc/src/sgml/config.sgml            | 10 +++---
 doc/src/sgml/libpq.sgml             | 23 ++++++++----
 doc/src/sgml/protocol.sgml          | 54 +++++++++++++----------------
 src/backend/libpq/pqcomm.c          |  2 +-
 src/common/zpq_stream.c             | 16 ++++-----
 src/include/common/zpq_stream.h     |  2 +-
 src/interfaces/libpq/fe-connect.c   |  2 +-
 src/interfaces/libpq/fe-protocol3.c | 26 +++++++-------
 8 files changed, 69 insertions(+), 66 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 3b132dcf27..8b5a6525ac 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1004,12 +1004,10 @@ include_dir 'conf.d'
       </term>
       <listitem>
        <para>
-        When this parameter is <literal>on</literal> (default), the <productname>PostgreSQL</productname>
-        server can switch on compression of traffic between server and client if it is requested by client.
-        Client sends to the server list of compression algorithms supported by frontend library,
-        server chooses one which is supported by backend library and sends it in compression acknowledgement message
-        to the client. This option allows to reject compression request even if it is supported by server
-        (due to security, CPU consumption or whatever else reasons...).
+        This parameter enables compression of libpq traffic between client and server.
+        The default is <literal>on</literal>.
+        This option allows rejecting compression requests even if it is supported by server
+        (for example, due to security, or CPU consumption).
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 2934908520..d4da390ca9 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1244,13 +1244,22 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>compression</literal></term>
       <listitem>
       <para>
-        Request compression of libpq traffic. Client sends to the server list of compression algorithms, supported by client library.
-        If server supports one of this algorithms, then it acknowledges use of this algorithm and then all libpq messages send both from client to server and
-        visa versa will be compressed. If server is not supporting any of the suggested algorithms, then it rejects client request to use compression
-        and it is up to the client whether to continue work without compression or report error.
-        Supported compression algorithms are chosen at configure time. Right now two libraries are supported: zlib (default) and zstd (if Postgres was
-        configured with --with-zstd option). In both cases streaming mode is used.
-        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+        Request compression of libpq traffic. The client sends a request with a list of compression algorithms.
+        Compression can be requested by a client by including the "compression" option in its connection string.
+        This can either be a boolean value to enable or disable compression
+        ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto", or an explicit list of comma-separated compression algorithms
+        which can optionally include compression level ("zlib,zstd:5").
+        If compression is enabled but an algorithm is not explicitly specified, the client library sends its full list of
+        supported algorithms and the server chooses a preferred algorithm.
+
+        If the server accepts one of the algorithms, it replies with an acknowledgment and all future libpq messages between client and server
+        will be compressed.
+        If the server rejects the compression request, it is up to the client whether to continue without compression or to report an error.
+        Support for compression algorithms must be enabled when the server is compiled.
+        Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
+        configured with --with-zstd option). In both cases, streaming mode is used.
+        By default, compression is not requested by the client.
+        Please note that using compression together with SSL may expose extra vulnerabilities:
         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;
       </para>
       </listitem>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 9f30aad8bd..a69f9bfc26 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -94,10 +94,10 @@
 
   <para>
     It is possible to compress protocol data to reduce traffic and speed-up client-server interaction.
-    Compression is especially useful for importing/exporting data to/from database using COPY command
-    and for replication (both physical and logical). Also compression can reduce server response time
-    in case of queries returning large amount of data (for example returning JSON, BLOBs, text,...)
-    Right now two libraries are supported: zlib (default) and zstd (if Postgres was
+    Compression is especially useful for importing/exporting data to/from the database using the <literal>COPY</literal> command
+    and for replication (both physical and logical). Compression can also reduce the server's response time
+    for queries returning a large amount of data (for example, JSON, BLOBs, text, ...).
+    Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
     configured with --with-zstd option).
   </para>
 
@@ -275,19 +275,14 @@
       <term>CompressionAck</term>
       <listitem>
        <para>
-         Server acknowledges using compression for client-server communication protocol.
-         Compression can be requested by client by including "compression" option in connection string.
-         It can be just boolean values enabling or disabling compression
-         ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto" or explicit list of compression algorithms
-         separated by comma with optional specification of compression level: "zlib,zstd:5".
-         If compression algorithm is not explicitly specified the most efficient one supported both by
-         client and server is chosen. Client sends to the server list of compression algorithms,
-         supported by client library.
-         If server supports one of this algorithms, then it acknowledges use of this algorithm and
-         all subsequent libpq messages send both from client to server and
-         visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-         index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-         and it is up to the client whether to continue work without compression or report error.
+         The server accepts the client's compression request.
+         Compression is requested when a client connection includes the "compression" option, which includes
+         a list of requested compression algorithms.
+         If the server accepts one of these algorithms, it acknowledges use of compression and
+         all subsequent libpq messages between the client and server will be compressed.
+         The server chooses an algorithm from the list specified by client and responds with the index of the chosen algorithm from the client-supplied list.
+         If the server does not accept any of the requested algorithms, then it replies with an index of -1
+         and it is up to the client whether to continue without compression or to report an error.
        </para>
       </listitem>
      </varlistentry>
@@ -3460,12 +3455,14 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-  Acknowledge use of compression for protocol data. Client sends to the server list of compression algorithms, supported by client library.
-  If server supports one of this algorithms, then it acknowledges use of this algorithm and all subsequent libpq messages send both from client to server and
-  visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-  index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-  and it is up to the client whether to continue work without compression or report error.
-  After receiving this message with algorithm index other than -1, both server and client are switched to compression mode
+  Acknowledge use of compression for protocol data. The client sends to the server a list of requested compression algorithms.
+  If the server supports any of these algorithms, it acknowledges use of this algorithm and all subsequent libpq messages between client and server
+  will be compressed.
+  The server selects the preferred algorithm from the list specified by client and responds with the
+  index of the chosen algorithm in this list.
+  If the server does not support any of the requested algorithms, it replies with -1
+  and it is up to the client whether to continue without compression or to report an error.
+  After receiving this message with algorithm index other than -1, both server and client switch to compressed mode
   and exchange compressed messages.
 </para>
 </listitem>
@@ -3486,7 +3483,7 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-        Index of algorithm in the list of supported algotihms specified by client or -1 if none of them is supported.
+        Index of algorithm in the list of supported algorithms specified by client or -1 if none of them are supported.
 </para>
 </listitem>
 </varlistentry>
@@ -6069,12 +6066,11 @@ StartupMessage (F)
 </term>
 <listitem>
 <para>
-                        Request compression of libpq traffic. Value is list of compression algorithms supported by client with optional
+                        Request compression of libpq traffic. The value is a list of compression algorithms requested by the client with an optional
                         specification of compression level: <literal>"zlib,zstd:5"</literal>.
-                        When connecting to an older backend, which does not support compression, or in case when the backend support compression
-                        but for some reason wants to disable it, the backend will just ignore the _pq_.compression parameter and won’t send
-                        the compressionAck message to the frontend.
-                        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+                        If the server does not accept compression, the backend will ignore the _pq_.compression
+                        parameter and will not send the CompressionAck message to the frontend.
+                        By default, compression is disabled. Please note that using compression together with SSL may expose extra vulnerabilities:
                         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;.
 </para>
 </listitem>
diff --git a/src/backend/libpq/pqcomm.c b/src/backend/libpq/pqcomm.c
index 8be1ce18de..f3293faf01 100644
--- a/src/backend/libpq/pqcomm.c
+++ b/src/backend/libpq/pqcomm.c
@@ -1073,7 +1073,7 @@ pq_recvbuf(bool nowait)
 	/* Can fill buffer from PqRecvLength and upwards */
 	for (;;)
 	{
-		/* If streaming compression is enabled then use correspondent compression read function. */
+		/* If streaming compression is enabled then use corresponding compression read function. */
 		r = PqStream
 			? zpq_read(PqStream, PqRecvBuffer + PqRecvLength,
 					   PQ_RECV_BUFFER_SIZE - PqRecvLength)
diff --git a/src/common/zpq_stream.c b/src/common/zpq_stream.c
index 459566228a..e044e83e7c 100644
--- a/src/common/zpq_stream.c
+++ b/src/common/zpq_stream.c
@@ -9,15 +9,15 @@
 typedef struct
 {
 	/*
-	 * Returns name of compression algorithm.
+	 * Name of compression algorithm.
 	 */
 	char const* (*name)(void);
 
 	/*
-	 * Create compression stream with using rx/tx function for fetching/sending compressed data.
+	 * Create compression stream with rx/tx function for reading/sending compressed data.
 	 * level: compression level
 	 * tx_func: function for writing compressed data in underlying stream
-	 * rx_func: function for receiving compressed data from underlying stream
+	 * rx_func: function for reading compressed data from underlying stream
 	 * arg: context passed to the function
      * rx_data: received data (compressed data already fetched from input stream)
 	 * rx_data_size: size of data fetched from input stream
@@ -27,14 +27,14 @@ typedef struct
 	/*
 	 * Read up to "size" raw (decompressed) bytes.
 	 * Returns number of decompressed bytes or error code.
-	 * Error code is either ZPQ_DECOMPRESS_ERROR either error code returned by the rx function.
+	 * Error code is either ZPQ_DECOMPRESS_ERROR or error code returned by the rx function.
 	 */
 	ssize_t (*read)(ZpqStream *zs, void *buf, size_t size);
 
 	/*
 	 * Write up to "size" raw (decompressed) bytes.
 	 * Returns number of written raw bytes or error code returned by tx function.
-	 * In the last case amount of written raw bytes is stored in *processed.
+	 * In the last case number of bytes written is stored in *processed.
 	 */
 	ssize_t (*write)(ZpqStream *zs, void const *buf, size_t size, size_t *processed);
 
@@ -49,12 +49,12 @@ typedef struct
 	char const* (*error)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal tx decompression buffer.
+	 * Return amount of data in internal tx decompression buffer.
 	 */
 	size_t  (*buffered_tx)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal rx compression buffer.
+	 * Return amount of data in internal rx compression buffer.
 	 */
 	size_t  (*buffered_rx)(ZpqStream *zs);
 } ZpqAlgorithm;
@@ -265,7 +265,7 @@ zstd_name(void)
 
 #define ZLIB_BUFFER_SIZE       8192 /* We have to flush stream after each protocol command
 									 * and command is mostly limited by record length,
-									 * which in turn usually less than page size (except TOAST)
+									 * which in turn is usually less than page size (except TOAST)
 									 */
 
 typedef struct ZlibStream
diff --git a/src/include/common/zpq_stream.h b/src/include/common/zpq_stream.h
index 27aef0aab9..991e2c0165 100644
--- a/src/include/common/zpq_stream.h
+++ b/src/include/common/zpq_stream.h
@@ -1,6 +1,6 @@
 /*
  * zpq_stream.h
- *     Streaiming compression for libpq
+ *     Streaming compression for libpq
  */
 
 #ifndef ZPQ_STREAM_H
diff --git a/src/interfaces/libpq/fe-connect.c b/src/interfaces/libpq/fe-connect.c
index eac6ef66cc..679f8cde9f 100644
--- a/src/interfaces/libpq/fe-connect.c
+++ b/src/interfaces/libpq/fe-connect.c
@@ -3269,7 +3269,7 @@ keep_going:						/* We will come back to here until there is
 						{
 							appendPQExpBuffer(&conn->errorMessage,
 											  libpq_gettext(
-												  "server is not supported requested compression algorithms %s\n"),
+												  "server does not support requested compression algorithms %s\n"),
 											  conn->compression);
 							goto error_return;
 						}
diff --git a/src/interfaces/libpq/fe-protocol3.c b/src/interfaces/libpq/fe-protocol3.c
index 095866bba0..5b879569b4 100644
--- a/src/interfaces/libpq/fe-protocol3.c
+++ b/src/interfaces/libpq/fe-protocol3.c
@@ -2135,15 +2135,15 @@ pqBuildStartupPacket3(PGconn *conn, int *packetlen,
 }
 
 /*
- * Build comma-separated list of compression algorithms suggested by client to the server.
- * It can be either explicitly specified by user in connection string, either
- * include all algorithms supported by clit library.
- * This functions returns true if compression string is successfully parsed and
- * stores comma-separated list of algorithms in *client_compressors.
- * If compression is disabled, then NULL is assigned to  *client_compressors.
- * Also it creates array of compressor descriptors, each element of which corresponds
- * the correspondent algorithm name in *client_compressors list. This array is stored in PGconn
- * and is used during handshake when compassion acknowledgment response is received from the server.
+ * Build comma-separated list of compression algorithms requested by client.
+ * It can be either explicitly specified by user in connection string, or
+ * include all algorithms supported by client library.
+ * This function returns true if the compression string is successfully parsed and
+ * stores a comma-separated list of algorithms in *client_compressors.
+ * If compression is disabled, then NULL is assigned to *client_compressors.
+ * Also it creates an array of compressor descriptors, each element of which corresponds to
+ * the corresponding algorithm name in *client_compressors list. This array is stored in PGconn
+ * and is used during handshake when a compression acknowledgment response is received from the server.
  */
 static bool
 build_compressors_list(PGconn *conn, char** client_compressors, bool build_descriptors)
@@ -2170,7 +2170,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 
 		if (n_supported_algorithms == 0)
 		{
-			*client_compressors = NULL; /* no compressors are avaialable */
+			*client_compressors = NULL; /* no compressors are available */
 			conn->compressors = NULL;
 			return true;
 		}
@@ -2204,7 +2204,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 	}
 	else
 	{
-		/* List of compresison algorithms separated by commas */
+		/* List of compression algorithms separated by commas */
 		char *src, *dst;
 		int n_suggested_algorithms = 0;
 		char* suggested_algorithms = strdup(value);
@@ -2232,7 +2232,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 				if (sscanf(col+1, "%d", &compression_level) != 1 && !build_descriptors)
 				{
 					fprintf(stderr,
-							libpq_gettext("WARNING: invlaid compression level %s in compression option '%s'\n"),
+							libpq_gettext("WARNING: invalid compression level %s in compression option '%s'\n"),
 							col+1, value);
 					return false;
 				}
@@ -2262,7 +2262,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 		{
 			if (!build_descriptors)
 				fprintf(stderr,
-						libpq_gettext("WARNING: none of specified algirthms %s is supported by client\n"),
+						libpq_gettext("WARNING: none of the specified algorithms are supported by client: %s\n"),
 						value);
 			else
 			{
-- 
2.17.0


--yudcn1FV7Hsu/q59--





^ permalink  raw  reply  [nested|flat] 22+ messages in thread

* [PATCH] fixes to docs and comments
@ 2021-01-09 15:49  Justin Pryzby <[email protected]>
  0 siblings, 0 replies; 22+ messages in thread

From: Justin Pryzby @ 2021-01-09 15:49 UTC (permalink / raw)

---
 doc/src/sgml/config.sgml            | 10 +++---
 doc/src/sgml/libpq.sgml             | 23 ++++++++----
 doc/src/sgml/protocol.sgml          | 54 +++++++++++++----------------
 src/backend/libpq/pqcomm.c          |  2 +-
 src/common/zpq_stream.c             | 16 ++++-----
 src/include/common/zpq_stream.h     |  2 +-
 src/interfaces/libpq/fe-connect.c   |  2 +-
 src/interfaces/libpq/fe-protocol3.c | 26 +++++++-------
 8 files changed, 69 insertions(+), 66 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 3b132dcf27..8b5a6525ac 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1004,12 +1004,10 @@ include_dir 'conf.d'
       </term>
       <listitem>
        <para>
-        When this parameter is <literal>on</literal> (default), the <productname>PostgreSQL</productname>
-        server can switch on compression of traffic between server and client if it is requested by client.
-        Client sends to the server list of compression algorithms supported by frontend library,
-        server chooses one which is supported by backend library and sends it in compression acknowledgement message
-        to the client. This option allows to reject compression request even if it is supported by server
-        (due to security, CPU consumption or whatever else reasons...).
+        This parameter enables compression of libpq traffic between client and server.
+        The default is <literal>on</literal>.
+        This option allows rejecting compression requests even if it is supported by server
+        (for example, due to security, or CPU consumption).
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 2934908520..d4da390ca9 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1244,13 +1244,22 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>compression</literal></term>
       <listitem>
       <para>
-        Request compression of libpq traffic. Client sends to the server list of compression algorithms, supported by client library.
-        If server supports one of this algorithms, then it acknowledges use of this algorithm and then all libpq messages send both from client to server and
-        visa versa will be compressed. If server is not supporting any of the suggested algorithms, then it rejects client request to use compression
-        and it is up to the client whether to continue work without compression or report error.
-        Supported compression algorithms are chosen at configure time. Right now two libraries are supported: zlib (default) and zstd (if Postgres was
-        configured with --with-zstd option). In both cases streaming mode is used.
-        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+        Request compression of libpq traffic. The client sends a request with a list of compression algorithms.
+        Compression can be requested by a client by including the "compression" option in its connection string.
+        This can either be a boolean value to enable or disable compression
+        ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto", or an explicit list of comma-separated compression algorithms
+        which can optionally include compression level ("zlib,zstd:5").
+        If compression is enabled but an algorithm is not explicitly specified, the client library sends its full list of
+        supported algorithms and the server chooses a preferred algorithm.
+
+        If the server accepts one of the algorithms, it replies with an acknowledgment and all future libpq messages between client and server
+        will be compressed.
+        If the server rejects the compression request, it is up to the client whether to continue without compression or to report an error.
+        Support for compression algorithms must be enabled when the server is compiled.
+        Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
+        configured with --with-zstd option). In both cases, streaming mode is used.
+        By default, compression is not requested by the client.
+        Please note that using compression together with SSL may expose extra vulnerabilities:
         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;
       </para>
       </listitem>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 9f30aad8bd..a69f9bfc26 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -94,10 +94,10 @@
 
   <para>
     It is possible to compress protocol data to reduce traffic and speed-up client-server interaction.
-    Compression is especially useful for importing/exporting data to/from database using COPY command
-    and for replication (both physical and logical). Also compression can reduce server response time
-    in case of queries returning large amount of data (for example returning JSON, BLOBs, text,...)
-    Right now two libraries are supported: zlib (default) and zstd (if Postgres was
+    Compression is especially useful for importing/exporting data to/from the database using the <literal>COPY</literal> command
+    and for replication (both physical and logical). Compression can also reduce the server's response time
+    for queries returning a large amount of data (for example, JSON, BLOBs, text, ...).
+    Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
     configured with --with-zstd option).
   </para>
 
@@ -275,19 +275,14 @@
       <term>CompressionAck</term>
       <listitem>
        <para>
-         Server acknowledges using compression for client-server communication protocol.
-         Compression can be requested by client by including "compression" option in connection string.
-         It can be just boolean values enabling or disabling compression
-         ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto" or explicit list of compression algorithms
-         separated by comma with optional specification of compression level: "zlib,zstd:5".
-         If compression algorithm is not explicitly specified the most efficient one supported both by
-         client and server is chosen. Client sends to the server list of compression algorithms,
-         supported by client library.
-         If server supports one of this algorithms, then it acknowledges use of this algorithm and
-         all subsequent libpq messages send both from client to server and
-         visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-         index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-         and it is up to the client whether to continue work without compression or report error.
+         The server accepts the client's compression request.
+         Compression is requested when a client connection includes the "compression" option, which includes
+         a list of requested compression algorithms.
+         If the server accepts one of these algorithms, it acknowledges use of compression and
+         all subsequent libpq messages between the client and server will be compressed.
+         The server chooses an algorithm from the list specified by client and responds with the index of the chosen algorithm from the client-supplied list.
+         If the server does not accept any of the requested algorithms, then it replies with an index of -1
+         and it is up to the client whether to continue without compression or to report an error.
        </para>
       </listitem>
      </varlistentry>
@@ -3460,12 +3455,14 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-  Acknowledge use of compression for protocol data. Client sends to the server list of compression algorithms, supported by client library.
-  If server supports one of this algorithms, then it acknowledges use of this algorithm and all subsequent libpq messages send both from client to server and
-  visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-  index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-  and it is up to the client whether to continue work without compression or report error.
-  After receiving this message with algorithm index other than -1, both server and client are switched to compression mode
+  Acknowledge use of compression for protocol data. The client sends to the server a list of requested compression algorithms.
+  If the server supports any of these algorithms, it acknowledges use of this algorithm and all subsequent libpq messages between client and server
+  will be compressed.
+  The server selects the preferred algorithm from the list specified by client and responds with the
+  index of the chosen algorithm in this list.
+  If the server does not support any of the requested algorithms, it replies with -1
+  and it is up to the client whether to continue without compression or to report an error.
+  After receiving this message with algorithm index other than -1, both server and client switch to compressed mode
   and exchange compressed messages.
 </para>
 </listitem>
@@ -3486,7 +3483,7 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-        Index of algorithm in the list of supported algotihms specified by client or -1 if none of them is supported.
+        Index of algorithm in the list of supported algorithms specified by client or -1 if none of them are supported.
 </para>
 </listitem>
 </varlistentry>
@@ -6069,12 +6066,11 @@ StartupMessage (F)
 </term>
 <listitem>
 <para>
-                        Request compression of libpq traffic. Value is list of compression algorithms supported by client with optional
+                        Request compression of libpq traffic. The value is a list of compression algorithms requested by the client with an optional
                         specification of compression level: <literal>"zlib,zstd:5"</literal>.
-                        When connecting to an older backend, which does not support compression, or in case when the backend support compression
-                        but for some reason wants to disable it, the backend will just ignore the _pq_.compression parameter and won’t send
-                        the compressionAck message to the frontend.
-                        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+                        If the server does not accept compression, the backend will ignore the _pq_.compression
+                        parameter and will not send the CompressionAck message to the frontend.
+                        By default, compression is disabled. Please note that using compression together with SSL may expose extra vulnerabilities:
                         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;.
 </para>
 </listitem>
diff --git a/src/backend/libpq/pqcomm.c b/src/backend/libpq/pqcomm.c
index 8be1ce18de..f3293faf01 100644
--- a/src/backend/libpq/pqcomm.c
+++ b/src/backend/libpq/pqcomm.c
@@ -1073,7 +1073,7 @@ pq_recvbuf(bool nowait)
 	/* Can fill buffer from PqRecvLength and upwards */
 	for (;;)
 	{
-		/* If streaming compression is enabled then use correspondent compression read function. */
+		/* If streaming compression is enabled then use corresponding compression read function. */
 		r = PqStream
 			? zpq_read(PqStream, PqRecvBuffer + PqRecvLength,
 					   PQ_RECV_BUFFER_SIZE - PqRecvLength)
diff --git a/src/common/zpq_stream.c b/src/common/zpq_stream.c
index 459566228a..e044e83e7c 100644
--- a/src/common/zpq_stream.c
+++ b/src/common/zpq_stream.c
@@ -9,15 +9,15 @@
 typedef struct
 {
 	/*
-	 * Returns name of compression algorithm.
+	 * Name of compression algorithm.
 	 */
 	char const* (*name)(void);
 
 	/*
-	 * Create compression stream with using rx/tx function for fetching/sending compressed data.
+	 * Create compression stream with rx/tx function for reading/sending compressed data.
 	 * level: compression level
 	 * tx_func: function for writing compressed data in underlying stream
-	 * rx_func: function for receiving compressed data from underlying stream
+	 * rx_func: function for reading compressed data from underlying stream
 	 * arg: context passed to the function
      * rx_data: received data (compressed data already fetched from input stream)
 	 * rx_data_size: size of data fetched from input stream
@@ -27,14 +27,14 @@ typedef struct
 	/*
 	 * Read up to "size" raw (decompressed) bytes.
 	 * Returns number of decompressed bytes or error code.
-	 * Error code is either ZPQ_DECOMPRESS_ERROR either error code returned by the rx function.
+	 * Error code is either ZPQ_DECOMPRESS_ERROR or error code returned by the rx function.
 	 */
 	ssize_t (*read)(ZpqStream *zs, void *buf, size_t size);
 
 	/*
 	 * Write up to "size" raw (decompressed) bytes.
 	 * Returns number of written raw bytes or error code returned by tx function.
-	 * In the last case amount of written raw bytes is stored in *processed.
+	 * In the last case number of bytes written is stored in *processed.
 	 */
 	ssize_t (*write)(ZpqStream *zs, void const *buf, size_t size, size_t *processed);
 
@@ -49,12 +49,12 @@ typedef struct
 	char const* (*error)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal tx decompression buffer.
+	 * Return amount of data in internal tx decompression buffer.
 	 */
 	size_t  (*buffered_tx)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal rx compression buffer.
+	 * Return amount of data in internal rx compression buffer.
 	 */
 	size_t  (*buffered_rx)(ZpqStream *zs);
 } ZpqAlgorithm;
@@ -265,7 +265,7 @@ zstd_name(void)
 
 #define ZLIB_BUFFER_SIZE       8192 /* We have to flush stream after each protocol command
 									 * and command is mostly limited by record length,
-									 * which in turn usually less than page size (except TOAST)
+									 * which in turn is usually less than page size (except TOAST)
 									 */
 
 typedef struct ZlibStream
diff --git a/src/include/common/zpq_stream.h b/src/include/common/zpq_stream.h
index 27aef0aab9..991e2c0165 100644
--- a/src/include/common/zpq_stream.h
+++ b/src/include/common/zpq_stream.h
@@ -1,6 +1,6 @@
 /*
  * zpq_stream.h
- *     Streaiming compression for libpq
+ *     Streaming compression for libpq
  */
 
 #ifndef ZPQ_STREAM_H
diff --git a/src/interfaces/libpq/fe-connect.c b/src/interfaces/libpq/fe-connect.c
index eac6ef66cc..679f8cde9f 100644
--- a/src/interfaces/libpq/fe-connect.c
+++ b/src/interfaces/libpq/fe-connect.c
@@ -3269,7 +3269,7 @@ keep_going:						/* We will come back to here until there is
 						{
 							appendPQExpBuffer(&conn->errorMessage,
 											  libpq_gettext(
-												  "server is not supported requested compression algorithms %s\n"),
+												  "server does not support requested compression algorithms %s\n"),
 											  conn->compression);
 							goto error_return;
 						}
diff --git a/src/interfaces/libpq/fe-protocol3.c b/src/interfaces/libpq/fe-protocol3.c
index 095866bba0..5b879569b4 100644
--- a/src/interfaces/libpq/fe-protocol3.c
+++ b/src/interfaces/libpq/fe-protocol3.c
@@ -2135,15 +2135,15 @@ pqBuildStartupPacket3(PGconn *conn, int *packetlen,
 }
 
 /*
- * Build comma-separated list of compression algorithms suggested by client to the server.
- * It can be either explicitly specified by user in connection string, either
- * include all algorithms supported by clit library.
- * This functions returns true if compression string is successfully parsed and
- * stores comma-separated list of algorithms in *client_compressors.
- * If compression is disabled, then NULL is assigned to  *client_compressors.
- * Also it creates array of compressor descriptors, each element of which corresponds
- * the correspondent algorithm name in *client_compressors list. This array is stored in PGconn
- * and is used during handshake when compassion acknowledgment response is received from the server.
+ * Build comma-separated list of compression algorithms requested by client.
+ * It can be either explicitly specified by user in connection string, or
+ * include all algorithms supported by client library.
+ * This function returns true if the compression string is successfully parsed and
+ * stores a comma-separated list of algorithms in *client_compressors.
+ * If compression is disabled, then NULL is assigned to *client_compressors.
+ * Also it creates an array of compressor descriptors, each element of which corresponds to
+ * the corresponding algorithm name in *client_compressors list. This array is stored in PGconn
+ * and is used during handshake when a compression acknowledgment response is received from the server.
  */
 static bool
 build_compressors_list(PGconn *conn, char** client_compressors, bool build_descriptors)
@@ -2170,7 +2170,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 
 		if (n_supported_algorithms == 0)
 		{
-			*client_compressors = NULL; /* no compressors are avaialable */
+			*client_compressors = NULL; /* no compressors are available */
 			conn->compressors = NULL;
 			return true;
 		}
@@ -2204,7 +2204,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 	}
 	else
 	{
-		/* List of compresison algorithms separated by commas */
+		/* List of compression algorithms separated by commas */
 		char *src, *dst;
 		int n_suggested_algorithms = 0;
 		char* suggested_algorithms = strdup(value);
@@ -2232,7 +2232,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 				if (sscanf(col+1, "%d", &compression_level) != 1 && !build_descriptors)
 				{
 					fprintf(stderr,
-							libpq_gettext("WARNING: invlaid compression level %s in compression option '%s'\n"),
+							libpq_gettext("WARNING: invalid compression level %s in compression option '%s'\n"),
 							col+1, value);
 					return false;
 				}
@@ -2262,7 +2262,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 		{
 			if (!build_descriptors)
 				fprintf(stderr,
-						libpq_gettext("WARNING: none of specified algirthms %s is supported by client\n"),
+						libpq_gettext("WARNING: none of the specified algorithms are supported by client: %s\n"),
 						value);
 			else
 			{
-- 
2.17.0


--yudcn1FV7Hsu/q59--





^ permalink  raw  reply  [nested|flat] 22+ messages in thread

* [PATCH] fixes to docs and comments
@ 2021-01-09 15:49  Justin Pryzby <[email protected]>
  0 siblings, 0 replies; 22+ messages in thread

From: Justin Pryzby @ 2021-01-09 15:49 UTC (permalink / raw)

---
 doc/src/sgml/config.sgml            | 10 +++---
 doc/src/sgml/libpq.sgml             | 23 ++++++++----
 doc/src/sgml/protocol.sgml          | 54 +++++++++++++----------------
 src/backend/libpq/pqcomm.c          |  2 +-
 src/common/zpq_stream.c             | 16 ++++-----
 src/include/common/zpq_stream.h     |  2 +-
 src/interfaces/libpq/fe-connect.c   |  2 +-
 src/interfaces/libpq/fe-protocol3.c | 26 +++++++-------
 8 files changed, 69 insertions(+), 66 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 3b132dcf27..8b5a6525ac 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1004,12 +1004,10 @@ include_dir 'conf.d'
       </term>
       <listitem>
        <para>
-        When this parameter is <literal>on</literal> (default), the <productname>PostgreSQL</productname>
-        server can switch on compression of traffic between server and client if it is requested by client.
-        Client sends to the server list of compression algorithms supported by frontend library,
-        server chooses one which is supported by backend library and sends it in compression acknowledgement message
-        to the client. This option allows to reject compression request even if it is supported by server
-        (due to security, CPU consumption or whatever else reasons...).
+        This parameter enables compression of libpq traffic between client and server.
+        The default is <literal>on</literal>.
+        This option allows rejecting compression requests even if it is supported by server
+        (for example, due to security, or CPU consumption).
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 2934908520..d4da390ca9 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1244,13 +1244,22 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>compression</literal></term>
       <listitem>
       <para>
-        Request compression of libpq traffic. Client sends to the server list of compression algorithms, supported by client library.
-        If server supports one of this algorithms, then it acknowledges use of this algorithm and then all libpq messages send both from client to server and
-        visa versa will be compressed. If server is not supporting any of the suggested algorithms, then it rejects client request to use compression
-        and it is up to the client whether to continue work without compression or report error.
-        Supported compression algorithms are chosen at configure time. Right now two libraries are supported: zlib (default) and zstd (if Postgres was
-        configured with --with-zstd option). In both cases streaming mode is used.
-        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+        Request compression of libpq traffic. The client sends a request with a list of compression algorithms.
+        Compression can be requested by a client by including the "compression" option in its connection string.
+        This can either be a boolean value to enable or disable compression
+        ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto", or an explicit list of comma-separated compression algorithms
+        which can optionally include compression level ("zlib,zstd:5").
+        If compression is enabled but an algorithm is not explicitly specified, the client library sends its full list of
+        supported algorithms and the server chooses a preferred algorithm.
+
+        If the server accepts one of the algorithms, it replies with an acknowledgment and all future libpq messages between client and server
+        will be compressed.
+        If the server rejects the compression request, it is up to the client whether to continue without compression or to report an error.
+        Support for compression algorithms must be enabled when the server is compiled.
+        Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
+        configured with --with-zstd option). In both cases, streaming mode is used.
+        By default, compression is not requested by the client.
+        Please note that using compression together with SSL may expose extra vulnerabilities:
         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;
       </para>
       </listitem>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 9f30aad8bd..a69f9bfc26 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -94,10 +94,10 @@
 
   <para>
     It is possible to compress protocol data to reduce traffic and speed-up client-server interaction.
-    Compression is especially useful for importing/exporting data to/from database using COPY command
-    and for replication (both physical and logical). Also compression can reduce server response time
-    in case of queries returning large amount of data (for example returning JSON, BLOBs, text,...)
-    Right now two libraries are supported: zlib (default) and zstd (if Postgres was
+    Compression is especially useful for importing/exporting data to/from the database using the <literal>COPY</literal> command
+    and for replication (both physical and logical). Compression can also reduce the server's response time
+    for queries returning a large amount of data (for example, JSON, BLOBs, text, ...).
+    Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
     configured with --with-zstd option).
   </para>
 
@@ -275,19 +275,14 @@
       <term>CompressionAck</term>
       <listitem>
        <para>
-         Server acknowledges using compression for client-server communication protocol.
-         Compression can be requested by client by including "compression" option in connection string.
-         It can be just boolean values enabling or disabling compression
-         ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto" or explicit list of compression algorithms
-         separated by comma with optional specification of compression level: "zlib,zstd:5".
-         If compression algorithm is not explicitly specified the most efficient one supported both by
-         client and server is chosen. Client sends to the server list of compression algorithms,
-         supported by client library.
-         If server supports one of this algorithms, then it acknowledges use of this algorithm and
-         all subsequent libpq messages send both from client to server and
-         visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-         index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-         and it is up to the client whether to continue work without compression or report error.
+         The server accepts the client's compression request.
+         Compression is requested when a client connection includes the "compression" option, which includes
+         a list of requested compression algorithms.
+         If the server accepts one of these algorithms, it acknowledges use of compression and
+         all subsequent libpq messages between the client and server will be compressed.
+         The server chooses an algorithm from the list specified by client and responds with the index of the chosen algorithm from the client-supplied list.
+         If the server does not accept any of the requested algorithms, then it replies with an index of -1
+         and it is up to the client whether to continue without compression or to report an error.
        </para>
       </listitem>
      </varlistentry>
@@ -3460,12 +3455,14 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-  Acknowledge use of compression for protocol data. Client sends to the server list of compression algorithms, supported by client library.
-  If server supports one of this algorithms, then it acknowledges use of this algorithm and all subsequent libpq messages send both from client to server and
-  visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-  index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-  and it is up to the client whether to continue work without compression or report error.
-  After receiving this message with algorithm index other than -1, both server and client are switched to compression mode
+  Acknowledge use of compression for protocol data. The client sends to the server a list of requested compression algorithms.
+  If the server supports any of these algorithms, it acknowledges use of this algorithm and all subsequent libpq messages between client and server
+  will be compressed.
+  The server selects the preferred algorithm from the list specified by client and responds with the
+  index of the chosen algorithm in this list.
+  If the server does not support any of the requested algorithms, it replies with -1
+  and it is up to the client whether to continue without compression or to report an error.
+  After receiving this message with algorithm index other than -1, both server and client switch to compressed mode
   and exchange compressed messages.
 </para>
 </listitem>
@@ -3486,7 +3483,7 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-        Index of algorithm in the list of supported algotihms specified by client or -1 if none of them is supported.
+        Index of algorithm in the list of supported algorithms specified by client or -1 if none of them are supported.
 </para>
 </listitem>
 </varlistentry>
@@ -6069,12 +6066,11 @@ StartupMessage (F)
 </term>
 <listitem>
 <para>
-                        Request compression of libpq traffic. Value is list of compression algorithms supported by client with optional
+                        Request compression of libpq traffic. The value is a list of compression algorithms requested by the client with an optional
                         specification of compression level: <literal>"zlib,zstd:5"</literal>.
-                        When connecting to an older backend, which does not support compression, or in case when the backend support compression
-                        but for some reason wants to disable it, the backend will just ignore the _pq_.compression parameter and won’t send
-                        the compressionAck message to the frontend.
-                        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+                        If the server does not accept compression, the backend will ignore the _pq_.compression
+                        parameter and will not send the CompressionAck message to the frontend.
+                        By default, compression is disabled. Please note that using compression together with SSL may expose extra vulnerabilities:
                         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;.
 </para>
 </listitem>
diff --git a/src/backend/libpq/pqcomm.c b/src/backend/libpq/pqcomm.c
index 8be1ce18de..f3293faf01 100644
--- a/src/backend/libpq/pqcomm.c
+++ b/src/backend/libpq/pqcomm.c
@@ -1073,7 +1073,7 @@ pq_recvbuf(bool nowait)
 	/* Can fill buffer from PqRecvLength and upwards */
 	for (;;)
 	{
-		/* If streaming compression is enabled then use correspondent compression read function. */
+		/* If streaming compression is enabled then use corresponding compression read function. */
 		r = PqStream
 			? zpq_read(PqStream, PqRecvBuffer + PqRecvLength,
 					   PQ_RECV_BUFFER_SIZE - PqRecvLength)
diff --git a/src/common/zpq_stream.c b/src/common/zpq_stream.c
index 459566228a..e044e83e7c 100644
--- a/src/common/zpq_stream.c
+++ b/src/common/zpq_stream.c
@@ -9,15 +9,15 @@
 typedef struct
 {
 	/*
-	 * Returns name of compression algorithm.
+	 * Name of compression algorithm.
 	 */
 	char const* (*name)(void);
 
 	/*
-	 * Create compression stream with using rx/tx function for fetching/sending compressed data.
+	 * Create compression stream with rx/tx function for reading/sending compressed data.
 	 * level: compression level
 	 * tx_func: function for writing compressed data in underlying stream
-	 * rx_func: function for receiving compressed data from underlying stream
+	 * rx_func: function for reading compressed data from underlying stream
 	 * arg: context passed to the function
      * rx_data: received data (compressed data already fetched from input stream)
 	 * rx_data_size: size of data fetched from input stream
@@ -27,14 +27,14 @@ typedef struct
 	/*
 	 * Read up to "size" raw (decompressed) bytes.
 	 * Returns number of decompressed bytes or error code.
-	 * Error code is either ZPQ_DECOMPRESS_ERROR either error code returned by the rx function.
+	 * Error code is either ZPQ_DECOMPRESS_ERROR or error code returned by the rx function.
 	 */
 	ssize_t (*read)(ZpqStream *zs, void *buf, size_t size);
 
 	/*
 	 * Write up to "size" raw (decompressed) bytes.
 	 * Returns number of written raw bytes or error code returned by tx function.
-	 * In the last case amount of written raw bytes is stored in *processed.
+	 * In the last case number of bytes written is stored in *processed.
 	 */
 	ssize_t (*write)(ZpqStream *zs, void const *buf, size_t size, size_t *processed);
 
@@ -49,12 +49,12 @@ typedef struct
 	char const* (*error)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal tx decompression buffer.
+	 * Return amount of data in internal tx decompression buffer.
 	 */
 	size_t  (*buffered_tx)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal rx compression buffer.
+	 * Return amount of data in internal rx compression buffer.
 	 */
 	size_t  (*buffered_rx)(ZpqStream *zs);
 } ZpqAlgorithm;
@@ -265,7 +265,7 @@ zstd_name(void)
 
 #define ZLIB_BUFFER_SIZE       8192 /* We have to flush stream after each protocol command
 									 * and command is mostly limited by record length,
-									 * which in turn usually less than page size (except TOAST)
+									 * which in turn is usually less than page size (except TOAST)
 									 */
 
 typedef struct ZlibStream
diff --git a/src/include/common/zpq_stream.h b/src/include/common/zpq_stream.h
index 27aef0aab9..991e2c0165 100644
--- a/src/include/common/zpq_stream.h
+++ b/src/include/common/zpq_stream.h
@@ -1,6 +1,6 @@
 /*
  * zpq_stream.h
- *     Streaiming compression for libpq
+ *     Streaming compression for libpq
  */
 
 #ifndef ZPQ_STREAM_H
diff --git a/src/interfaces/libpq/fe-connect.c b/src/interfaces/libpq/fe-connect.c
index eac6ef66cc..679f8cde9f 100644
--- a/src/interfaces/libpq/fe-connect.c
+++ b/src/interfaces/libpq/fe-connect.c
@@ -3269,7 +3269,7 @@ keep_going:						/* We will come back to here until there is
 						{
 							appendPQExpBuffer(&conn->errorMessage,
 											  libpq_gettext(
-												  "server is not supported requested compression algorithms %s\n"),
+												  "server does not support requested compression algorithms %s\n"),
 											  conn->compression);
 							goto error_return;
 						}
diff --git a/src/interfaces/libpq/fe-protocol3.c b/src/interfaces/libpq/fe-protocol3.c
index 095866bba0..5b879569b4 100644
--- a/src/interfaces/libpq/fe-protocol3.c
+++ b/src/interfaces/libpq/fe-protocol3.c
@@ -2135,15 +2135,15 @@ pqBuildStartupPacket3(PGconn *conn, int *packetlen,
 }
 
 /*
- * Build comma-separated list of compression algorithms suggested by client to the server.
- * It can be either explicitly specified by user in connection string, either
- * include all algorithms supported by clit library.
- * This functions returns true if compression string is successfully parsed and
- * stores comma-separated list of algorithms in *client_compressors.
- * If compression is disabled, then NULL is assigned to  *client_compressors.
- * Also it creates array of compressor descriptors, each element of which corresponds
- * the correspondent algorithm name in *client_compressors list. This array is stored in PGconn
- * and is used during handshake when compassion acknowledgment response is received from the server.
+ * Build comma-separated list of compression algorithms requested by client.
+ * It can be either explicitly specified by user in connection string, or
+ * include all algorithms supported by client library.
+ * This function returns true if the compression string is successfully parsed and
+ * stores a comma-separated list of algorithms in *client_compressors.
+ * If compression is disabled, then NULL is assigned to *client_compressors.
+ * Also it creates an array of compressor descriptors, each element of which corresponds to
+ * the corresponding algorithm name in *client_compressors list. This array is stored in PGconn
+ * and is used during handshake when a compression acknowledgment response is received from the server.
  */
 static bool
 build_compressors_list(PGconn *conn, char** client_compressors, bool build_descriptors)
@@ -2170,7 +2170,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 
 		if (n_supported_algorithms == 0)
 		{
-			*client_compressors = NULL; /* no compressors are avaialable */
+			*client_compressors = NULL; /* no compressors are available */
 			conn->compressors = NULL;
 			return true;
 		}
@@ -2204,7 +2204,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 	}
 	else
 	{
-		/* List of compresison algorithms separated by commas */
+		/* List of compression algorithms separated by commas */
 		char *src, *dst;
 		int n_suggested_algorithms = 0;
 		char* suggested_algorithms = strdup(value);
@@ -2232,7 +2232,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 				if (sscanf(col+1, "%d", &compression_level) != 1 && !build_descriptors)
 				{
 					fprintf(stderr,
-							libpq_gettext("WARNING: invlaid compression level %s in compression option '%s'\n"),
+							libpq_gettext("WARNING: invalid compression level %s in compression option '%s'\n"),
 							col+1, value);
 					return false;
 				}
@@ -2262,7 +2262,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 		{
 			if (!build_descriptors)
 				fprintf(stderr,
-						libpq_gettext("WARNING: none of specified algirthms %s is supported by client\n"),
+						libpq_gettext("WARNING: none of the specified algorithms are supported by client: %s\n"),
 						value);
 			else
 			{
-- 
2.17.0


--yudcn1FV7Hsu/q59--





^ permalink  raw  reply  [nested|flat] 22+ messages in thread

* [PATCH] fixes to docs and comments
@ 2021-01-09 15:49  Justin Pryzby <[email protected]>
  0 siblings, 0 replies; 22+ messages in thread

From: Justin Pryzby @ 2021-01-09 15:49 UTC (permalink / raw)

---
 doc/src/sgml/config.sgml            | 10 +++---
 doc/src/sgml/libpq.sgml             | 23 ++++++++----
 doc/src/sgml/protocol.sgml          | 54 +++++++++++++----------------
 src/backend/libpq/pqcomm.c          |  2 +-
 src/common/zpq_stream.c             | 16 ++++-----
 src/include/common/zpq_stream.h     |  2 +-
 src/interfaces/libpq/fe-connect.c   |  2 +-
 src/interfaces/libpq/fe-protocol3.c | 26 +++++++-------
 8 files changed, 69 insertions(+), 66 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 3b132dcf27..8b5a6525ac 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1004,12 +1004,10 @@ include_dir 'conf.d'
       </term>
       <listitem>
        <para>
-        When this parameter is <literal>on</literal> (default), the <productname>PostgreSQL</productname>
-        server can switch on compression of traffic between server and client if it is requested by client.
-        Client sends to the server list of compression algorithms supported by frontend library,
-        server chooses one which is supported by backend library and sends it in compression acknowledgement message
-        to the client. This option allows to reject compression request even if it is supported by server
-        (due to security, CPU consumption or whatever else reasons...).
+        This parameter enables compression of libpq traffic between client and server.
+        The default is <literal>on</literal>.
+        This option allows rejecting compression requests even if it is supported by server
+        (for example, due to security, or CPU consumption).
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 2934908520..d4da390ca9 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1244,13 +1244,22 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>compression</literal></term>
       <listitem>
       <para>
-        Request compression of libpq traffic. Client sends to the server list of compression algorithms, supported by client library.
-        If server supports one of this algorithms, then it acknowledges use of this algorithm and then all libpq messages send both from client to server and
-        visa versa will be compressed. If server is not supporting any of the suggested algorithms, then it rejects client request to use compression
-        and it is up to the client whether to continue work without compression or report error.
-        Supported compression algorithms are chosen at configure time. Right now two libraries are supported: zlib (default) and zstd (if Postgres was
-        configured with --with-zstd option). In both cases streaming mode is used.
-        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+        Request compression of libpq traffic. The client sends a request with a list of compression algorithms.
+        Compression can be requested by a client by including the "compression" option in its connection string.
+        This can either be a boolean value to enable or disable compression
+        ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto", or an explicit list of comma-separated compression algorithms
+        which can optionally include compression level ("zlib,zstd:5").
+        If compression is enabled but an algorithm is not explicitly specified, the client library sends its full list of
+        supported algorithms and the server chooses a preferred algorithm.
+
+        If the server accepts one of the algorithms, it replies with an acknowledgment and all future libpq messages between client and server
+        will be compressed.
+        If the server rejects the compression request, it is up to the client whether to continue without compression or to report an error.
+        Support for compression algorithms must be enabled when the server is compiled.
+        Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
+        configured with --with-zstd option). In both cases, streaming mode is used.
+        By default, compression is not requested by the client.
+        Please note that using compression together with SSL may expose extra vulnerabilities:
         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;
       </para>
       </listitem>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 9f30aad8bd..a69f9bfc26 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -94,10 +94,10 @@
 
   <para>
     It is possible to compress protocol data to reduce traffic and speed-up client-server interaction.
-    Compression is especially useful for importing/exporting data to/from database using COPY command
-    and for replication (both physical and logical). Also compression can reduce server response time
-    in case of queries returning large amount of data (for example returning JSON, BLOBs, text,...)
-    Right now two libraries are supported: zlib (default) and zstd (if Postgres was
+    Compression is especially useful for importing/exporting data to/from the database using the <literal>COPY</literal> command
+    and for replication (both physical and logical). Compression can also reduce the server's response time
+    for queries returning a large amount of data (for example, JSON, BLOBs, text, ...).
+    Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
     configured with --with-zstd option).
   </para>
 
@@ -275,19 +275,14 @@
       <term>CompressionAck</term>
       <listitem>
        <para>
-         Server acknowledges using compression for client-server communication protocol.
-         Compression can be requested by client by including "compression" option in connection string.
-         It can be just boolean values enabling or disabling compression
-         ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto" or explicit list of compression algorithms
-         separated by comma with optional specification of compression level: "zlib,zstd:5".
-         If compression algorithm is not explicitly specified the most efficient one supported both by
-         client and server is chosen. Client sends to the server list of compression algorithms,
-         supported by client library.
-         If server supports one of this algorithms, then it acknowledges use of this algorithm and
-         all subsequent libpq messages send both from client to server and
-         visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-         index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-         and it is up to the client whether to continue work without compression or report error.
+         The server accepts the client's compression request.
+         Compression is requested when a client connection includes the "compression" option, which includes
+         a list of requested compression algorithms.
+         If the server accepts one of these algorithms, it acknowledges use of compression and
+         all subsequent libpq messages between the client and server will be compressed.
+         The server chooses an algorithm from the list specified by client and responds with the index of the chosen algorithm from the client-supplied list.
+         If the server does not accept any of the requested algorithms, then it replies with an index of -1
+         and it is up to the client whether to continue without compression or to report an error.
        </para>
       </listitem>
      </varlistentry>
@@ -3460,12 +3455,14 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-  Acknowledge use of compression for protocol data. Client sends to the server list of compression algorithms, supported by client library.
-  If server supports one of this algorithms, then it acknowledges use of this algorithm and all subsequent libpq messages send both from client to server and
-  visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-  index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-  and it is up to the client whether to continue work without compression or report error.
-  After receiving this message with algorithm index other than -1, both server and client are switched to compression mode
+  Acknowledge use of compression for protocol data. The client sends to the server a list of requested compression algorithms.
+  If the server supports any of these algorithms, it acknowledges use of this algorithm and all subsequent libpq messages between client and server
+  will be compressed.
+  The server selects the preferred algorithm from the list specified by client and responds with the
+  index of the chosen algorithm in this list.
+  If the server does not support any of the requested algorithms, it replies with -1
+  and it is up to the client whether to continue without compression or to report an error.
+  After receiving this message with algorithm index other than -1, both server and client switch to compressed mode
   and exchange compressed messages.
 </para>
 </listitem>
@@ -3486,7 +3483,7 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-        Index of algorithm in the list of supported algotihms specified by client or -1 if none of them is supported.
+        Index of algorithm in the list of supported algorithms specified by client or -1 if none of them are supported.
 </para>
 </listitem>
 </varlistentry>
@@ -6069,12 +6066,11 @@ StartupMessage (F)
 </term>
 <listitem>
 <para>
-                        Request compression of libpq traffic. Value is list of compression algorithms supported by client with optional
+                        Request compression of libpq traffic. The value is a list of compression algorithms requested by the client with an optional
                         specification of compression level: <literal>"zlib,zstd:5"</literal>.
-                        When connecting to an older backend, which does not support compression, or in case when the backend support compression
-                        but for some reason wants to disable it, the backend will just ignore the _pq_.compression parameter and won’t send
-                        the compressionAck message to the frontend.
-                        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+                        If the server does not accept compression, the backend will ignore the _pq_.compression
+                        parameter and will not send the CompressionAck message to the frontend.
+                        By default, compression is disabled. Please note that using compression together with SSL may expose extra vulnerabilities:
                         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;.
 </para>
 </listitem>
diff --git a/src/backend/libpq/pqcomm.c b/src/backend/libpq/pqcomm.c
index 8be1ce18de..f3293faf01 100644
--- a/src/backend/libpq/pqcomm.c
+++ b/src/backend/libpq/pqcomm.c
@@ -1073,7 +1073,7 @@ pq_recvbuf(bool nowait)
 	/* Can fill buffer from PqRecvLength and upwards */
 	for (;;)
 	{
-		/* If streaming compression is enabled then use correspondent compression read function. */
+		/* If streaming compression is enabled then use corresponding compression read function. */
 		r = PqStream
 			? zpq_read(PqStream, PqRecvBuffer + PqRecvLength,
 					   PQ_RECV_BUFFER_SIZE - PqRecvLength)
diff --git a/src/common/zpq_stream.c b/src/common/zpq_stream.c
index 459566228a..e044e83e7c 100644
--- a/src/common/zpq_stream.c
+++ b/src/common/zpq_stream.c
@@ -9,15 +9,15 @@
 typedef struct
 {
 	/*
-	 * Returns name of compression algorithm.
+	 * Name of compression algorithm.
 	 */
 	char const* (*name)(void);
 
 	/*
-	 * Create compression stream with using rx/tx function for fetching/sending compressed data.
+	 * Create compression stream with rx/tx function for reading/sending compressed data.
 	 * level: compression level
 	 * tx_func: function for writing compressed data in underlying stream
-	 * rx_func: function for receiving compressed data from underlying stream
+	 * rx_func: function for reading compressed data from underlying stream
 	 * arg: context passed to the function
      * rx_data: received data (compressed data already fetched from input stream)
 	 * rx_data_size: size of data fetched from input stream
@@ -27,14 +27,14 @@ typedef struct
 	/*
 	 * Read up to "size" raw (decompressed) bytes.
 	 * Returns number of decompressed bytes or error code.
-	 * Error code is either ZPQ_DECOMPRESS_ERROR either error code returned by the rx function.
+	 * Error code is either ZPQ_DECOMPRESS_ERROR or error code returned by the rx function.
 	 */
 	ssize_t (*read)(ZpqStream *zs, void *buf, size_t size);
 
 	/*
 	 * Write up to "size" raw (decompressed) bytes.
 	 * Returns number of written raw bytes or error code returned by tx function.
-	 * In the last case amount of written raw bytes is stored in *processed.
+	 * In the last case number of bytes written is stored in *processed.
 	 */
 	ssize_t (*write)(ZpqStream *zs, void const *buf, size_t size, size_t *processed);
 
@@ -49,12 +49,12 @@ typedef struct
 	char const* (*error)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal tx decompression buffer.
+	 * Return amount of data in internal tx decompression buffer.
 	 */
 	size_t  (*buffered_tx)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal rx compression buffer.
+	 * Return amount of data in internal rx compression buffer.
 	 */
 	size_t  (*buffered_rx)(ZpqStream *zs);
 } ZpqAlgorithm;
@@ -265,7 +265,7 @@ zstd_name(void)
 
 #define ZLIB_BUFFER_SIZE       8192 /* We have to flush stream after each protocol command
 									 * and command is mostly limited by record length,
-									 * which in turn usually less than page size (except TOAST)
+									 * which in turn is usually less than page size (except TOAST)
 									 */
 
 typedef struct ZlibStream
diff --git a/src/include/common/zpq_stream.h b/src/include/common/zpq_stream.h
index 27aef0aab9..991e2c0165 100644
--- a/src/include/common/zpq_stream.h
+++ b/src/include/common/zpq_stream.h
@@ -1,6 +1,6 @@
 /*
  * zpq_stream.h
- *     Streaiming compression for libpq
+ *     Streaming compression for libpq
  */
 
 #ifndef ZPQ_STREAM_H
diff --git a/src/interfaces/libpq/fe-connect.c b/src/interfaces/libpq/fe-connect.c
index eac6ef66cc..679f8cde9f 100644
--- a/src/interfaces/libpq/fe-connect.c
+++ b/src/interfaces/libpq/fe-connect.c
@@ -3269,7 +3269,7 @@ keep_going:						/* We will come back to here until there is
 						{
 							appendPQExpBuffer(&conn->errorMessage,
 											  libpq_gettext(
-												  "server is not supported requested compression algorithms %s\n"),
+												  "server does not support requested compression algorithms %s\n"),
 											  conn->compression);
 							goto error_return;
 						}
diff --git a/src/interfaces/libpq/fe-protocol3.c b/src/interfaces/libpq/fe-protocol3.c
index 095866bba0..5b879569b4 100644
--- a/src/interfaces/libpq/fe-protocol3.c
+++ b/src/interfaces/libpq/fe-protocol3.c
@@ -2135,15 +2135,15 @@ pqBuildStartupPacket3(PGconn *conn, int *packetlen,
 }
 
 /*
- * Build comma-separated list of compression algorithms suggested by client to the server.
- * It can be either explicitly specified by user in connection string, either
- * include all algorithms supported by clit library.
- * This functions returns true if compression string is successfully parsed and
- * stores comma-separated list of algorithms in *client_compressors.
- * If compression is disabled, then NULL is assigned to  *client_compressors.
- * Also it creates array of compressor descriptors, each element of which corresponds
- * the correspondent algorithm name in *client_compressors list. This array is stored in PGconn
- * and is used during handshake when compassion acknowledgment response is received from the server.
+ * Build comma-separated list of compression algorithms requested by client.
+ * It can be either explicitly specified by user in connection string, or
+ * include all algorithms supported by client library.
+ * This function returns true if the compression string is successfully parsed and
+ * stores a comma-separated list of algorithms in *client_compressors.
+ * If compression is disabled, then NULL is assigned to *client_compressors.
+ * Also it creates an array of compressor descriptors, each element of which corresponds to
+ * the corresponding algorithm name in *client_compressors list. This array is stored in PGconn
+ * and is used during handshake when a compression acknowledgment response is received from the server.
  */
 static bool
 build_compressors_list(PGconn *conn, char** client_compressors, bool build_descriptors)
@@ -2170,7 +2170,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 
 		if (n_supported_algorithms == 0)
 		{
-			*client_compressors = NULL; /* no compressors are avaialable */
+			*client_compressors = NULL; /* no compressors are available */
 			conn->compressors = NULL;
 			return true;
 		}
@@ -2204,7 +2204,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 	}
 	else
 	{
-		/* List of compresison algorithms separated by commas */
+		/* List of compression algorithms separated by commas */
 		char *src, *dst;
 		int n_suggested_algorithms = 0;
 		char* suggested_algorithms = strdup(value);
@@ -2232,7 +2232,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 				if (sscanf(col+1, "%d", &compression_level) != 1 && !build_descriptors)
 				{
 					fprintf(stderr,
-							libpq_gettext("WARNING: invlaid compression level %s in compression option '%s'\n"),
+							libpq_gettext("WARNING: invalid compression level %s in compression option '%s'\n"),
 							col+1, value);
 					return false;
 				}
@@ -2262,7 +2262,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 		{
 			if (!build_descriptors)
 				fprintf(stderr,
-						libpq_gettext("WARNING: none of specified algirthms %s is supported by client\n"),
+						libpq_gettext("WARNING: none of the specified algorithms are supported by client: %s\n"),
 						value);
 			else
 			{
-- 
2.17.0


--yudcn1FV7Hsu/q59--





^ permalink  raw  reply  [nested|flat] 22+ messages in thread

* [PATCH] fixes to docs and comments
@ 2021-01-09 15:49  Justin Pryzby <[email protected]>
  0 siblings, 0 replies; 22+ messages in thread

From: Justin Pryzby @ 2021-01-09 15:49 UTC (permalink / raw)

---
 doc/src/sgml/config.sgml            | 10 +++---
 doc/src/sgml/libpq.sgml             | 23 ++++++++----
 doc/src/sgml/protocol.sgml          | 54 +++++++++++++----------------
 src/backend/libpq/pqcomm.c          |  2 +-
 src/common/zpq_stream.c             | 16 ++++-----
 src/include/common/zpq_stream.h     |  2 +-
 src/interfaces/libpq/fe-connect.c   |  2 +-
 src/interfaces/libpq/fe-protocol3.c | 26 +++++++-------
 8 files changed, 69 insertions(+), 66 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 3b132dcf27..8b5a6525ac 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1004,12 +1004,10 @@ include_dir 'conf.d'
       </term>
       <listitem>
        <para>
-        When this parameter is <literal>on</literal> (default), the <productname>PostgreSQL</productname>
-        server can switch on compression of traffic between server and client if it is requested by client.
-        Client sends to the server list of compression algorithms supported by frontend library,
-        server chooses one which is supported by backend library and sends it in compression acknowledgement message
-        to the client. This option allows to reject compression request even if it is supported by server
-        (due to security, CPU consumption or whatever else reasons...).
+        This parameter enables compression of libpq traffic between client and server.
+        The default is <literal>on</literal>.
+        This option allows rejecting compression requests even if it is supported by server
+        (for example, due to security, or CPU consumption).
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 2934908520..d4da390ca9 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1244,13 +1244,22 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>compression</literal></term>
       <listitem>
       <para>
-        Request compression of libpq traffic. Client sends to the server list of compression algorithms, supported by client library.
-        If server supports one of this algorithms, then it acknowledges use of this algorithm and then all libpq messages send both from client to server and
-        visa versa will be compressed. If server is not supporting any of the suggested algorithms, then it rejects client request to use compression
-        and it is up to the client whether to continue work without compression or report error.
-        Supported compression algorithms are chosen at configure time. Right now two libraries are supported: zlib (default) and zstd (if Postgres was
-        configured with --with-zstd option). In both cases streaming mode is used.
-        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+        Request compression of libpq traffic. The client sends a request with a list of compression algorithms.
+        Compression can be requested by a client by including the "compression" option in its connection string.
+        This can either be a boolean value to enable or disable compression
+        ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto", or an explicit list of comma-separated compression algorithms
+        which can optionally include compression level ("zlib,zstd:5").
+        If compression is enabled but an algorithm is not explicitly specified, the client library sends its full list of
+        supported algorithms and the server chooses a preferred algorithm.
+
+        If the server accepts one of the algorithms, it replies with an acknowledgment and all future libpq messages between client and server
+        will be compressed.
+        If the server rejects the compression request, it is up to the client whether to continue without compression or to report an error.
+        Support for compression algorithms must be enabled when the server is compiled.
+        Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
+        configured with --with-zstd option). In both cases, streaming mode is used.
+        By default, compression is not requested by the client.
+        Please note that using compression together with SSL may expose extra vulnerabilities:
         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;
       </para>
       </listitem>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 9f30aad8bd..a69f9bfc26 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -94,10 +94,10 @@
 
   <para>
     It is possible to compress protocol data to reduce traffic and speed-up client-server interaction.
-    Compression is especially useful for importing/exporting data to/from database using COPY command
-    and for replication (both physical and logical). Also compression can reduce server response time
-    in case of queries returning large amount of data (for example returning JSON, BLOBs, text,...)
-    Right now two libraries are supported: zlib (default) and zstd (if Postgres was
+    Compression is especially useful for importing/exporting data to/from the database using the <literal>COPY</literal> command
+    and for replication (both physical and logical). Compression can also reduce the server's response time
+    for queries returning a large amount of data (for example, JSON, BLOBs, text, ...).
+    Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
     configured with --with-zstd option).
   </para>
 
@@ -275,19 +275,14 @@
       <term>CompressionAck</term>
       <listitem>
        <para>
-         Server acknowledges using compression for client-server communication protocol.
-         Compression can be requested by client by including "compression" option in connection string.
-         It can be just boolean values enabling or disabling compression
-         ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto" or explicit list of compression algorithms
-         separated by comma with optional specification of compression level: "zlib,zstd:5".
-         If compression algorithm is not explicitly specified the most efficient one supported both by
-         client and server is chosen. Client sends to the server list of compression algorithms,
-         supported by client library.
-         If server supports one of this algorithms, then it acknowledges use of this algorithm and
-         all subsequent libpq messages send both from client to server and
-         visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-         index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-         and it is up to the client whether to continue work without compression or report error.
+         The server accepts the client's compression request.
+         Compression is requested when a client connection includes the "compression" option, which includes
+         a list of requested compression algorithms.
+         If the server accepts one of these algorithms, it acknowledges use of compression and
+         all subsequent libpq messages between the client and server will be compressed.
+         The server chooses an algorithm from the list specified by client and responds with the index of the chosen algorithm from the client-supplied list.
+         If the server does not accept any of the requested algorithms, then it replies with an index of -1
+         and it is up to the client whether to continue without compression or to report an error.
        </para>
       </listitem>
      </varlistentry>
@@ -3460,12 +3455,14 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-  Acknowledge use of compression for protocol data. Client sends to the server list of compression algorithms, supported by client library.
-  If server supports one of this algorithms, then it acknowledges use of this algorithm and all subsequent libpq messages send both from client to server and
-  visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-  index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-  and it is up to the client whether to continue work without compression or report error.
-  After receiving this message with algorithm index other than -1, both server and client are switched to compression mode
+  Acknowledge use of compression for protocol data. The client sends to the server a list of requested compression algorithms.
+  If the server supports any of these algorithms, it acknowledges use of this algorithm and all subsequent libpq messages between client and server
+  will be compressed.
+  The server selects the preferred algorithm from the list specified by client and responds with the
+  index of the chosen algorithm in this list.
+  If the server does not support any of the requested algorithms, it replies with -1
+  and it is up to the client whether to continue without compression or to report an error.
+  After receiving this message with algorithm index other than -1, both server and client switch to compressed mode
   and exchange compressed messages.
 </para>
 </listitem>
@@ -3486,7 +3483,7 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-        Index of algorithm in the list of supported algotihms specified by client or -1 if none of them is supported.
+        Index of algorithm in the list of supported algorithms specified by client or -1 if none of them are supported.
 </para>
 </listitem>
 </varlistentry>
@@ -6069,12 +6066,11 @@ StartupMessage (F)
 </term>
 <listitem>
 <para>
-                        Request compression of libpq traffic. Value is list of compression algorithms supported by client with optional
+                        Request compression of libpq traffic. The value is a list of compression algorithms requested by the client with an optional
                         specification of compression level: <literal>"zlib,zstd:5"</literal>.
-                        When connecting to an older backend, which does not support compression, or in case when the backend support compression
-                        but for some reason wants to disable it, the backend will just ignore the _pq_.compression parameter and won’t send
-                        the compressionAck message to the frontend.
-                        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+                        If the server does not accept compression, the backend will ignore the _pq_.compression
+                        parameter and will not send the CompressionAck message to the frontend.
+                        By default, compression is disabled. Please note that using compression together with SSL may expose extra vulnerabilities:
                         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;.
 </para>
 </listitem>
diff --git a/src/backend/libpq/pqcomm.c b/src/backend/libpq/pqcomm.c
index 8be1ce18de..f3293faf01 100644
--- a/src/backend/libpq/pqcomm.c
+++ b/src/backend/libpq/pqcomm.c
@@ -1073,7 +1073,7 @@ pq_recvbuf(bool nowait)
 	/* Can fill buffer from PqRecvLength and upwards */
 	for (;;)
 	{
-		/* If streaming compression is enabled then use correspondent compression read function. */
+		/* If streaming compression is enabled then use corresponding compression read function. */
 		r = PqStream
 			? zpq_read(PqStream, PqRecvBuffer + PqRecvLength,
 					   PQ_RECV_BUFFER_SIZE - PqRecvLength)
diff --git a/src/common/zpq_stream.c b/src/common/zpq_stream.c
index 459566228a..e044e83e7c 100644
--- a/src/common/zpq_stream.c
+++ b/src/common/zpq_stream.c
@@ -9,15 +9,15 @@
 typedef struct
 {
 	/*
-	 * Returns name of compression algorithm.
+	 * Name of compression algorithm.
 	 */
 	char const* (*name)(void);
 
 	/*
-	 * Create compression stream with using rx/tx function for fetching/sending compressed data.
+	 * Create compression stream with rx/tx function for reading/sending compressed data.
 	 * level: compression level
 	 * tx_func: function for writing compressed data in underlying stream
-	 * rx_func: function for receiving compressed data from underlying stream
+	 * rx_func: function for reading compressed data from underlying stream
 	 * arg: context passed to the function
      * rx_data: received data (compressed data already fetched from input stream)
 	 * rx_data_size: size of data fetched from input stream
@@ -27,14 +27,14 @@ typedef struct
 	/*
 	 * Read up to "size" raw (decompressed) bytes.
 	 * Returns number of decompressed bytes or error code.
-	 * Error code is either ZPQ_DECOMPRESS_ERROR either error code returned by the rx function.
+	 * Error code is either ZPQ_DECOMPRESS_ERROR or error code returned by the rx function.
 	 */
 	ssize_t (*read)(ZpqStream *zs, void *buf, size_t size);
 
 	/*
 	 * Write up to "size" raw (decompressed) bytes.
 	 * Returns number of written raw bytes or error code returned by tx function.
-	 * In the last case amount of written raw bytes is stored in *processed.
+	 * In the last case number of bytes written is stored in *processed.
 	 */
 	ssize_t (*write)(ZpqStream *zs, void const *buf, size_t size, size_t *processed);
 
@@ -49,12 +49,12 @@ typedef struct
 	char const* (*error)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal tx decompression buffer.
+	 * Return amount of data in internal tx decompression buffer.
 	 */
 	size_t  (*buffered_tx)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal rx compression buffer.
+	 * Return amount of data in internal rx compression buffer.
 	 */
 	size_t  (*buffered_rx)(ZpqStream *zs);
 } ZpqAlgorithm;
@@ -265,7 +265,7 @@ zstd_name(void)
 
 #define ZLIB_BUFFER_SIZE       8192 /* We have to flush stream after each protocol command
 									 * and command is mostly limited by record length,
-									 * which in turn usually less than page size (except TOAST)
+									 * which in turn is usually less than page size (except TOAST)
 									 */
 
 typedef struct ZlibStream
diff --git a/src/include/common/zpq_stream.h b/src/include/common/zpq_stream.h
index 27aef0aab9..991e2c0165 100644
--- a/src/include/common/zpq_stream.h
+++ b/src/include/common/zpq_stream.h
@@ -1,6 +1,6 @@
 /*
  * zpq_stream.h
- *     Streaiming compression for libpq
+ *     Streaming compression for libpq
  */
 
 #ifndef ZPQ_STREAM_H
diff --git a/src/interfaces/libpq/fe-connect.c b/src/interfaces/libpq/fe-connect.c
index eac6ef66cc..679f8cde9f 100644
--- a/src/interfaces/libpq/fe-connect.c
+++ b/src/interfaces/libpq/fe-connect.c
@@ -3269,7 +3269,7 @@ keep_going:						/* We will come back to here until there is
 						{
 							appendPQExpBuffer(&conn->errorMessage,
 											  libpq_gettext(
-												  "server is not supported requested compression algorithms %s\n"),
+												  "server does not support requested compression algorithms %s\n"),
 											  conn->compression);
 							goto error_return;
 						}
diff --git a/src/interfaces/libpq/fe-protocol3.c b/src/interfaces/libpq/fe-protocol3.c
index 095866bba0..5b879569b4 100644
--- a/src/interfaces/libpq/fe-protocol3.c
+++ b/src/interfaces/libpq/fe-protocol3.c
@@ -2135,15 +2135,15 @@ pqBuildStartupPacket3(PGconn *conn, int *packetlen,
 }
 
 /*
- * Build comma-separated list of compression algorithms suggested by client to the server.
- * It can be either explicitly specified by user in connection string, either
- * include all algorithms supported by clit library.
- * This functions returns true if compression string is successfully parsed and
- * stores comma-separated list of algorithms in *client_compressors.
- * If compression is disabled, then NULL is assigned to  *client_compressors.
- * Also it creates array of compressor descriptors, each element of which corresponds
- * the correspondent algorithm name in *client_compressors list. This array is stored in PGconn
- * and is used during handshake when compassion acknowledgment response is received from the server.
+ * Build comma-separated list of compression algorithms requested by client.
+ * It can be either explicitly specified by user in connection string, or
+ * include all algorithms supported by client library.
+ * This function returns true if the compression string is successfully parsed and
+ * stores a comma-separated list of algorithms in *client_compressors.
+ * If compression is disabled, then NULL is assigned to *client_compressors.
+ * Also it creates an array of compressor descriptors, each element of which corresponds to
+ * the corresponding algorithm name in *client_compressors list. This array is stored in PGconn
+ * and is used during handshake when a compression acknowledgment response is received from the server.
  */
 static bool
 build_compressors_list(PGconn *conn, char** client_compressors, bool build_descriptors)
@@ -2170,7 +2170,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 
 		if (n_supported_algorithms == 0)
 		{
-			*client_compressors = NULL; /* no compressors are avaialable */
+			*client_compressors = NULL; /* no compressors are available */
 			conn->compressors = NULL;
 			return true;
 		}
@@ -2204,7 +2204,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 	}
 	else
 	{
-		/* List of compresison algorithms separated by commas */
+		/* List of compression algorithms separated by commas */
 		char *src, *dst;
 		int n_suggested_algorithms = 0;
 		char* suggested_algorithms = strdup(value);
@@ -2232,7 +2232,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 				if (sscanf(col+1, "%d", &compression_level) != 1 && !build_descriptors)
 				{
 					fprintf(stderr,
-							libpq_gettext("WARNING: invlaid compression level %s in compression option '%s'\n"),
+							libpq_gettext("WARNING: invalid compression level %s in compression option '%s'\n"),
 							col+1, value);
 					return false;
 				}
@@ -2262,7 +2262,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 		{
 			if (!build_descriptors)
 				fprintf(stderr,
-						libpq_gettext("WARNING: none of specified algirthms %s is supported by client\n"),
+						libpq_gettext("WARNING: none of the specified algorithms are supported by client: %s\n"),
 						value);
 			else
 			{
-- 
2.17.0


--yudcn1FV7Hsu/q59--





^ permalink  raw  reply  [nested|flat] 22+ messages in thread

* [PATCH] fixes to docs and comments
@ 2021-01-09 15:49  Justin Pryzby <[email protected]>
  0 siblings, 0 replies; 22+ messages in thread

From: Justin Pryzby @ 2021-01-09 15:49 UTC (permalink / raw)

---
 doc/src/sgml/config.sgml            | 10 +++---
 doc/src/sgml/libpq.sgml             | 23 ++++++++----
 doc/src/sgml/protocol.sgml          | 54 +++++++++++++----------------
 src/backend/libpq/pqcomm.c          |  2 +-
 src/common/zpq_stream.c             | 16 ++++-----
 src/include/common/zpq_stream.h     |  2 +-
 src/interfaces/libpq/fe-connect.c   |  2 +-
 src/interfaces/libpq/fe-protocol3.c | 26 +++++++-------
 8 files changed, 69 insertions(+), 66 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 3b132dcf27..8b5a6525ac 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1004,12 +1004,10 @@ include_dir 'conf.d'
       </term>
       <listitem>
        <para>
-        When this parameter is <literal>on</literal> (default), the <productname>PostgreSQL</productname>
-        server can switch on compression of traffic between server and client if it is requested by client.
-        Client sends to the server list of compression algorithms supported by frontend library,
-        server chooses one which is supported by backend library and sends it in compression acknowledgement message
-        to the client. This option allows to reject compression request even if it is supported by server
-        (due to security, CPU consumption or whatever else reasons...).
+        This parameter enables compression of libpq traffic between client and server.
+        The default is <literal>on</literal>.
+        This option allows rejecting compression requests even if it is supported by server
+        (for example, due to security, or CPU consumption).
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 2934908520..d4da390ca9 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1244,13 +1244,22 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>compression</literal></term>
       <listitem>
       <para>
-        Request compression of libpq traffic. Client sends to the server list of compression algorithms, supported by client library.
-        If server supports one of this algorithms, then it acknowledges use of this algorithm and then all libpq messages send both from client to server and
-        visa versa will be compressed. If server is not supporting any of the suggested algorithms, then it rejects client request to use compression
-        and it is up to the client whether to continue work without compression or report error.
-        Supported compression algorithms are chosen at configure time. Right now two libraries are supported: zlib (default) and zstd (if Postgres was
-        configured with --with-zstd option). In both cases streaming mode is used.
-        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+        Request compression of libpq traffic. The client sends a request with a list of compression algorithms.
+        Compression can be requested by a client by including the "compression" option in its connection string.
+        This can either be a boolean value to enable or disable compression
+        ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto", or an explicit list of comma-separated compression algorithms
+        which can optionally include compression level ("zlib,zstd:5").
+        If compression is enabled but an algorithm is not explicitly specified, the client library sends its full list of
+        supported algorithms and the server chooses a preferred algorithm.
+
+        If the server accepts one of the algorithms, it replies with an acknowledgment and all future libpq messages between client and server
+        will be compressed.
+        If the server rejects the compression request, it is up to the client whether to continue without compression or to report an error.
+        Support for compression algorithms must be enabled when the server is compiled.
+        Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
+        configured with --with-zstd option). In both cases, streaming mode is used.
+        By default, compression is not requested by the client.
+        Please note that using compression together with SSL may expose extra vulnerabilities:
         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;
       </para>
       </listitem>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 9f30aad8bd..a69f9bfc26 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -94,10 +94,10 @@
 
   <para>
     It is possible to compress protocol data to reduce traffic and speed-up client-server interaction.
-    Compression is especially useful for importing/exporting data to/from database using COPY command
-    and for replication (both physical and logical). Also compression can reduce server response time
-    in case of queries returning large amount of data (for example returning JSON, BLOBs, text,...)
-    Right now two libraries are supported: zlib (default) and zstd (if Postgres was
+    Compression is especially useful for importing/exporting data to/from the database using the <literal>COPY</literal> command
+    and for replication (both physical and logical). Compression can also reduce the server's response time
+    for queries returning a large amount of data (for example, JSON, BLOBs, text, ...).
+    Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
     configured with --with-zstd option).
   </para>
 
@@ -275,19 +275,14 @@
       <term>CompressionAck</term>
       <listitem>
        <para>
-         Server acknowledges using compression for client-server communication protocol.
-         Compression can be requested by client by including "compression" option in connection string.
-         It can be just boolean values enabling or disabling compression
-         ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto" or explicit list of compression algorithms
-         separated by comma with optional specification of compression level: "zlib,zstd:5".
-         If compression algorithm is not explicitly specified the most efficient one supported both by
-         client and server is chosen. Client sends to the server list of compression algorithms,
-         supported by client library.
-         If server supports one of this algorithms, then it acknowledges use of this algorithm and
-         all subsequent libpq messages send both from client to server and
-         visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-         index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-         and it is up to the client whether to continue work without compression or report error.
+         The server accepts the client's compression request.
+         Compression is requested when a client connection includes the "compression" option, which includes
+         a list of requested compression algorithms.
+         If the server accepts one of these algorithms, it acknowledges use of compression and
+         all subsequent libpq messages between the client and server will be compressed.
+         The server chooses an algorithm from the list specified by client and responds with the index of the chosen algorithm from the client-supplied list.
+         If the server does not accept any of the requested algorithms, then it replies with an index of -1
+         and it is up to the client whether to continue without compression or to report an error.
        </para>
       </listitem>
      </varlistentry>
@@ -3460,12 +3455,14 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-  Acknowledge use of compression for protocol data. Client sends to the server list of compression algorithms, supported by client library.
-  If server supports one of this algorithms, then it acknowledges use of this algorithm and all subsequent libpq messages send both from client to server and
-  visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-  index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-  and it is up to the client whether to continue work without compression or report error.
-  After receiving this message with algorithm index other than -1, both server and client are switched to compression mode
+  Acknowledge use of compression for protocol data. The client sends to the server a list of requested compression algorithms.
+  If the server supports any of these algorithms, it acknowledges use of this algorithm and all subsequent libpq messages between client and server
+  will be compressed.
+  The server selects the preferred algorithm from the list specified by client and responds with the
+  index of the chosen algorithm in this list.
+  If the server does not support any of the requested algorithms, it replies with -1
+  and it is up to the client whether to continue without compression or to report an error.
+  After receiving this message with algorithm index other than -1, both server and client switch to compressed mode
   and exchange compressed messages.
 </para>
 </listitem>
@@ -3486,7 +3483,7 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-        Index of algorithm in the list of supported algotihms specified by client or -1 if none of them is supported.
+        Index of algorithm in the list of supported algorithms specified by client or -1 if none of them are supported.
 </para>
 </listitem>
 </varlistentry>
@@ -6069,12 +6066,11 @@ StartupMessage (F)
 </term>
 <listitem>
 <para>
-                        Request compression of libpq traffic. Value is list of compression algorithms supported by client with optional
+                        Request compression of libpq traffic. The value is a list of compression algorithms requested by the client with an optional
                         specification of compression level: <literal>"zlib,zstd:5"</literal>.
-                        When connecting to an older backend, which does not support compression, or in case when the backend support compression
-                        but for some reason wants to disable it, the backend will just ignore the _pq_.compression parameter and won’t send
-                        the compressionAck message to the frontend.
-                        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+                        If the server does not accept compression, the backend will ignore the _pq_.compression
+                        parameter and will not send the CompressionAck message to the frontend.
+                        By default, compression is disabled. Please note that using compression together with SSL may expose extra vulnerabilities:
                         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;.
 </para>
 </listitem>
diff --git a/src/backend/libpq/pqcomm.c b/src/backend/libpq/pqcomm.c
index 8be1ce18de..f3293faf01 100644
--- a/src/backend/libpq/pqcomm.c
+++ b/src/backend/libpq/pqcomm.c
@@ -1073,7 +1073,7 @@ pq_recvbuf(bool nowait)
 	/* Can fill buffer from PqRecvLength and upwards */
 	for (;;)
 	{
-		/* If streaming compression is enabled then use correspondent compression read function. */
+		/* If streaming compression is enabled then use corresponding compression read function. */
 		r = PqStream
 			? zpq_read(PqStream, PqRecvBuffer + PqRecvLength,
 					   PQ_RECV_BUFFER_SIZE - PqRecvLength)
diff --git a/src/common/zpq_stream.c b/src/common/zpq_stream.c
index 459566228a..e044e83e7c 100644
--- a/src/common/zpq_stream.c
+++ b/src/common/zpq_stream.c
@@ -9,15 +9,15 @@
 typedef struct
 {
 	/*
-	 * Returns name of compression algorithm.
+	 * Name of compression algorithm.
 	 */
 	char const* (*name)(void);
 
 	/*
-	 * Create compression stream with using rx/tx function for fetching/sending compressed data.
+	 * Create compression stream with rx/tx function for reading/sending compressed data.
 	 * level: compression level
 	 * tx_func: function for writing compressed data in underlying stream
-	 * rx_func: function for receiving compressed data from underlying stream
+	 * rx_func: function for reading compressed data from underlying stream
 	 * arg: context passed to the function
      * rx_data: received data (compressed data already fetched from input stream)
 	 * rx_data_size: size of data fetched from input stream
@@ -27,14 +27,14 @@ typedef struct
 	/*
 	 * Read up to "size" raw (decompressed) bytes.
 	 * Returns number of decompressed bytes or error code.
-	 * Error code is either ZPQ_DECOMPRESS_ERROR either error code returned by the rx function.
+	 * Error code is either ZPQ_DECOMPRESS_ERROR or error code returned by the rx function.
 	 */
 	ssize_t (*read)(ZpqStream *zs, void *buf, size_t size);
 
 	/*
 	 * Write up to "size" raw (decompressed) bytes.
 	 * Returns number of written raw bytes or error code returned by tx function.
-	 * In the last case amount of written raw bytes is stored in *processed.
+	 * In the last case number of bytes written is stored in *processed.
 	 */
 	ssize_t (*write)(ZpqStream *zs, void const *buf, size_t size, size_t *processed);
 
@@ -49,12 +49,12 @@ typedef struct
 	char const* (*error)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal tx decompression buffer.
+	 * Return amount of data in internal tx decompression buffer.
 	 */
 	size_t  (*buffered_tx)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal rx compression buffer.
+	 * Return amount of data in internal rx compression buffer.
 	 */
 	size_t  (*buffered_rx)(ZpqStream *zs);
 } ZpqAlgorithm;
@@ -265,7 +265,7 @@ zstd_name(void)
 
 #define ZLIB_BUFFER_SIZE       8192 /* We have to flush stream after each protocol command
 									 * and command is mostly limited by record length,
-									 * which in turn usually less than page size (except TOAST)
+									 * which in turn is usually less than page size (except TOAST)
 									 */
 
 typedef struct ZlibStream
diff --git a/src/include/common/zpq_stream.h b/src/include/common/zpq_stream.h
index 27aef0aab9..991e2c0165 100644
--- a/src/include/common/zpq_stream.h
+++ b/src/include/common/zpq_stream.h
@@ -1,6 +1,6 @@
 /*
  * zpq_stream.h
- *     Streaiming compression for libpq
+ *     Streaming compression for libpq
  */
 
 #ifndef ZPQ_STREAM_H
diff --git a/src/interfaces/libpq/fe-connect.c b/src/interfaces/libpq/fe-connect.c
index eac6ef66cc..679f8cde9f 100644
--- a/src/interfaces/libpq/fe-connect.c
+++ b/src/interfaces/libpq/fe-connect.c
@@ -3269,7 +3269,7 @@ keep_going:						/* We will come back to here until there is
 						{
 							appendPQExpBuffer(&conn->errorMessage,
 											  libpq_gettext(
-												  "server is not supported requested compression algorithms %s\n"),
+												  "server does not support requested compression algorithms %s\n"),
 											  conn->compression);
 							goto error_return;
 						}
diff --git a/src/interfaces/libpq/fe-protocol3.c b/src/interfaces/libpq/fe-protocol3.c
index 095866bba0..5b879569b4 100644
--- a/src/interfaces/libpq/fe-protocol3.c
+++ b/src/interfaces/libpq/fe-protocol3.c
@@ -2135,15 +2135,15 @@ pqBuildStartupPacket3(PGconn *conn, int *packetlen,
 }
 
 /*
- * Build comma-separated list of compression algorithms suggested by client to the server.
- * It can be either explicitly specified by user in connection string, either
- * include all algorithms supported by clit library.
- * This functions returns true if compression string is successfully parsed and
- * stores comma-separated list of algorithms in *client_compressors.
- * If compression is disabled, then NULL is assigned to  *client_compressors.
- * Also it creates array of compressor descriptors, each element of which corresponds
- * the correspondent algorithm name in *client_compressors list. This array is stored in PGconn
- * and is used during handshake when compassion acknowledgment response is received from the server.
+ * Build comma-separated list of compression algorithms requested by client.
+ * It can be either explicitly specified by user in connection string, or
+ * include all algorithms supported by client library.
+ * This function returns true if the compression string is successfully parsed and
+ * stores a comma-separated list of algorithms in *client_compressors.
+ * If compression is disabled, then NULL is assigned to *client_compressors.
+ * Also it creates an array of compressor descriptors, each element of which corresponds to
+ * the corresponding algorithm name in *client_compressors list. This array is stored in PGconn
+ * and is used during handshake when a compression acknowledgment response is received from the server.
  */
 static bool
 build_compressors_list(PGconn *conn, char** client_compressors, bool build_descriptors)
@@ -2170,7 +2170,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 
 		if (n_supported_algorithms == 0)
 		{
-			*client_compressors = NULL; /* no compressors are avaialable */
+			*client_compressors = NULL; /* no compressors are available */
 			conn->compressors = NULL;
 			return true;
 		}
@@ -2204,7 +2204,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 	}
 	else
 	{
-		/* List of compresison algorithms separated by commas */
+		/* List of compression algorithms separated by commas */
 		char *src, *dst;
 		int n_suggested_algorithms = 0;
 		char* suggested_algorithms = strdup(value);
@@ -2232,7 +2232,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 				if (sscanf(col+1, "%d", &compression_level) != 1 && !build_descriptors)
 				{
 					fprintf(stderr,
-							libpq_gettext("WARNING: invlaid compression level %s in compression option '%s'\n"),
+							libpq_gettext("WARNING: invalid compression level %s in compression option '%s'\n"),
 							col+1, value);
 					return false;
 				}
@@ -2262,7 +2262,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 		{
 			if (!build_descriptors)
 				fprintf(stderr,
-						libpq_gettext("WARNING: none of specified algirthms %s is supported by client\n"),
+						libpq_gettext("WARNING: none of the specified algorithms are supported by client: %s\n"),
 						value);
 			else
 			{
-- 
2.17.0


--yudcn1FV7Hsu/q59--





^ permalink  raw  reply  [nested|flat] 22+ messages in thread

* [PATCH] fixes to docs and comments
@ 2021-01-09 15:49  Justin Pryzby <[email protected]>
  0 siblings, 0 replies; 22+ messages in thread

From: Justin Pryzby @ 2021-01-09 15:49 UTC (permalink / raw)

---
 doc/src/sgml/config.sgml            | 10 +++---
 doc/src/sgml/libpq.sgml             | 23 ++++++++----
 doc/src/sgml/protocol.sgml          | 54 +++++++++++++----------------
 src/backend/libpq/pqcomm.c          |  2 +-
 src/common/zpq_stream.c             | 16 ++++-----
 src/include/common/zpq_stream.h     |  2 +-
 src/interfaces/libpq/fe-connect.c   |  2 +-
 src/interfaces/libpq/fe-protocol3.c | 26 +++++++-------
 8 files changed, 69 insertions(+), 66 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 3b132dcf27..8b5a6525ac 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1004,12 +1004,10 @@ include_dir 'conf.d'
       </term>
       <listitem>
        <para>
-        When this parameter is <literal>on</literal> (default), the <productname>PostgreSQL</productname>
-        server can switch on compression of traffic between server and client if it is requested by client.
-        Client sends to the server list of compression algorithms supported by frontend library,
-        server chooses one which is supported by backend library and sends it in compression acknowledgement message
-        to the client. This option allows to reject compression request even if it is supported by server
-        (due to security, CPU consumption or whatever else reasons...).
+        This parameter enables compression of libpq traffic between client and server.
+        The default is <literal>on</literal>.
+        This option allows rejecting compression requests even if it is supported by server
+        (for example, due to security, or CPU consumption).
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 2934908520..d4da390ca9 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1244,13 +1244,22 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>compression</literal></term>
       <listitem>
       <para>
-        Request compression of libpq traffic. Client sends to the server list of compression algorithms, supported by client library.
-        If server supports one of this algorithms, then it acknowledges use of this algorithm and then all libpq messages send both from client to server and
-        visa versa will be compressed. If server is not supporting any of the suggested algorithms, then it rejects client request to use compression
-        and it is up to the client whether to continue work without compression or report error.
-        Supported compression algorithms are chosen at configure time. Right now two libraries are supported: zlib (default) and zstd (if Postgres was
-        configured with --with-zstd option). In both cases streaming mode is used.
-        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+        Request compression of libpq traffic. The client sends a request with a list of compression algorithms.
+        Compression can be requested by a client by including the "compression" option in its connection string.
+        This can either be a boolean value to enable or disable compression
+        ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto", or an explicit list of comma-separated compression algorithms
+        which can optionally include compression level ("zlib,zstd:5").
+        If compression is enabled but an algorithm is not explicitly specified, the client library sends its full list of
+        supported algorithms and the server chooses a preferred algorithm.
+
+        If the server accepts one of the algorithms, it replies with an acknowledgment and all future libpq messages between client and server
+        will be compressed.
+        If the server rejects the compression request, it is up to the client whether to continue without compression or to report an error.
+        Support for compression algorithms must be enabled when the server is compiled.
+        Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
+        configured with --with-zstd option). In both cases, streaming mode is used.
+        By default, compression is not requested by the client.
+        Please note that using compression together with SSL may expose extra vulnerabilities:
         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;
       </para>
       </listitem>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 9f30aad8bd..a69f9bfc26 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -94,10 +94,10 @@
 
   <para>
     It is possible to compress protocol data to reduce traffic and speed-up client-server interaction.
-    Compression is especially useful for importing/exporting data to/from database using COPY command
-    and for replication (both physical and logical). Also compression can reduce server response time
-    in case of queries returning large amount of data (for example returning JSON, BLOBs, text,...)
-    Right now two libraries are supported: zlib (default) and zstd (if Postgres was
+    Compression is especially useful for importing/exporting data to/from the database using the <literal>COPY</literal> command
+    and for replication (both physical and logical). Compression can also reduce the server's response time
+    for queries returning a large amount of data (for example, JSON, BLOBs, text, ...).
+    Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
     configured with --with-zstd option).
   </para>
 
@@ -275,19 +275,14 @@
       <term>CompressionAck</term>
       <listitem>
        <para>
-         Server acknowledges using compression for client-server communication protocol.
-         Compression can be requested by client by including "compression" option in connection string.
-         It can be just boolean values enabling or disabling compression
-         ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto" or explicit list of compression algorithms
-         separated by comma with optional specification of compression level: "zlib,zstd:5".
-         If compression algorithm is not explicitly specified the most efficient one supported both by
-         client and server is chosen. Client sends to the server list of compression algorithms,
-         supported by client library.
-         If server supports one of this algorithms, then it acknowledges use of this algorithm and
-         all subsequent libpq messages send both from client to server and
-         visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-         index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-         and it is up to the client whether to continue work without compression or report error.
+         The server accepts the client's compression request.
+         Compression is requested when a client connection includes the "compression" option, which includes
+         a list of requested compression algorithms.
+         If the server accepts one of these algorithms, it acknowledges use of compression and
+         all subsequent libpq messages between the client and server will be compressed.
+         The server chooses an algorithm from the list specified by client and responds with the index of the chosen algorithm from the client-supplied list.
+         If the server does not accept any of the requested algorithms, then it replies with an index of -1
+         and it is up to the client whether to continue without compression or to report an error.
        </para>
       </listitem>
      </varlistentry>
@@ -3460,12 +3455,14 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-  Acknowledge use of compression for protocol data. Client sends to the server list of compression algorithms, supported by client library.
-  If server supports one of this algorithms, then it acknowledges use of this algorithm and all subsequent libpq messages send both from client to server and
-  visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-  index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-  and it is up to the client whether to continue work without compression or report error.
-  After receiving this message with algorithm index other than -1, both server and client are switched to compression mode
+  Acknowledge use of compression for protocol data. The client sends to the server a list of requested compression algorithms.
+  If the server supports any of these algorithms, it acknowledges use of this algorithm and all subsequent libpq messages between client and server
+  will be compressed.
+  The server selects the preferred algorithm from the list specified by client and responds with the
+  index of the chosen algorithm in this list.
+  If the server does not support any of the requested algorithms, it replies with -1
+  and it is up to the client whether to continue without compression or to report an error.
+  After receiving this message with algorithm index other than -1, both server and client switch to compressed mode
   and exchange compressed messages.
 </para>
 </listitem>
@@ -3486,7 +3483,7 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-        Index of algorithm in the list of supported algotihms specified by client or -1 if none of them is supported.
+        Index of algorithm in the list of supported algorithms specified by client or -1 if none of them are supported.
 </para>
 </listitem>
 </varlistentry>
@@ -6069,12 +6066,11 @@ StartupMessage (F)
 </term>
 <listitem>
 <para>
-                        Request compression of libpq traffic. Value is list of compression algorithms supported by client with optional
+                        Request compression of libpq traffic. The value is a list of compression algorithms requested by the client with an optional
                         specification of compression level: <literal>"zlib,zstd:5"</literal>.
-                        When connecting to an older backend, which does not support compression, or in case when the backend support compression
-                        but for some reason wants to disable it, the backend will just ignore the _pq_.compression parameter and won’t send
-                        the compressionAck message to the frontend.
-                        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+                        If the server does not accept compression, the backend will ignore the _pq_.compression
+                        parameter and will not send the CompressionAck message to the frontend.
+                        By default, compression is disabled. Please note that using compression together with SSL may expose extra vulnerabilities:
                         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;.
 </para>
 </listitem>
diff --git a/src/backend/libpq/pqcomm.c b/src/backend/libpq/pqcomm.c
index 8be1ce18de..f3293faf01 100644
--- a/src/backend/libpq/pqcomm.c
+++ b/src/backend/libpq/pqcomm.c
@@ -1073,7 +1073,7 @@ pq_recvbuf(bool nowait)
 	/* Can fill buffer from PqRecvLength and upwards */
 	for (;;)
 	{
-		/* If streaming compression is enabled then use correspondent compression read function. */
+		/* If streaming compression is enabled then use corresponding compression read function. */
 		r = PqStream
 			? zpq_read(PqStream, PqRecvBuffer + PqRecvLength,
 					   PQ_RECV_BUFFER_SIZE - PqRecvLength)
diff --git a/src/common/zpq_stream.c b/src/common/zpq_stream.c
index 459566228a..e044e83e7c 100644
--- a/src/common/zpq_stream.c
+++ b/src/common/zpq_stream.c
@@ -9,15 +9,15 @@
 typedef struct
 {
 	/*
-	 * Returns name of compression algorithm.
+	 * Name of compression algorithm.
 	 */
 	char const* (*name)(void);
 
 	/*
-	 * Create compression stream with using rx/tx function for fetching/sending compressed data.
+	 * Create compression stream with rx/tx function for reading/sending compressed data.
 	 * level: compression level
 	 * tx_func: function for writing compressed data in underlying stream
-	 * rx_func: function for receiving compressed data from underlying stream
+	 * rx_func: function for reading compressed data from underlying stream
 	 * arg: context passed to the function
      * rx_data: received data (compressed data already fetched from input stream)
 	 * rx_data_size: size of data fetched from input stream
@@ -27,14 +27,14 @@ typedef struct
 	/*
 	 * Read up to "size" raw (decompressed) bytes.
 	 * Returns number of decompressed bytes or error code.
-	 * Error code is either ZPQ_DECOMPRESS_ERROR either error code returned by the rx function.
+	 * Error code is either ZPQ_DECOMPRESS_ERROR or error code returned by the rx function.
 	 */
 	ssize_t (*read)(ZpqStream *zs, void *buf, size_t size);
 
 	/*
 	 * Write up to "size" raw (decompressed) bytes.
 	 * Returns number of written raw bytes or error code returned by tx function.
-	 * In the last case amount of written raw bytes is stored in *processed.
+	 * In the last case number of bytes written is stored in *processed.
 	 */
 	ssize_t (*write)(ZpqStream *zs, void const *buf, size_t size, size_t *processed);
 
@@ -49,12 +49,12 @@ typedef struct
 	char const* (*error)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal tx decompression buffer.
+	 * Return amount of data in internal tx decompression buffer.
 	 */
 	size_t  (*buffered_tx)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal rx compression buffer.
+	 * Return amount of data in internal rx compression buffer.
 	 */
 	size_t  (*buffered_rx)(ZpqStream *zs);
 } ZpqAlgorithm;
@@ -265,7 +265,7 @@ zstd_name(void)
 
 #define ZLIB_BUFFER_SIZE       8192 /* We have to flush stream after each protocol command
 									 * and command is mostly limited by record length,
-									 * which in turn usually less than page size (except TOAST)
+									 * which in turn is usually less than page size (except TOAST)
 									 */
 
 typedef struct ZlibStream
diff --git a/src/include/common/zpq_stream.h b/src/include/common/zpq_stream.h
index 27aef0aab9..991e2c0165 100644
--- a/src/include/common/zpq_stream.h
+++ b/src/include/common/zpq_stream.h
@@ -1,6 +1,6 @@
 /*
  * zpq_stream.h
- *     Streaiming compression for libpq
+ *     Streaming compression for libpq
  */
 
 #ifndef ZPQ_STREAM_H
diff --git a/src/interfaces/libpq/fe-connect.c b/src/interfaces/libpq/fe-connect.c
index eac6ef66cc..679f8cde9f 100644
--- a/src/interfaces/libpq/fe-connect.c
+++ b/src/interfaces/libpq/fe-connect.c
@@ -3269,7 +3269,7 @@ keep_going:						/* We will come back to here until there is
 						{
 							appendPQExpBuffer(&conn->errorMessage,
 											  libpq_gettext(
-												  "server is not supported requested compression algorithms %s\n"),
+												  "server does not support requested compression algorithms %s\n"),
 											  conn->compression);
 							goto error_return;
 						}
diff --git a/src/interfaces/libpq/fe-protocol3.c b/src/interfaces/libpq/fe-protocol3.c
index 095866bba0..5b879569b4 100644
--- a/src/interfaces/libpq/fe-protocol3.c
+++ b/src/interfaces/libpq/fe-protocol3.c
@@ -2135,15 +2135,15 @@ pqBuildStartupPacket3(PGconn *conn, int *packetlen,
 }
 
 /*
- * Build comma-separated list of compression algorithms suggested by client to the server.
- * It can be either explicitly specified by user in connection string, either
- * include all algorithms supported by clit library.
- * This functions returns true if compression string is successfully parsed and
- * stores comma-separated list of algorithms in *client_compressors.
- * If compression is disabled, then NULL is assigned to  *client_compressors.
- * Also it creates array of compressor descriptors, each element of which corresponds
- * the correspondent algorithm name in *client_compressors list. This array is stored in PGconn
- * and is used during handshake when compassion acknowledgment response is received from the server.
+ * Build comma-separated list of compression algorithms requested by client.
+ * It can be either explicitly specified by user in connection string, or
+ * include all algorithms supported by client library.
+ * This function returns true if the compression string is successfully parsed and
+ * stores a comma-separated list of algorithms in *client_compressors.
+ * If compression is disabled, then NULL is assigned to *client_compressors.
+ * Also it creates an array of compressor descriptors, each element of which corresponds to
+ * the corresponding algorithm name in *client_compressors list. This array is stored in PGconn
+ * and is used during handshake when a compression acknowledgment response is received from the server.
  */
 static bool
 build_compressors_list(PGconn *conn, char** client_compressors, bool build_descriptors)
@@ -2170,7 +2170,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 
 		if (n_supported_algorithms == 0)
 		{
-			*client_compressors = NULL; /* no compressors are avaialable */
+			*client_compressors = NULL; /* no compressors are available */
 			conn->compressors = NULL;
 			return true;
 		}
@@ -2204,7 +2204,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 	}
 	else
 	{
-		/* List of compresison algorithms separated by commas */
+		/* List of compression algorithms separated by commas */
 		char *src, *dst;
 		int n_suggested_algorithms = 0;
 		char* suggested_algorithms = strdup(value);
@@ -2232,7 +2232,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 				if (sscanf(col+1, "%d", &compression_level) != 1 && !build_descriptors)
 				{
 					fprintf(stderr,
-							libpq_gettext("WARNING: invlaid compression level %s in compression option '%s'\n"),
+							libpq_gettext("WARNING: invalid compression level %s in compression option '%s'\n"),
 							col+1, value);
 					return false;
 				}
@@ -2262,7 +2262,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 		{
 			if (!build_descriptors)
 				fprintf(stderr,
-						libpq_gettext("WARNING: none of specified algirthms %s is supported by client\n"),
+						libpq_gettext("WARNING: none of the specified algorithms are supported by client: %s\n"),
 						value);
 			else
 			{
-- 
2.17.0


--yudcn1FV7Hsu/q59--





^ permalink  raw  reply  [nested|flat] 22+ messages in thread

* [PATCH] fixes to docs and comments
@ 2021-01-09 15:49  Justin Pryzby <[email protected]>
  0 siblings, 0 replies; 22+ messages in thread

From: Justin Pryzby @ 2021-01-09 15:49 UTC (permalink / raw)

---
 doc/src/sgml/config.sgml            | 10 +++---
 doc/src/sgml/libpq.sgml             | 23 ++++++++----
 doc/src/sgml/protocol.sgml          | 54 +++++++++++++----------------
 src/backend/libpq/pqcomm.c          |  2 +-
 src/common/zpq_stream.c             | 16 ++++-----
 src/include/common/zpq_stream.h     |  2 +-
 src/interfaces/libpq/fe-connect.c   |  2 +-
 src/interfaces/libpq/fe-protocol3.c | 26 +++++++-------
 8 files changed, 69 insertions(+), 66 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 3b132dcf27..8b5a6525ac 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1004,12 +1004,10 @@ include_dir 'conf.d'
       </term>
       <listitem>
        <para>
-        When this parameter is <literal>on</literal> (default), the <productname>PostgreSQL</productname>
-        server can switch on compression of traffic between server and client if it is requested by client.
-        Client sends to the server list of compression algorithms supported by frontend library,
-        server chooses one which is supported by backend library and sends it in compression acknowledgement message
-        to the client. This option allows to reject compression request even if it is supported by server
-        (due to security, CPU consumption or whatever else reasons...).
+        This parameter enables compression of libpq traffic between client and server.
+        The default is <literal>on</literal>.
+        This option allows rejecting compression requests even if it is supported by server
+        (for example, due to security, or CPU consumption).
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 2934908520..d4da390ca9 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1244,13 +1244,22 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>compression</literal></term>
       <listitem>
       <para>
-        Request compression of libpq traffic. Client sends to the server list of compression algorithms, supported by client library.
-        If server supports one of this algorithms, then it acknowledges use of this algorithm and then all libpq messages send both from client to server and
-        visa versa will be compressed. If server is not supporting any of the suggested algorithms, then it rejects client request to use compression
-        and it is up to the client whether to continue work without compression or report error.
-        Supported compression algorithms are chosen at configure time. Right now two libraries are supported: zlib (default) and zstd (if Postgres was
-        configured with --with-zstd option). In both cases streaming mode is used.
-        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+        Request compression of libpq traffic. The client sends a request with a list of compression algorithms.
+        Compression can be requested by a client by including the "compression" option in its connection string.
+        This can either be a boolean value to enable or disable compression
+        ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto", or an explicit list of comma-separated compression algorithms
+        which can optionally include compression level ("zlib,zstd:5").
+        If compression is enabled but an algorithm is not explicitly specified, the client library sends its full list of
+        supported algorithms and the server chooses a preferred algorithm.
+
+        If the server accepts one of the algorithms, it replies with an acknowledgment and all future libpq messages between client and server
+        will be compressed.
+        If the server rejects the compression request, it is up to the client whether to continue without compression or to report an error.
+        Support for compression algorithms must be enabled when the server is compiled.
+        Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
+        configured with --with-zstd option). In both cases, streaming mode is used.
+        By default, compression is not requested by the client.
+        Please note that using compression together with SSL may expose extra vulnerabilities:
         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;
       </para>
       </listitem>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 9f30aad8bd..a69f9bfc26 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -94,10 +94,10 @@
 
   <para>
     It is possible to compress protocol data to reduce traffic and speed-up client-server interaction.
-    Compression is especially useful for importing/exporting data to/from database using COPY command
-    and for replication (both physical and logical). Also compression can reduce server response time
-    in case of queries returning large amount of data (for example returning JSON, BLOBs, text,...)
-    Right now two libraries are supported: zlib (default) and zstd (if Postgres was
+    Compression is especially useful for importing/exporting data to/from the database using the <literal>COPY</literal> command
+    and for replication (both physical and logical). Compression can also reduce the server's response time
+    for queries returning a large amount of data (for example, JSON, BLOBs, text, ...).
+    Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
     configured with --with-zstd option).
   </para>
 
@@ -275,19 +275,14 @@
       <term>CompressionAck</term>
       <listitem>
        <para>
-         Server acknowledges using compression for client-server communication protocol.
-         Compression can be requested by client by including "compression" option in connection string.
-         It can be just boolean values enabling or disabling compression
-         ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto" or explicit list of compression algorithms
-         separated by comma with optional specification of compression level: "zlib,zstd:5".
-         If compression algorithm is not explicitly specified the most efficient one supported both by
-         client and server is chosen. Client sends to the server list of compression algorithms,
-         supported by client library.
-         If server supports one of this algorithms, then it acknowledges use of this algorithm and
-         all subsequent libpq messages send both from client to server and
-         visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-         index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-         and it is up to the client whether to continue work without compression or report error.
+         The server accepts the client's compression request.
+         Compression is requested when a client connection includes the "compression" option, which includes
+         a list of requested compression algorithms.
+         If the server accepts one of these algorithms, it acknowledges use of compression and
+         all subsequent libpq messages between the client and server will be compressed.
+         The server chooses an algorithm from the list specified by client and responds with the index of the chosen algorithm from the client-supplied list.
+         If the server does not accept any of the requested algorithms, then it replies with an index of -1
+         and it is up to the client whether to continue without compression or to report an error.
        </para>
       </listitem>
      </varlistentry>
@@ -3460,12 +3455,14 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-  Acknowledge use of compression for protocol data. Client sends to the server list of compression algorithms, supported by client library.
-  If server supports one of this algorithms, then it acknowledges use of this algorithm and all subsequent libpq messages send both from client to server and
-  visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-  index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-  and it is up to the client whether to continue work without compression or report error.
-  After receiving this message with algorithm index other than -1, both server and client are switched to compression mode
+  Acknowledge use of compression for protocol data. The client sends to the server a list of requested compression algorithms.
+  If the server supports any of these algorithms, it acknowledges use of this algorithm and all subsequent libpq messages between client and server
+  will be compressed.
+  The server selects the preferred algorithm from the list specified by client and responds with the
+  index of the chosen algorithm in this list.
+  If the server does not support any of the requested algorithms, it replies with -1
+  and it is up to the client whether to continue without compression or to report an error.
+  After receiving this message with algorithm index other than -1, both server and client switch to compressed mode
   and exchange compressed messages.
 </para>
 </listitem>
@@ -3486,7 +3483,7 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-        Index of algorithm in the list of supported algotihms specified by client or -1 if none of them is supported.
+        Index of algorithm in the list of supported algorithms specified by client or -1 if none of them are supported.
 </para>
 </listitem>
 </varlistentry>
@@ -6069,12 +6066,11 @@ StartupMessage (F)
 </term>
 <listitem>
 <para>
-                        Request compression of libpq traffic. Value is list of compression algorithms supported by client with optional
+                        Request compression of libpq traffic. The value is a list of compression algorithms requested by the client with an optional
                         specification of compression level: <literal>"zlib,zstd:5"</literal>.
-                        When connecting to an older backend, which does not support compression, or in case when the backend support compression
-                        but for some reason wants to disable it, the backend will just ignore the _pq_.compression parameter and won’t send
-                        the compressionAck message to the frontend.
-                        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+                        If the server does not accept compression, the backend will ignore the _pq_.compression
+                        parameter and will not send the CompressionAck message to the frontend.
+                        By default, compression is disabled. Please note that using compression together with SSL may expose extra vulnerabilities:
                         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;.
 </para>
 </listitem>
diff --git a/src/backend/libpq/pqcomm.c b/src/backend/libpq/pqcomm.c
index 8be1ce18de..f3293faf01 100644
--- a/src/backend/libpq/pqcomm.c
+++ b/src/backend/libpq/pqcomm.c
@@ -1073,7 +1073,7 @@ pq_recvbuf(bool nowait)
 	/* Can fill buffer from PqRecvLength and upwards */
 	for (;;)
 	{
-		/* If streaming compression is enabled then use correspondent compression read function. */
+		/* If streaming compression is enabled then use corresponding compression read function. */
 		r = PqStream
 			? zpq_read(PqStream, PqRecvBuffer + PqRecvLength,
 					   PQ_RECV_BUFFER_SIZE - PqRecvLength)
diff --git a/src/common/zpq_stream.c b/src/common/zpq_stream.c
index 459566228a..e044e83e7c 100644
--- a/src/common/zpq_stream.c
+++ b/src/common/zpq_stream.c
@@ -9,15 +9,15 @@
 typedef struct
 {
 	/*
-	 * Returns name of compression algorithm.
+	 * Name of compression algorithm.
 	 */
 	char const* (*name)(void);
 
 	/*
-	 * Create compression stream with using rx/tx function for fetching/sending compressed data.
+	 * Create compression stream with rx/tx function for reading/sending compressed data.
 	 * level: compression level
 	 * tx_func: function for writing compressed data in underlying stream
-	 * rx_func: function for receiving compressed data from underlying stream
+	 * rx_func: function for reading compressed data from underlying stream
 	 * arg: context passed to the function
      * rx_data: received data (compressed data already fetched from input stream)
 	 * rx_data_size: size of data fetched from input stream
@@ -27,14 +27,14 @@ typedef struct
 	/*
 	 * Read up to "size" raw (decompressed) bytes.
 	 * Returns number of decompressed bytes or error code.
-	 * Error code is either ZPQ_DECOMPRESS_ERROR either error code returned by the rx function.
+	 * Error code is either ZPQ_DECOMPRESS_ERROR or error code returned by the rx function.
 	 */
 	ssize_t (*read)(ZpqStream *zs, void *buf, size_t size);
 
 	/*
 	 * Write up to "size" raw (decompressed) bytes.
 	 * Returns number of written raw bytes or error code returned by tx function.
-	 * In the last case amount of written raw bytes is stored in *processed.
+	 * In the last case number of bytes written is stored in *processed.
 	 */
 	ssize_t (*write)(ZpqStream *zs, void const *buf, size_t size, size_t *processed);
 
@@ -49,12 +49,12 @@ typedef struct
 	char const* (*error)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal tx decompression buffer.
+	 * Return amount of data in internal tx decompression buffer.
 	 */
 	size_t  (*buffered_tx)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal rx compression buffer.
+	 * Return amount of data in internal rx compression buffer.
 	 */
 	size_t  (*buffered_rx)(ZpqStream *zs);
 } ZpqAlgorithm;
@@ -265,7 +265,7 @@ zstd_name(void)
 
 #define ZLIB_BUFFER_SIZE       8192 /* We have to flush stream after each protocol command
 									 * and command is mostly limited by record length,
-									 * which in turn usually less than page size (except TOAST)
+									 * which in turn is usually less than page size (except TOAST)
 									 */
 
 typedef struct ZlibStream
diff --git a/src/include/common/zpq_stream.h b/src/include/common/zpq_stream.h
index 27aef0aab9..991e2c0165 100644
--- a/src/include/common/zpq_stream.h
+++ b/src/include/common/zpq_stream.h
@@ -1,6 +1,6 @@
 /*
  * zpq_stream.h
- *     Streaiming compression for libpq
+ *     Streaming compression for libpq
  */
 
 #ifndef ZPQ_STREAM_H
diff --git a/src/interfaces/libpq/fe-connect.c b/src/interfaces/libpq/fe-connect.c
index eac6ef66cc..679f8cde9f 100644
--- a/src/interfaces/libpq/fe-connect.c
+++ b/src/interfaces/libpq/fe-connect.c
@@ -3269,7 +3269,7 @@ keep_going:						/* We will come back to here until there is
 						{
 							appendPQExpBuffer(&conn->errorMessage,
 											  libpq_gettext(
-												  "server is not supported requested compression algorithms %s\n"),
+												  "server does not support requested compression algorithms %s\n"),
 											  conn->compression);
 							goto error_return;
 						}
diff --git a/src/interfaces/libpq/fe-protocol3.c b/src/interfaces/libpq/fe-protocol3.c
index 095866bba0..5b879569b4 100644
--- a/src/interfaces/libpq/fe-protocol3.c
+++ b/src/interfaces/libpq/fe-protocol3.c
@@ -2135,15 +2135,15 @@ pqBuildStartupPacket3(PGconn *conn, int *packetlen,
 }
 
 /*
- * Build comma-separated list of compression algorithms suggested by client to the server.
- * It can be either explicitly specified by user in connection string, either
- * include all algorithms supported by clit library.
- * This functions returns true if compression string is successfully parsed and
- * stores comma-separated list of algorithms in *client_compressors.
- * If compression is disabled, then NULL is assigned to  *client_compressors.
- * Also it creates array of compressor descriptors, each element of which corresponds
- * the correspondent algorithm name in *client_compressors list. This array is stored in PGconn
- * and is used during handshake when compassion acknowledgment response is received from the server.
+ * Build comma-separated list of compression algorithms requested by client.
+ * It can be either explicitly specified by user in connection string, or
+ * include all algorithms supported by client library.
+ * This function returns true if the compression string is successfully parsed and
+ * stores a comma-separated list of algorithms in *client_compressors.
+ * If compression is disabled, then NULL is assigned to *client_compressors.
+ * Also it creates an array of compressor descriptors, each element of which corresponds to
+ * the corresponding algorithm name in *client_compressors list. This array is stored in PGconn
+ * and is used during handshake when a compression acknowledgment response is received from the server.
  */
 static bool
 build_compressors_list(PGconn *conn, char** client_compressors, bool build_descriptors)
@@ -2170,7 +2170,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 
 		if (n_supported_algorithms == 0)
 		{
-			*client_compressors = NULL; /* no compressors are avaialable */
+			*client_compressors = NULL; /* no compressors are available */
 			conn->compressors = NULL;
 			return true;
 		}
@@ -2204,7 +2204,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 	}
 	else
 	{
-		/* List of compresison algorithms separated by commas */
+		/* List of compression algorithms separated by commas */
 		char *src, *dst;
 		int n_suggested_algorithms = 0;
 		char* suggested_algorithms = strdup(value);
@@ -2232,7 +2232,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 				if (sscanf(col+1, "%d", &compression_level) != 1 && !build_descriptors)
 				{
 					fprintf(stderr,
-							libpq_gettext("WARNING: invlaid compression level %s in compression option '%s'\n"),
+							libpq_gettext("WARNING: invalid compression level %s in compression option '%s'\n"),
 							col+1, value);
 					return false;
 				}
@@ -2262,7 +2262,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 		{
 			if (!build_descriptors)
 				fprintf(stderr,
-						libpq_gettext("WARNING: none of specified algirthms %s is supported by client\n"),
+						libpq_gettext("WARNING: none of the specified algorithms are supported by client: %s\n"),
 						value);
 			else
 			{
-- 
2.17.0


--yudcn1FV7Hsu/q59--





^ permalink  raw  reply  [nested|flat] 22+ messages in thread

* [PATCH] fixes to docs and comments
@ 2021-01-09 15:49  Justin Pryzby <[email protected]>
  0 siblings, 0 replies; 22+ messages in thread

From: Justin Pryzby @ 2021-01-09 15:49 UTC (permalink / raw)

---
 doc/src/sgml/config.sgml            | 10 +++---
 doc/src/sgml/libpq.sgml             | 23 ++++++++----
 doc/src/sgml/protocol.sgml          | 54 +++++++++++++----------------
 src/backend/libpq/pqcomm.c          |  2 +-
 src/common/zpq_stream.c             | 16 ++++-----
 src/include/common/zpq_stream.h     |  2 +-
 src/interfaces/libpq/fe-connect.c   |  2 +-
 src/interfaces/libpq/fe-protocol3.c | 26 +++++++-------
 8 files changed, 69 insertions(+), 66 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 3b132dcf27..8b5a6525ac 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1004,12 +1004,10 @@ include_dir 'conf.d'
       </term>
       <listitem>
        <para>
-        When this parameter is <literal>on</literal> (default), the <productname>PostgreSQL</productname>
-        server can switch on compression of traffic between server and client if it is requested by client.
-        Client sends to the server list of compression algorithms supported by frontend library,
-        server chooses one which is supported by backend library and sends it in compression acknowledgement message
-        to the client. This option allows to reject compression request even if it is supported by server
-        (due to security, CPU consumption or whatever else reasons...).
+        This parameter enables compression of libpq traffic between client and server.
+        The default is <literal>on</literal>.
+        This option allows rejecting compression requests even if it is supported by server
+        (for example, due to security, or CPU consumption).
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 2934908520..d4da390ca9 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1244,13 +1244,22 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>compression</literal></term>
       <listitem>
       <para>
-        Request compression of libpq traffic. Client sends to the server list of compression algorithms, supported by client library.
-        If server supports one of this algorithms, then it acknowledges use of this algorithm and then all libpq messages send both from client to server and
-        visa versa will be compressed. If server is not supporting any of the suggested algorithms, then it rejects client request to use compression
-        and it is up to the client whether to continue work without compression or report error.
-        Supported compression algorithms are chosen at configure time. Right now two libraries are supported: zlib (default) and zstd (if Postgres was
-        configured with --with-zstd option). In both cases streaming mode is used.
-        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+        Request compression of libpq traffic. The client sends a request with a list of compression algorithms.
+        Compression can be requested by a client by including the "compression" option in its connection string.
+        This can either be a boolean value to enable or disable compression
+        ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto", or an explicit list of comma-separated compression algorithms
+        which can optionally include compression level ("zlib,zstd:5").
+        If compression is enabled but an algorithm is not explicitly specified, the client library sends its full list of
+        supported algorithms and the server chooses a preferred algorithm.
+
+        If the server accepts one of the algorithms, it replies with an acknowledgment and all future libpq messages between client and server
+        will be compressed.
+        If the server rejects the compression request, it is up to the client whether to continue without compression or to report an error.
+        Support for compression algorithms must be enabled when the server is compiled.
+        Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
+        configured with --with-zstd option). In both cases, streaming mode is used.
+        By default, compression is not requested by the client.
+        Please note that using compression together with SSL may expose extra vulnerabilities:
         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;
       </para>
       </listitem>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 9f30aad8bd..a69f9bfc26 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -94,10 +94,10 @@
 
   <para>
     It is possible to compress protocol data to reduce traffic and speed-up client-server interaction.
-    Compression is especially useful for importing/exporting data to/from database using COPY command
-    and for replication (both physical and logical). Also compression can reduce server response time
-    in case of queries returning large amount of data (for example returning JSON, BLOBs, text,...)
-    Right now two libraries are supported: zlib (default) and zstd (if Postgres was
+    Compression is especially useful for importing/exporting data to/from the database using the <literal>COPY</literal> command
+    and for replication (both physical and logical). Compression can also reduce the server's response time
+    for queries returning a large amount of data (for example, JSON, BLOBs, text, ...).
+    Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
     configured with --with-zstd option).
   </para>
 
@@ -275,19 +275,14 @@
       <term>CompressionAck</term>
       <listitem>
        <para>
-         Server acknowledges using compression for client-server communication protocol.
-         Compression can be requested by client by including "compression" option in connection string.
-         It can be just boolean values enabling or disabling compression
-         ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto" or explicit list of compression algorithms
-         separated by comma with optional specification of compression level: "zlib,zstd:5".
-         If compression algorithm is not explicitly specified the most efficient one supported both by
-         client and server is chosen. Client sends to the server list of compression algorithms,
-         supported by client library.
-         If server supports one of this algorithms, then it acknowledges use of this algorithm and
-         all subsequent libpq messages send both from client to server and
-         visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-         index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-         and it is up to the client whether to continue work without compression or report error.
+         The server accepts the client's compression request.
+         Compression is requested when a client connection includes the "compression" option, which includes
+         a list of requested compression algorithms.
+         If the server accepts one of these algorithms, it acknowledges use of compression and
+         all subsequent libpq messages between the client and server will be compressed.
+         The server chooses an algorithm from the list specified by client and responds with the index of the chosen algorithm from the client-supplied list.
+         If the server does not accept any of the requested algorithms, then it replies with an index of -1
+         and it is up to the client whether to continue without compression or to report an error.
        </para>
       </listitem>
      </varlistentry>
@@ -3460,12 +3455,14 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-  Acknowledge use of compression for protocol data. Client sends to the server list of compression algorithms, supported by client library.
-  If server supports one of this algorithms, then it acknowledges use of this algorithm and all subsequent libpq messages send both from client to server and
-  visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-  index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-  and it is up to the client whether to continue work without compression or report error.
-  After receiving this message with algorithm index other than -1, both server and client are switched to compression mode
+  Acknowledge use of compression for protocol data. The client sends to the server a list of requested compression algorithms.
+  If the server supports any of these algorithms, it acknowledges use of this algorithm and all subsequent libpq messages between client and server
+  will be compressed.
+  The server selects the preferred algorithm from the list specified by client and responds with the
+  index of the chosen algorithm in this list.
+  If the server does not support any of the requested algorithms, it replies with -1
+  and it is up to the client whether to continue without compression or to report an error.
+  After receiving this message with algorithm index other than -1, both server and client switch to compressed mode
   and exchange compressed messages.
 </para>
 </listitem>
@@ -3486,7 +3483,7 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-        Index of algorithm in the list of supported algotihms specified by client or -1 if none of them is supported.
+        Index of algorithm in the list of supported algorithms specified by client or -1 if none of them are supported.
 </para>
 </listitem>
 </varlistentry>
@@ -6069,12 +6066,11 @@ StartupMessage (F)
 </term>
 <listitem>
 <para>
-                        Request compression of libpq traffic. Value is list of compression algorithms supported by client with optional
+                        Request compression of libpq traffic. The value is a list of compression algorithms requested by the client with an optional
                         specification of compression level: <literal>"zlib,zstd:5"</literal>.
-                        When connecting to an older backend, which does not support compression, or in case when the backend support compression
-                        but for some reason wants to disable it, the backend will just ignore the _pq_.compression parameter and won’t send
-                        the compressionAck message to the frontend.
-                        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+                        If the server does not accept compression, the backend will ignore the _pq_.compression
+                        parameter and will not send the CompressionAck message to the frontend.
+                        By default, compression is disabled. Please note that using compression together with SSL may expose extra vulnerabilities:
                         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;.
 </para>
 </listitem>
diff --git a/src/backend/libpq/pqcomm.c b/src/backend/libpq/pqcomm.c
index 8be1ce18de..f3293faf01 100644
--- a/src/backend/libpq/pqcomm.c
+++ b/src/backend/libpq/pqcomm.c
@@ -1073,7 +1073,7 @@ pq_recvbuf(bool nowait)
 	/* Can fill buffer from PqRecvLength and upwards */
 	for (;;)
 	{
-		/* If streaming compression is enabled then use correspondent compression read function. */
+		/* If streaming compression is enabled then use corresponding compression read function. */
 		r = PqStream
 			? zpq_read(PqStream, PqRecvBuffer + PqRecvLength,
 					   PQ_RECV_BUFFER_SIZE - PqRecvLength)
diff --git a/src/common/zpq_stream.c b/src/common/zpq_stream.c
index 459566228a..e044e83e7c 100644
--- a/src/common/zpq_stream.c
+++ b/src/common/zpq_stream.c
@@ -9,15 +9,15 @@
 typedef struct
 {
 	/*
-	 * Returns name of compression algorithm.
+	 * Name of compression algorithm.
 	 */
 	char const* (*name)(void);
 
 	/*
-	 * Create compression stream with using rx/tx function for fetching/sending compressed data.
+	 * Create compression stream with rx/tx function for reading/sending compressed data.
 	 * level: compression level
 	 * tx_func: function for writing compressed data in underlying stream
-	 * rx_func: function for receiving compressed data from underlying stream
+	 * rx_func: function for reading compressed data from underlying stream
 	 * arg: context passed to the function
      * rx_data: received data (compressed data already fetched from input stream)
 	 * rx_data_size: size of data fetched from input stream
@@ -27,14 +27,14 @@ typedef struct
 	/*
 	 * Read up to "size" raw (decompressed) bytes.
 	 * Returns number of decompressed bytes or error code.
-	 * Error code is either ZPQ_DECOMPRESS_ERROR either error code returned by the rx function.
+	 * Error code is either ZPQ_DECOMPRESS_ERROR or error code returned by the rx function.
 	 */
 	ssize_t (*read)(ZpqStream *zs, void *buf, size_t size);
 
 	/*
 	 * Write up to "size" raw (decompressed) bytes.
 	 * Returns number of written raw bytes or error code returned by tx function.
-	 * In the last case amount of written raw bytes is stored in *processed.
+	 * In the last case number of bytes written is stored in *processed.
 	 */
 	ssize_t (*write)(ZpqStream *zs, void const *buf, size_t size, size_t *processed);
 
@@ -49,12 +49,12 @@ typedef struct
 	char const* (*error)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal tx decompression buffer.
+	 * Return amount of data in internal tx decompression buffer.
 	 */
 	size_t  (*buffered_tx)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal rx compression buffer.
+	 * Return amount of data in internal rx compression buffer.
 	 */
 	size_t  (*buffered_rx)(ZpqStream *zs);
 } ZpqAlgorithm;
@@ -265,7 +265,7 @@ zstd_name(void)
 
 #define ZLIB_BUFFER_SIZE       8192 /* We have to flush stream after each protocol command
 									 * and command is mostly limited by record length,
-									 * which in turn usually less than page size (except TOAST)
+									 * which in turn is usually less than page size (except TOAST)
 									 */
 
 typedef struct ZlibStream
diff --git a/src/include/common/zpq_stream.h b/src/include/common/zpq_stream.h
index 27aef0aab9..991e2c0165 100644
--- a/src/include/common/zpq_stream.h
+++ b/src/include/common/zpq_stream.h
@@ -1,6 +1,6 @@
 /*
  * zpq_stream.h
- *     Streaiming compression for libpq
+ *     Streaming compression for libpq
  */
 
 #ifndef ZPQ_STREAM_H
diff --git a/src/interfaces/libpq/fe-connect.c b/src/interfaces/libpq/fe-connect.c
index eac6ef66cc..679f8cde9f 100644
--- a/src/interfaces/libpq/fe-connect.c
+++ b/src/interfaces/libpq/fe-connect.c
@@ -3269,7 +3269,7 @@ keep_going:						/* We will come back to here until there is
 						{
 							appendPQExpBuffer(&conn->errorMessage,
 											  libpq_gettext(
-												  "server is not supported requested compression algorithms %s\n"),
+												  "server does not support requested compression algorithms %s\n"),
 											  conn->compression);
 							goto error_return;
 						}
diff --git a/src/interfaces/libpq/fe-protocol3.c b/src/interfaces/libpq/fe-protocol3.c
index 095866bba0..5b879569b4 100644
--- a/src/interfaces/libpq/fe-protocol3.c
+++ b/src/interfaces/libpq/fe-protocol3.c
@@ -2135,15 +2135,15 @@ pqBuildStartupPacket3(PGconn *conn, int *packetlen,
 }
 
 /*
- * Build comma-separated list of compression algorithms suggested by client to the server.
- * It can be either explicitly specified by user in connection string, either
- * include all algorithms supported by clit library.
- * This functions returns true if compression string is successfully parsed and
- * stores comma-separated list of algorithms in *client_compressors.
- * If compression is disabled, then NULL is assigned to  *client_compressors.
- * Also it creates array of compressor descriptors, each element of which corresponds
- * the correspondent algorithm name in *client_compressors list. This array is stored in PGconn
- * and is used during handshake when compassion acknowledgment response is received from the server.
+ * Build comma-separated list of compression algorithms requested by client.
+ * It can be either explicitly specified by user in connection string, or
+ * include all algorithms supported by client library.
+ * This function returns true if the compression string is successfully parsed and
+ * stores a comma-separated list of algorithms in *client_compressors.
+ * If compression is disabled, then NULL is assigned to *client_compressors.
+ * Also it creates an array of compressor descriptors, each element of which corresponds to
+ * the corresponding algorithm name in *client_compressors list. This array is stored in PGconn
+ * and is used during handshake when a compression acknowledgment response is received from the server.
  */
 static bool
 build_compressors_list(PGconn *conn, char** client_compressors, bool build_descriptors)
@@ -2170,7 +2170,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 
 		if (n_supported_algorithms == 0)
 		{
-			*client_compressors = NULL; /* no compressors are avaialable */
+			*client_compressors = NULL; /* no compressors are available */
 			conn->compressors = NULL;
 			return true;
 		}
@@ -2204,7 +2204,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 	}
 	else
 	{
-		/* List of compresison algorithms separated by commas */
+		/* List of compression algorithms separated by commas */
 		char *src, *dst;
 		int n_suggested_algorithms = 0;
 		char* suggested_algorithms = strdup(value);
@@ -2232,7 +2232,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 				if (sscanf(col+1, "%d", &compression_level) != 1 && !build_descriptors)
 				{
 					fprintf(stderr,
-							libpq_gettext("WARNING: invlaid compression level %s in compression option '%s'\n"),
+							libpq_gettext("WARNING: invalid compression level %s in compression option '%s'\n"),
 							col+1, value);
 					return false;
 				}
@@ -2262,7 +2262,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 		{
 			if (!build_descriptors)
 				fprintf(stderr,
-						libpq_gettext("WARNING: none of specified algirthms %s is supported by client\n"),
+						libpq_gettext("WARNING: none of the specified algorithms are supported by client: %s\n"),
 						value);
 			else
 			{
-- 
2.17.0


--yudcn1FV7Hsu/q59--





^ permalink  raw  reply  [nested|flat] 22+ messages in thread

* [PATCH] fixes to docs and comments
@ 2021-01-09 15:49  Justin Pryzby <[email protected]>
  0 siblings, 0 replies; 22+ messages in thread

From: Justin Pryzby @ 2021-01-09 15:49 UTC (permalink / raw)

---
 doc/src/sgml/config.sgml            | 10 +++---
 doc/src/sgml/libpq.sgml             | 23 ++++++++----
 doc/src/sgml/protocol.sgml          | 54 +++++++++++++----------------
 src/backend/libpq/pqcomm.c          |  2 +-
 src/common/zpq_stream.c             | 16 ++++-----
 src/include/common/zpq_stream.h     |  2 +-
 src/interfaces/libpq/fe-connect.c   |  2 +-
 src/interfaces/libpq/fe-protocol3.c | 26 +++++++-------
 8 files changed, 69 insertions(+), 66 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 3b132dcf27..8b5a6525ac 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1004,12 +1004,10 @@ include_dir 'conf.d'
       </term>
       <listitem>
        <para>
-        When this parameter is <literal>on</literal> (default), the <productname>PostgreSQL</productname>
-        server can switch on compression of traffic between server and client if it is requested by client.
-        Client sends to the server list of compression algorithms supported by frontend library,
-        server chooses one which is supported by backend library and sends it in compression acknowledgement message
-        to the client. This option allows to reject compression request even if it is supported by server
-        (due to security, CPU consumption or whatever else reasons...).
+        This parameter enables compression of libpq traffic between client and server.
+        The default is <literal>on</literal>.
+        This option allows rejecting compression requests even if it is supported by server
+        (for example, due to security, or CPU consumption).
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 2934908520..d4da390ca9 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1244,13 +1244,22 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>compression</literal></term>
       <listitem>
       <para>
-        Request compression of libpq traffic. Client sends to the server list of compression algorithms, supported by client library.
-        If server supports one of this algorithms, then it acknowledges use of this algorithm and then all libpq messages send both from client to server and
-        visa versa will be compressed. If server is not supporting any of the suggested algorithms, then it rejects client request to use compression
-        and it is up to the client whether to continue work without compression or report error.
-        Supported compression algorithms are chosen at configure time. Right now two libraries are supported: zlib (default) and zstd (if Postgres was
-        configured with --with-zstd option). In both cases streaming mode is used.
-        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+        Request compression of libpq traffic. The client sends a request with a list of compression algorithms.
+        Compression can be requested by a client by including the "compression" option in its connection string.
+        This can either be a boolean value to enable or disable compression
+        ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto", or an explicit list of comma-separated compression algorithms
+        which can optionally include compression level ("zlib,zstd:5").
+        If compression is enabled but an algorithm is not explicitly specified, the client library sends its full list of
+        supported algorithms and the server chooses a preferred algorithm.
+
+        If the server accepts one of the algorithms, it replies with an acknowledgment and all future libpq messages between client and server
+        will be compressed.
+        If the server rejects the compression request, it is up to the client whether to continue without compression or to report an error.
+        Support for compression algorithms must be enabled when the server is compiled.
+        Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
+        configured with --with-zstd option). In both cases, streaming mode is used.
+        By default, compression is not requested by the client.
+        Please note that using compression together with SSL may expose extra vulnerabilities:
         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;
       </para>
       </listitem>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 9f30aad8bd..a69f9bfc26 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -94,10 +94,10 @@
 
   <para>
     It is possible to compress protocol data to reduce traffic and speed-up client-server interaction.
-    Compression is especially useful for importing/exporting data to/from database using COPY command
-    and for replication (both physical and logical). Also compression can reduce server response time
-    in case of queries returning large amount of data (for example returning JSON, BLOBs, text,...)
-    Right now two libraries are supported: zlib (default) and zstd (if Postgres was
+    Compression is especially useful for importing/exporting data to/from the database using the <literal>COPY</literal> command
+    and for replication (both physical and logical). Compression can also reduce the server's response time
+    for queries returning a large amount of data (for example, JSON, BLOBs, text, ...).
+    Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
     configured with --with-zstd option).
   </para>
 
@@ -275,19 +275,14 @@
       <term>CompressionAck</term>
       <listitem>
        <para>
-         Server acknowledges using compression for client-server communication protocol.
-         Compression can be requested by client by including "compression" option in connection string.
-         It can be just boolean values enabling or disabling compression
-         ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto" or explicit list of compression algorithms
-         separated by comma with optional specification of compression level: "zlib,zstd:5".
-         If compression algorithm is not explicitly specified the most efficient one supported both by
-         client and server is chosen. Client sends to the server list of compression algorithms,
-         supported by client library.
-         If server supports one of this algorithms, then it acknowledges use of this algorithm and
-         all subsequent libpq messages send both from client to server and
-         visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-         index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-         and it is up to the client whether to continue work without compression or report error.
+         The server accepts the client's compression request.
+         Compression is requested when a client connection includes the "compression" option, which includes
+         a list of requested compression algorithms.
+         If the server accepts one of these algorithms, it acknowledges use of compression and
+         all subsequent libpq messages between the client and server will be compressed.
+         The server chooses an algorithm from the list specified by client and responds with the index of the chosen algorithm from the client-supplied list.
+         If the server does not accept any of the requested algorithms, then it replies with an index of -1
+         and it is up to the client whether to continue without compression or to report an error.
        </para>
       </listitem>
      </varlistentry>
@@ -3460,12 +3455,14 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-  Acknowledge use of compression for protocol data. Client sends to the server list of compression algorithms, supported by client library.
-  If server supports one of this algorithms, then it acknowledges use of this algorithm and all subsequent libpq messages send both from client to server and
-  visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-  index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-  and it is up to the client whether to continue work without compression or report error.
-  After receiving this message with algorithm index other than -1, both server and client are switched to compression mode
+  Acknowledge use of compression for protocol data. The client sends to the server a list of requested compression algorithms.
+  If the server supports any of these algorithms, it acknowledges use of this algorithm and all subsequent libpq messages between client and server
+  will be compressed.
+  The server selects the preferred algorithm from the list specified by client and responds with the
+  index of the chosen algorithm in this list.
+  If the server does not support any of the requested algorithms, it replies with -1
+  and it is up to the client whether to continue without compression or to report an error.
+  After receiving this message with algorithm index other than -1, both server and client switch to compressed mode
   and exchange compressed messages.
 </para>
 </listitem>
@@ -3486,7 +3483,7 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-        Index of algorithm in the list of supported algotihms specified by client or -1 if none of them is supported.
+        Index of algorithm in the list of supported algorithms specified by client or -1 if none of them are supported.
 </para>
 </listitem>
 </varlistentry>
@@ -6069,12 +6066,11 @@ StartupMessage (F)
 </term>
 <listitem>
 <para>
-                        Request compression of libpq traffic. Value is list of compression algorithms supported by client with optional
+                        Request compression of libpq traffic. The value is a list of compression algorithms requested by the client with an optional
                         specification of compression level: <literal>"zlib,zstd:5"</literal>.
-                        When connecting to an older backend, which does not support compression, or in case when the backend support compression
-                        but for some reason wants to disable it, the backend will just ignore the _pq_.compression parameter and won’t send
-                        the compressionAck message to the frontend.
-                        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+                        If the server does not accept compression, the backend will ignore the _pq_.compression
+                        parameter and will not send the CompressionAck message to the frontend.
+                        By default, compression is disabled. Please note that using compression together with SSL may expose extra vulnerabilities:
                         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;.
 </para>
 </listitem>
diff --git a/src/backend/libpq/pqcomm.c b/src/backend/libpq/pqcomm.c
index 8be1ce18de..f3293faf01 100644
--- a/src/backend/libpq/pqcomm.c
+++ b/src/backend/libpq/pqcomm.c
@@ -1073,7 +1073,7 @@ pq_recvbuf(bool nowait)
 	/* Can fill buffer from PqRecvLength and upwards */
 	for (;;)
 	{
-		/* If streaming compression is enabled then use correspondent compression read function. */
+		/* If streaming compression is enabled then use corresponding compression read function. */
 		r = PqStream
 			? zpq_read(PqStream, PqRecvBuffer + PqRecvLength,
 					   PQ_RECV_BUFFER_SIZE - PqRecvLength)
diff --git a/src/common/zpq_stream.c b/src/common/zpq_stream.c
index 459566228a..e044e83e7c 100644
--- a/src/common/zpq_stream.c
+++ b/src/common/zpq_stream.c
@@ -9,15 +9,15 @@
 typedef struct
 {
 	/*
-	 * Returns name of compression algorithm.
+	 * Name of compression algorithm.
 	 */
 	char const* (*name)(void);
 
 	/*
-	 * Create compression stream with using rx/tx function for fetching/sending compressed data.
+	 * Create compression stream with rx/tx function for reading/sending compressed data.
 	 * level: compression level
 	 * tx_func: function for writing compressed data in underlying stream
-	 * rx_func: function for receiving compressed data from underlying stream
+	 * rx_func: function for reading compressed data from underlying stream
 	 * arg: context passed to the function
      * rx_data: received data (compressed data already fetched from input stream)
 	 * rx_data_size: size of data fetched from input stream
@@ -27,14 +27,14 @@ typedef struct
 	/*
 	 * Read up to "size" raw (decompressed) bytes.
 	 * Returns number of decompressed bytes or error code.
-	 * Error code is either ZPQ_DECOMPRESS_ERROR either error code returned by the rx function.
+	 * Error code is either ZPQ_DECOMPRESS_ERROR or error code returned by the rx function.
 	 */
 	ssize_t (*read)(ZpqStream *zs, void *buf, size_t size);
 
 	/*
 	 * Write up to "size" raw (decompressed) bytes.
 	 * Returns number of written raw bytes or error code returned by tx function.
-	 * In the last case amount of written raw bytes is stored in *processed.
+	 * In the last case number of bytes written is stored in *processed.
 	 */
 	ssize_t (*write)(ZpqStream *zs, void const *buf, size_t size, size_t *processed);
 
@@ -49,12 +49,12 @@ typedef struct
 	char const* (*error)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal tx decompression buffer.
+	 * Return amount of data in internal tx decompression buffer.
 	 */
 	size_t  (*buffered_tx)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal rx compression buffer.
+	 * Return amount of data in internal rx compression buffer.
 	 */
 	size_t  (*buffered_rx)(ZpqStream *zs);
 } ZpqAlgorithm;
@@ -265,7 +265,7 @@ zstd_name(void)
 
 #define ZLIB_BUFFER_SIZE       8192 /* We have to flush stream after each protocol command
 									 * and command is mostly limited by record length,
-									 * which in turn usually less than page size (except TOAST)
+									 * which in turn is usually less than page size (except TOAST)
 									 */
 
 typedef struct ZlibStream
diff --git a/src/include/common/zpq_stream.h b/src/include/common/zpq_stream.h
index 27aef0aab9..991e2c0165 100644
--- a/src/include/common/zpq_stream.h
+++ b/src/include/common/zpq_stream.h
@@ -1,6 +1,6 @@
 /*
  * zpq_stream.h
- *     Streaiming compression for libpq
+ *     Streaming compression for libpq
  */
 
 #ifndef ZPQ_STREAM_H
diff --git a/src/interfaces/libpq/fe-connect.c b/src/interfaces/libpq/fe-connect.c
index eac6ef66cc..679f8cde9f 100644
--- a/src/interfaces/libpq/fe-connect.c
+++ b/src/interfaces/libpq/fe-connect.c
@@ -3269,7 +3269,7 @@ keep_going:						/* We will come back to here until there is
 						{
 							appendPQExpBuffer(&conn->errorMessage,
 											  libpq_gettext(
-												  "server is not supported requested compression algorithms %s\n"),
+												  "server does not support requested compression algorithms %s\n"),
 											  conn->compression);
 							goto error_return;
 						}
diff --git a/src/interfaces/libpq/fe-protocol3.c b/src/interfaces/libpq/fe-protocol3.c
index 095866bba0..5b879569b4 100644
--- a/src/interfaces/libpq/fe-protocol3.c
+++ b/src/interfaces/libpq/fe-protocol3.c
@@ -2135,15 +2135,15 @@ pqBuildStartupPacket3(PGconn *conn, int *packetlen,
 }
 
 /*
- * Build comma-separated list of compression algorithms suggested by client to the server.
- * It can be either explicitly specified by user in connection string, either
- * include all algorithms supported by clit library.
- * This functions returns true if compression string is successfully parsed and
- * stores comma-separated list of algorithms in *client_compressors.
- * If compression is disabled, then NULL is assigned to  *client_compressors.
- * Also it creates array of compressor descriptors, each element of which corresponds
- * the correspondent algorithm name in *client_compressors list. This array is stored in PGconn
- * and is used during handshake when compassion acknowledgment response is received from the server.
+ * Build comma-separated list of compression algorithms requested by client.
+ * It can be either explicitly specified by user in connection string, or
+ * include all algorithms supported by client library.
+ * This function returns true if the compression string is successfully parsed and
+ * stores a comma-separated list of algorithms in *client_compressors.
+ * If compression is disabled, then NULL is assigned to *client_compressors.
+ * Also it creates an array of compressor descriptors, each element of which corresponds to
+ * the corresponding algorithm name in *client_compressors list. This array is stored in PGconn
+ * and is used during handshake when a compression acknowledgment response is received from the server.
  */
 static bool
 build_compressors_list(PGconn *conn, char** client_compressors, bool build_descriptors)
@@ -2170,7 +2170,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 
 		if (n_supported_algorithms == 0)
 		{
-			*client_compressors = NULL; /* no compressors are avaialable */
+			*client_compressors = NULL; /* no compressors are available */
 			conn->compressors = NULL;
 			return true;
 		}
@@ -2204,7 +2204,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 	}
 	else
 	{
-		/* List of compresison algorithms separated by commas */
+		/* List of compression algorithms separated by commas */
 		char *src, *dst;
 		int n_suggested_algorithms = 0;
 		char* suggested_algorithms = strdup(value);
@@ -2232,7 +2232,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 				if (sscanf(col+1, "%d", &compression_level) != 1 && !build_descriptors)
 				{
 					fprintf(stderr,
-							libpq_gettext("WARNING: invlaid compression level %s in compression option '%s'\n"),
+							libpq_gettext("WARNING: invalid compression level %s in compression option '%s'\n"),
 							col+1, value);
 					return false;
 				}
@@ -2262,7 +2262,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 		{
 			if (!build_descriptors)
 				fprintf(stderr,
-						libpq_gettext("WARNING: none of specified algirthms %s is supported by client\n"),
+						libpq_gettext("WARNING: none of the specified algorithms are supported by client: %s\n"),
 						value);
 			else
 			{
-- 
2.17.0


--yudcn1FV7Hsu/q59--





^ permalink  raw  reply  [nested|flat] 22+ messages in thread

* [PATCH] fixes to docs and comments
@ 2021-01-09 15:49  Justin Pryzby <[email protected]>
  0 siblings, 0 replies; 22+ messages in thread

From: Justin Pryzby @ 2021-01-09 15:49 UTC (permalink / raw)

---
 doc/src/sgml/config.sgml            | 10 +++---
 doc/src/sgml/libpq.sgml             | 23 ++++++++----
 doc/src/sgml/protocol.sgml          | 54 +++++++++++++----------------
 src/backend/libpq/pqcomm.c          |  2 +-
 src/common/zpq_stream.c             | 16 ++++-----
 src/include/common/zpq_stream.h     |  2 +-
 src/interfaces/libpq/fe-connect.c   |  2 +-
 src/interfaces/libpq/fe-protocol3.c | 26 +++++++-------
 8 files changed, 69 insertions(+), 66 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 3b132dcf27..8b5a6525ac 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1004,12 +1004,10 @@ include_dir 'conf.d'
       </term>
       <listitem>
        <para>
-        When this parameter is <literal>on</literal> (default), the <productname>PostgreSQL</productname>
-        server can switch on compression of traffic between server and client if it is requested by client.
-        Client sends to the server list of compression algorithms supported by frontend library,
-        server chooses one which is supported by backend library and sends it in compression acknowledgement message
-        to the client. This option allows to reject compression request even if it is supported by server
-        (due to security, CPU consumption or whatever else reasons...).
+        This parameter enables compression of libpq traffic between client and server.
+        The default is <literal>on</literal>.
+        This option allows rejecting compression requests even if it is supported by server
+        (for example, due to security, or CPU consumption).
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 2934908520..d4da390ca9 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1244,13 +1244,22 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>compression</literal></term>
       <listitem>
       <para>
-        Request compression of libpq traffic. Client sends to the server list of compression algorithms, supported by client library.
-        If server supports one of this algorithms, then it acknowledges use of this algorithm and then all libpq messages send both from client to server and
-        visa versa will be compressed. If server is not supporting any of the suggested algorithms, then it rejects client request to use compression
-        and it is up to the client whether to continue work without compression or report error.
-        Supported compression algorithms are chosen at configure time. Right now two libraries are supported: zlib (default) and zstd (if Postgres was
-        configured with --with-zstd option). In both cases streaming mode is used.
-        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+        Request compression of libpq traffic. The client sends a request with a list of compression algorithms.
+        Compression can be requested by a client by including the "compression" option in its connection string.
+        This can either be a boolean value to enable or disable compression
+        ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto", or an explicit list of comma-separated compression algorithms
+        which can optionally include compression level ("zlib,zstd:5").
+        If compression is enabled but an algorithm is not explicitly specified, the client library sends its full list of
+        supported algorithms and the server chooses a preferred algorithm.
+
+        If the server accepts one of the algorithms, it replies with an acknowledgment and all future libpq messages between client and server
+        will be compressed.
+        If the server rejects the compression request, it is up to the client whether to continue without compression or to report an error.
+        Support for compression algorithms must be enabled when the server is compiled.
+        Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
+        configured with --with-zstd option). In both cases, streaming mode is used.
+        By default, compression is not requested by the client.
+        Please note that using compression together with SSL may expose extra vulnerabilities:
         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;
       </para>
       </listitem>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 9f30aad8bd..a69f9bfc26 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -94,10 +94,10 @@
 
   <para>
     It is possible to compress protocol data to reduce traffic and speed-up client-server interaction.
-    Compression is especially useful for importing/exporting data to/from database using COPY command
-    and for replication (both physical and logical). Also compression can reduce server response time
-    in case of queries returning large amount of data (for example returning JSON, BLOBs, text,...)
-    Right now two libraries are supported: zlib (default) and zstd (if Postgres was
+    Compression is especially useful for importing/exporting data to/from the database using the <literal>COPY</literal> command
+    and for replication (both physical and logical). Compression can also reduce the server's response time
+    for queries returning a large amount of data (for example, JSON, BLOBs, text, ...).
+    Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
     configured with --with-zstd option).
   </para>
 
@@ -275,19 +275,14 @@
       <term>CompressionAck</term>
       <listitem>
        <para>
-         Server acknowledges using compression for client-server communication protocol.
-         Compression can be requested by client by including "compression" option in connection string.
-         It can be just boolean values enabling or disabling compression
-         ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto" or explicit list of compression algorithms
-         separated by comma with optional specification of compression level: "zlib,zstd:5".
-         If compression algorithm is not explicitly specified the most efficient one supported both by
-         client and server is chosen. Client sends to the server list of compression algorithms,
-         supported by client library.
-         If server supports one of this algorithms, then it acknowledges use of this algorithm and
-         all subsequent libpq messages send both from client to server and
-         visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-         index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-         and it is up to the client whether to continue work without compression or report error.
+         The server accepts the client's compression request.
+         Compression is requested when a client connection includes the "compression" option, which includes
+         a list of requested compression algorithms.
+         If the server accepts one of these algorithms, it acknowledges use of compression and
+         all subsequent libpq messages between the client and server will be compressed.
+         The server chooses an algorithm from the list specified by client and responds with the index of the chosen algorithm from the client-supplied list.
+         If the server does not accept any of the requested algorithms, then it replies with an index of -1
+         and it is up to the client whether to continue without compression or to report an error.
        </para>
       </listitem>
      </varlistentry>
@@ -3460,12 +3455,14 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-  Acknowledge use of compression for protocol data. Client sends to the server list of compression algorithms, supported by client library.
-  If server supports one of this algorithms, then it acknowledges use of this algorithm and all subsequent libpq messages send both from client to server and
-  visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-  index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-  and it is up to the client whether to continue work without compression or report error.
-  After receiving this message with algorithm index other than -1, both server and client are switched to compression mode
+  Acknowledge use of compression for protocol data. The client sends to the server a list of requested compression algorithms.
+  If the server supports any of these algorithms, it acknowledges use of this algorithm and all subsequent libpq messages between client and server
+  will be compressed.
+  The server selects the preferred algorithm from the list specified by client and responds with the
+  index of the chosen algorithm in this list.
+  If the server does not support any of the requested algorithms, it replies with -1
+  and it is up to the client whether to continue without compression or to report an error.
+  After receiving this message with algorithm index other than -1, both server and client switch to compressed mode
   and exchange compressed messages.
 </para>
 </listitem>
@@ -3486,7 +3483,7 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-        Index of algorithm in the list of supported algotihms specified by client or -1 if none of them is supported.
+        Index of algorithm in the list of supported algorithms specified by client or -1 if none of them are supported.
 </para>
 </listitem>
 </varlistentry>
@@ -6069,12 +6066,11 @@ StartupMessage (F)
 </term>
 <listitem>
 <para>
-                        Request compression of libpq traffic. Value is list of compression algorithms supported by client with optional
+                        Request compression of libpq traffic. The value is a list of compression algorithms requested by the client with an optional
                         specification of compression level: <literal>"zlib,zstd:5"</literal>.
-                        When connecting to an older backend, which does not support compression, or in case when the backend support compression
-                        but for some reason wants to disable it, the backend will just ignore the _pq_.compression parameter and won’t send
-                        the compressionAck message to the frontend.
-                        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+                        If the server does not accept compression, the backend will ignore the _pq_.compression
+                        parameter and will not send the CompressionAck message to the frontend.
+                        By default, compression is disabled. Please note that using compression together with SSL may expose extra vulnerabilities:
                         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;.
 </para>
 </listitem>
diff --git a/src/backend/libpq/pqcomm.c b/src/backend/libpq/pqcomm.c
index 8be1ce18de..f3293faf01 100644
--- a/src/backend/libpq/pqcomm.c
+++ b/src/backend/libpq/pqcomm.c
@@ -1073,7 +1073,7 @@ pq_recvbuf(bool nowait)
 	/* Can fill buffer from PqRecvLength and upwards */
 	for (;;)
 	{
-		/* If streaming compression is enabled then use correspondent compression read function. */
+		/* If streaming compression is enabled then use corresponding compression read function. */
 		r = PqStream
 			? zpq_read(PqStream, PqRecvBuffer + PqRecvLength,
 					   PQ_RECV_BUFFER_SIZE - PqRecvLength)
diff --git a/src/common/zpq_stream.c b/src/common/zpq_stream.c
index 459566228a..e044e83e7c 100644
--- a/src/common/zpq_stream.c
+++ b/src/common/zpq_stream.c
@@ -9,15 +9,15 @@
 typedef struct
 {
 	/*
-	 * Returns name of compression algorithm.
+	 * Name of compression algorithm.
 	 */
 	char const* (*name)(void);
 
 	/*
-	 * Create compression stream with using rx/tx function for fetching/sending compressed data.
+	 * Create compression stream with rx/tx function for reading/sending compressed data.
 	 * level: compression level
 	 * tx_func: function for writing compressed data in underlying stream
-	 * rx_func: function for receiving compressed data from underlying stream
+	 * rx_func: function for reading compressed data from underlying stream
 	 * arg: context passed to the function
      * rx_data: received data (compressed data already fetched from input stream)
 	 * rx_data_size: size of data fetched from input stream
@@ -27,14 +27,14 @@ typedef struct
 	/*
 	 * Read up to "size" raw (decompressed) bytes.
 	 * Returns number of decompressed bytes or error code.
-	 * Error code is either ZPQ_DECOMPRESS_ERROR either error code returned by the rx function.
+	 * Error code is either ZPQ_DECOMPRESS_ERROR or error code returned by the rx function.
 	 */
 	ssize_t (*read)(ZpqStream *zs, void *buf, size_t size);
 
 	/*
 	 * Write up to "size" raw (decompressed) bytes.
 	 * Returns number of written raw bytes or error code returned by tx function.
-	 * In the last case amount of written raw bytes is stored in *processed.
+	 * In the last case number of bytes written is stored in *processed.
 	 */
 	ssize_t (*write)(ZpqStream *zs, void const *buf, size_t size, size_t *processed);
 
@@ -49,12 +49,12 @@ typedef struct
 	char const* (*error)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal tx decompression buffer.
+	 * Return amount of data in internal tx decompression buffer.
 	 */
 	size_t  (*buffered_tx)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal rx compression buffer.
+	 * Return amount of data in internal rx compression buffer.
 	 */
 	size_t  (*buffered_rx)(ZpqStream *zs);
 } ZpqAlgorithm;
@@ -265,7 +265,7 @@ zstd_name(void)
 
 #define ZLIB_BUFFER_SIZE       8192 /* We have to flush stream after each protocol command
 									 * and command is mostly limited by record length,
-									 * which in turn usually less than page size (except TOAST)
+									 * which in turn is usually less than page size (except TOAST)
 									 */
 
 typedef struct ZlibStream
diff --git a/src/include/common/zpq_stream.h b/src/include/common/zpq_stream.h
index 27aef0aab9..991e2c0165 100644
--- a/src/include/common/zpq_stream.h
+++ b/src/include/common/zpq_stream.h
@@ -1,6 +1,6 @@
 /*
  * zpq_stream.h
- *     Streaiming compression for libpq
+ *     Streaming compression for libpq
  */
 
 #ifndef ZPQ_STREAM_H
diff --git a/src/interfaces/libpq/fe-connect.c b/src/interfaces/libpq/fe-connect.c
index eac6ef66cc..679f8cde9f 100644
--- a/src/interfaces/libpq/fe-connect.c
+++ b/src/interfaces/libpq/fe-connect.c
@@ -3269,7 +3269,7 @@ keep_going:						/* We will come back to here until there is
 						{
 							appendPQExpBuffer(&conn->errorMessage,
 											  libpq_gettext(
-												  "server is not supported requested compression algorithms %s\n"),
+												  "server does not support requested compression algorithms %s\n"),
 											  conn->compression);
 							goto error_return;
 						}
diff --git a/src/interfaces/libpq/fe-protocol3.c b/src/interfaces/libpq/fe-protocol3.c
index 095866bba0..5b879569b4 100644
--- a/src/interfaces/libpq/fe-protocol3.c
+++ b/src/interfaces/libpq/fe-protocol3.c
@@ -2135,15 +2135,15 @@ pqBuildStartupPacket3(PGconn *conn, int *packetlen,
 }
 
 /*
- * Build comma-separated list of compression algorithms suggested by client to the server.
- * It can be either explicitly specified by user in connection string, either
- * include all algorithms supported by clit library.
- * This functions returns true if compression string is successfully parsed and
- * stores comma-separated list of algorithms in *client_compressors.
- * If compression is disabled, then NULL is assigned to  *client_compressors.
- * Also it creates array of compressor descriptors, each element of which corresponds
- * the correspondent algorithm name in *client_compressors list. This array is stored in PGconn
- * and is used during handshake when compassion acknowledgment response is received from the server.
+ * Build comma-separated list of compression algorithms requested by client.
+ * It can be either explicitly specified by user in connection string, or
+ * include all algorithms supported by client library.
+ * This function returns true if the compression string is successfully parsed and
+ * stores a comma-separated list of algorithms in *client_compressors.
+ * If compression is disabled, then NULL is assigned to *client_compressors.
+ * Also it creates an array of compressor descriptors, each element of which corresponds to
+ * the corresponding algorithm name in *client_compressors list. This array is stored in PGconn
+ * and is used during handshake when a compression acknowledgment response is received from the server.
  */
 static bool
 build_compressors_list(PGconn *conn, char** client_compressors, bool build_descriptors)
@@ -2170,7 +2170,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 
 		if (n_supported_algorithms == 0)
 		{
-			*client_compressors = NULL; /* no compressors are avaialable */
+			*client_compressors = NULL; /* no compressors are available */
 			conn->compressors = NULL;
 			return true;
 		}
@@ -2204,7 +2204,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 	}
 	else
 	{
-		/* List of compresison algorithms separated by commas */
+		/* List of compression algorithms separated by commas */
 		char *src, *dst;
 		int n_suggested_algorithms = 0;
 		char* suggested_algorithms = strdup(value);
@@ -2232,7 +2232,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 				if (sscanf(col+1, "%d", &compression_level) != 1 && !build_descriptors)
 				{
 					fprintf(stderr,
-							libpq_gettext("WARNING: invlaid compression level %s in compression option '%s'\n"),
+							libpq_gettext("WARNING: invalid compression level %s in compression option '%s'\n"),
 							col+1, value);
 					return false;
 				}
@@ -2262,7 +2262,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 		{
 			if (!build_descriptors)
 				fprintf(stderr,
-						libpq_gettext("WARNING: none of specified algirthms %s is supported by client\n"),
+						libpq_gettext("WARNING: none of the specified algorithms are supported by client: %s\n"),
 						value);
 			else
 			{
-- 
2.17.0


--yudcn1FV7Hsu/q59--





^ permalink  raw  reply  [nested|flat] 22+ messages in thread

* [PATCH] fixes to docs and comments
@ 2021-01-09 15:49  Justin Pryzby <[email protected]>
  0 siblings, 0 replies; 22+ messages in thread

From: Justin Pryzby @ 2021-01-09 15:49 UTC (permalink / raw)

---
 doc/src/sgml/config.sgml            | 10 +++---
 doc/src/sgml/libpq.sgml             | 23 ++++++++----
 doc/src/sgml/protocol.sgml          | 54 +++++++++++++----------------
 src/backend/libpq/pqcomm.c          |  2 +-
 src/common/zpq_stream.c             | 16 ++++-----
 src/include/common/zpq_stream.h     |  2 +-
 src/interfaces/libpq/fe-connect.c   |  2 +-
 src/interfaces/libpq/fe-protocol3.c | 26 +++++++-------
 8 files changed, 69 insertions(+), 66 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 3b132dcf27..8b5a6525ac 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1004,12 +1004,10 @@ include_dir 'conf.d'
       </term>
       <listitem>
        <para>
-        When this parameter is <literal>on</literal> (default), the <productname>PostgreSQL</productname>
-        server can switch on compression of traffic between server and client if it is requested by client.
-        Client sends to the server list of compression algorithms supported by frontend library,
-        server chooses one which is supported by backend library and sends it in compression acknowledgement message
-        to the client. This option allows to reject compression request even if it is supported by server
-        (due to security, CPU consumption or whatever else reasons...).
+        This parameter enables compression of libpq traffic between client and server.
+        The default is <literal>on</literal>.
+        This option allows rejecting compression requests even if it is supported by server
+        (for example, due to security, or CPU consumption).
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 2934908520..d4da390ca9 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1244,13 +1244,22 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>compression</literal></term>
       <listitem>
       <para>
-        Request compression of libpq traffic. Client sends to the server list of compression algorithms, supported by client library.
-        If server supports one of this algorithms, then it acknowledges use of this algorithm and then all libpq messages send both from client to server and
-        visa versa will be compressed. If server is not supporting any of the suggested algorithms, then it rejects client request to use compression
-        and it is up to the client whether to continue work without compression or report error.
-        Supported compression algorithms are chosen at configure time. Right now two libraries are supported: zlib (default) and zstd (if Postgres was
-        configured with --with-zstd option). In both cases streaming mode is used.
-        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+        Request compression of libpq traffic. The client sends a request with a list of compression algorithms.
+        Compression can be requested by a client by including the "compression" option in its connection string.
+        This can either be a boolean value to enable or disable compression
+        ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto", or an explicit list of comma-separated compression algorithms
+        which can optionally include compression level ("zlib,zstd:5").
+        If compression is enabled but an algorithm is not explicitly specified, the client library sends its full list of
+        supported algorithms and the server chooses a preferred algorithm.
+
+        If the server accepts one of the algorithms, it replies with an acknowledgment and all future libpq messages between client and server
+        will be compressed.
+        If the server rejects the compression request, it is up to the client whether to continue without compression or to report an error.
+        Support for compression algorithms must be enabled when the server is compiled.
+        Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
+        configured with --with-zstd option). In both cases, streaming mode is used.
+        By default, compression is not requested by the client.
+        Please note that using compression together with SSL may expose extra vulnerabilities:
         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;
       </para>
       </listitem>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 9f30aad8bd..a69f9bfc26 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -94,10 +94,10 @@
 
   <para>
     It is possible to compress protocol data to reduce traffic and speed-up client-server interaction.
-    Compression is especially useful for importing/exporting data to/from database using COPY command
-    and for replication (both physical and logical). Also compression can reduce server response time
-    in case of queries returning large amount of data (for example returning JSON, BLOBs, text,...)
-    Right now two libraries are supported: zlib (default) and zstd (if Postgres was
+    Compression is especially useful for importing/exporting data to/from the database using the <literal>COPY</literal> command
+    and for replication (both physical and logical). Compression can also reduce the server's response time
+    for queries returning a large amount of data (for example, JSON, BLOBs, text, ...).
+    Currently, two libraries are supported: zlib (default) and zstd (if Postgres was
     configured with --with-zstd option).
   </para>
 
@@ -275,19 +275,14 @@
       <term>CompressionAck</term>
       <listitem>
        <para>
-         Server acknowledges using compression for client-server communication protocol.
-         Compression can be requested by client by including "compression" option in connection string.
-         It can be just boolean values enabling or disabling compression
-         ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "auto" or explicit list of compression algorithms
-         separated by comma with optional specification of compression level: "zlib,zstd:5".
-         If compression algorithm is not explicitly specified the most efficient one supported both by
-         client and server is chosen. Client sends to the server list of compression algorithms,
-         supported by client library.
-         If server supports one of this algorithms, then it acknowledges use of this algorithm and
-         all subsequent libpq messages send both from client to server and
-         visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-         index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-         and it is up to the client whether to continue work without compression or report error.
+         The server accepts the client's compression request.
+         Compression is requested when a client connection includes the "compression" option, which includes
+         a list of requested compression algorithms.
+         If the server accepts one of these algorithms, it acknowledges use of compression and
+         all subsequent libpq messages between the client and server will be compressed.
+         The server chooses an algorithm from the list specified by client and responds with the index of the chosen algorithm from the client-supplied list.
+         If the server does not accept any of the requested algorithms, then it replies with an index of -1
+         and it is up to the client whether to continue without compression or to report an error.
        </para>
       </listitem>
      </varlistentry>
@@ -3460,12 +3455,14 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-  Acknowledge use of compression for protocol data. Client sends to the server list of compression algorithms, supported by client library.
-  If server supports one of this algorithms, then it acknowledges use of this algorithm and all subsequent libpq messages send both from client to server and
-  visa versa will be compressed. Server selects most efficient algorithm among list specified by client and returns to the client
-  index of chosen algorithm in this list. If server is not supporting any of the suggested algorithms, then it replies with -1
-  and it is up to the client whether to continue work without compression or report error.
-  After receiving this message with algorithm index other than -1, both server and client are switched to compression mode
+  Acknowledge use of compression for protocol data. The client sends to the server a list of requested compression algorithms.
+  If the server supports any of these algorithms, it acknowledges use of this algorithm and all subsequent libpq messages between client and server
+  will be compressed.
+  The server selects the preferred algorithm from the list specified by client and responds with the
+  index of the chosen algorithm in this list.
+  If the server does not support any of the requested algorithms, it replies with -1
+  and it is up to the client whether to continue without compression or to report an error.
+  After receiving this message with algorithm index other than -1, both server and client switch to compressed mode
   and exchange compressed messages.
 </para>
 </listitem>
@@ -3486,7 +3483,7 @@ CompressionAck (B)
 </term>
 <listitem>
 <para>
-        Index of algorithm in the list of supported algotihms specified by client or -1 if none of them is supported.
+        Index of algorithm in the list of supported algorithms specified by client or -1 if none of them are supported.
 </para>
 </listitem>
 </varlistentry>
@@ -6069,12 +6066,11 @@ StartupMessage (F)
 </term>
 <listitem>
 <para>
-                        Request compression of libpq traffic. Value is list of compression algorithms supported by client with optional
+                        Request compression of libpq traffic. The value is a list of compression algorithms requested by the client with an optional
                         specification of compression level: <literal>"zlib,zstd:5"</literal>.
-                        When connecting to an older backend, which does not support compression, or in case when the backend support compression
-                        but for some reason wants to disable it, the backend will just ignore the _pq_.compression parameter and won’t send
-                        the compressionAck message to the frontend.
-                        By default compression is disabled. Please notice that using compression together with SSL may add extra vulnerabilities:
+                        If the server does not accept compression, the backend will ignore the _pq_.compression
+                        parameter and will not send the CompressionAck message to the frontend.
+                        By default, compression is disabled. Please note that using compression together with SSL may expose extra vulnerabilities:
                         <ulink url="https://en.wikipedia.org/wiki/CRIME">CRIME</ulink;.
 </para>
 </listitem>
diff --git a/src/backend/libpq/pqcomm.c b/src/backend/libpq/pqcomm.c
index 8be1ce18de..f3293faf01 100644
--- a/src/backend/libpq/pqcomm.c
+++ b/src/backend/libpq/pqcomm.c
@@ -1073,7 +1073,7 @@ pq_recvbuf(bool nowait)
 	/* Can fill buffer from PqRecvLength and upwards */
 	for (;;)
 	{
-		/* If streaming compression is enabled then use correspondent compression read function. */
+		/* If streaming compression is enabled then use corresponding compression read function. */
 		r = PqStream
 			? zpq_read(PqStream, PqRecvBuffer + PqRecvLength,
 					   PQ_RECV_BUFFER_SIZE - PqRecvLength)
diff --git a/src/common/zpq_stream.c b/src/common/zpq_stream.c
index 459566228a..e044e83e7c 100644
--- a/src/common/zpq_stream.c
+++ b/src/common/zpq_stream.c
@@ -9,15 +9,15 @@
 typedef struct
 {
 	/*
-	 * Returns name of compression algorithm.
+	 * Name of compression algorithm.
 	 */
 	char const* (*name)(void);
 
 	/*
-	 * Create compression stream with using rx/tx function for fetching/sending compressed data.
+	 * Create compression stream with rx/tx function for reading/sending compressed data.
 	 * level: compression level
 	 * tx_func: function for writing compressed data in underlying stream
-	 * rx_func: function for receiving compressed data from underlying stream
+	 * rx_func: function for reading compressed data from underlying stream
 	 * arg: context passed to the function
      * rx_data: received data (compressed data already fetched from input stream)
 	 * rx_data_size: size of data fetched from input stream
@@ -27,14 +27,14 @@ typedef struct
 	/*
 	 * Read up to "size" raw (decompressed) bytes.
 	 * Returns number of decompressed bytes or error code.
-	 * Error code is either ZPQ_DECOMPRESS_ERROR either error code returned by the rx function.
+	 * Error code is either ZPQ_DECOMPRESS_ERROR or error code returned by the rx function.
 	 */
 	ssize_t (*read)(ZpqStream *zs, void *buf, size_t size);
 
 	/*
 	 * Write up to "size" raw (decompressed) bytes.
 	 * Returns number of written raw bytes or error code returned by tx function.
-	 * In the last case amount of written raw bytes is stored in *processed.
+	 * In the last case number of bytes written is stored in *processed.
 	 */
 	ssize_t (*write)(ZpqStream *zs, void const *buf, size_t size, size_t *processed);
 
@@ -49,12 +49,12 @@ typedef struct
 	char const* (*error)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal tx decompression buffer.
+	 * Return amount of data in internal tx decompression buffer.
 	 */
 	size_t  (*buffered_tx)(ZpqStream *zs);
 
 	/*
-	 * Returns amount of data in internal rx compression buffer.
+	 * Return amount of data in internal rx compression buffer.
 	 */
 	size_t  (*buffered_rx)(ZpqStream *zs);
 } ZpqAlgorithm;
@@ -265,7 +265,7 @@ zstd_name(void)
 
 #define ZLIB_BUFFER_SIZE       8192 /* We have to flush stream after each protocol command
 									 * and command is mostly limited by record length,
-									 * which in turn usually less than page size (except TOAST)
+									 * which in turn is usually less than page size (except TOAST)
 									 */
 
 typedef struct ZlibStream
diff --git a/src/include/common/zpq_stream.h b/src/include/common/zpq_stream.h
index 27aef0aab9..991e2c0165 100644
--- a/src/include/common/zpq_stream.h
+++ b/src/include/common/zpq_stream.h
@@ -1,6 +1,6 @@
 /*
  * zpq_stream.h
- *     Streaiming compression for libpq
+ *     Streaming compression for libpq
  */
 
 #ifndef ZPQ_STREAM_H
diff --git a/src/interfaces/libpq/fe-connect.c b/src/interfaces/libpq/fe-connect.c
index eac6ef66cc..679f8cde9f 100644
--- a/src/interfaces/libpq/fe-connect.c
+++ b/src/interfaces/libpq/fe-connect.c
@@ -3269,7 +3269,7 @@ keep_going:						/* We will come back to here until there is
 						{
 							appendPQExpBuffer(&conn->errorMessage,
 											  libpq_gettext(
-												  "server is not supported requested compression algorithms %s\n"),
+												  "server does not support requested compression algorithms %s\n"),
 											  conn->compression);
 							goto error_return;
 						}
diff --git a/src/interfaces/libpq/fe-protocol3.c b/src/interfaces/libpq/fe-protocol3.c
index 095866bba0..5b879569b4 100644
--- a/src/interfaces/libpq/fe-protocol3.c
+++ b/src/interfaces/libpq/fe-protocol3.c
@@ -2135,15 +2135,15 @@ pqBuildStartupPacket3(PGconn *conn, int *packetlen,
 }
 
 /*
- * Build comma-separated list of compression algorithms suggested by client to the server.
- * It can be either explicitly specified by user in connection string, either
- * include all algorithms supported by clit library.
- * This functions returns true if compression string is successfully parsed and
- * stores comma-separated list of algorithms in *client_compressors.
- * If compression is disabled, then NULL is assigned to  *client_compressors.
- * Also it creates array of compressor descriptors, each element of which corresponds
- * the correspondent algorithm name in *client_compressors list. This array is stored in PGconn
- * and is used during handshake when compassion acknowledgment response is received from the server.
+ * Build comma-separated list of compression algorithms requested by client.
+ * It can be either explicitly specified by user in connection string, or
+ * include all algorithms supported by client library.
+ * This function returns true if the compression string is successfully parsed and
+ * stores a comma-separated list of algorithms in *client_compressors.
+ * If compression is disabled, then NULL is assigned to *client_compressors.
+ * Also it creates an array of compressor descriptors, each element of which corresponds to
+ * the corresponding algorithm name in *client_compressors list. This array is stored in PGconn
+ * and is used during handshake when a compression acknowledgment response is received from the server.
  */
 static bool
 build_compressors_list(PGconn *conn, char** client_compressors, bool build_descriptors)
@@ -2170,7 +2170,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 
 		if (n_supported_algorithms == 0)
 		{
-			*client_compressors = NULL; /* no compressors are avaialable */
+			*client_compressors = NULL; /* no compressors are available */
 			conn->compressors = NULL;
 			return true;
 		}
@@ -2204,7 +2204,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 	}
 	else
 	{
-		/* List of compresison algorithms separated by commas */
+		/* List of compression algorithms separated by commas */
 		char *src, *dst;
 		int n_suggested_algorithms = 0;
 		char* suggested_algorithms = strdup(value);
@@ -2232,7 +2232,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 				if (sscanf(col+1, "%d", &compression_level) != 1 && !build_descriptors)
 				{
 					fprintf(stderr,
-							libpq_gettext("WARNING: invlaid compression level %s in compression option '%s'\n"),
+							libpq_gettext("WARNING: invalid compression level %s in compression option '%s'\n"),
 							col+1, value);
 					return false;
 				}
@@ -2262,7 +2262,7 @@ build_compressors_list(PGconn *conn, char** client_compressors, bool build_descr
 		{
 			if (!build_descriptors)
 				fprintf(stderr,
-						libpq_gettext("WARNING: none of specified algirthms %s is supported by client\n"),
+						libpq_gettext("WARNING: none of the specified algorithms are supported by client: %s\n"),
 						value);
 			else
 			{
-- 
2.17.0


--yudcn1FV7Hsu/q59--





^ permalink  raw  reply  [nested|flat] 22+ messages in thread

* Re: What object types should be in schemas?
@ 2023-01-11 15:53  Tom Lane <[email protected]>
  0 siblings, 0 replies; 22+ messages in thread

From: Tom Lane @ 2023-01-11 15:53 UTC (permalink / raw)
  To: Peter Eisentraut <[email protected]>; +Cc: pgsql-hackers

Peter Eisentraut <[email protected]> writes:
> The current hierarchy of object types is like this:
> ...
> How does one decide whether something should be in a schema or not?

Roughly speaking, I think the intuition was "if there are not likely
to be a lot of objects of type X, maybe they don't need to be within
schemas".

Extensions might be raised as a counterexample, but in that case
I recall that there was a specific consideration: extensions can
contain (own) schemas, so it would be very confusing if they could
also be within schemas.

I'm not sure about whether that holds for foreign data wrappers and
foreign servers, but isn't that case mandated by the SQL spec?

Roles and tablespaces aren't within schemas because they aren't
within databases.

> Over in the column encryption thread, the patch proposes to add various 
> key types as new object types.  For simplicity, I just stuck them 
> directly under database, but I don't know whether that is correct.

Is it reasonable for those to be per-database rather than cluster-wide?
I don't immediately see a reason to have encrypted columns in shared
catalogs, but there would never be any chance of supporting that if
the keys live in per-database catalogs.  (OTOH, perhaps there are
security reasons to keep them per-database, so I'm not insisting
that this is the right way.)

If we did make them cluster-wide then of course they'd be outside
schemas too.  If we don't, I'd lean slightly towards putting them
within schemas, because that seems to be the default choice if you're
not sure.  There probably aren't a huge number of text search parsers
either, but they live within schemas.

			regards, tom lane






^ permalink  raw  reply  [nested|flat] 22+ messages in thread

end of thread, other threads:[~2023-01-11 15:53 UTC | newest]

Thread overview: 22+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2021-01-09 15:49 [PATCH] fixes to docs and comments Justin Pryzby <[email protected]>
2021-01-09 15:49 [PATCH] fixes to docs and comments Justin Pryzby <[email protected]>
2021-01-09 15:49 [PATCH] fixes to docs and comments Justin Pryzby <[email protected]>
2021-01-09 15:49 [PATCH] fixes to docs and comments Justin Pryzby <[email protected]>
2021-01-09 15:49 [PATCH] fixes to docs and comments Justin Pryzby <[email protected]>
2021-01-09 15:49 [PATCH] fixes to docs and comments Justin Pryzby <[email protected]>
2021-01-09 15:49 [PATCH] fixes to docs and comments Justin Pryzby <[email protected]>
2021-01-09 15:49 [PATCH] fixes to docs and comments Justin Pryzby <[email protected]>
2021-01-09 15:49 [PATCH] fixes to docs and comments Justin Pryzby <[email protected]>
2021-01-09 15:49 [PATCH] fixes to docs and comments Justin Pryzby <[email protected]>
2021-01-09 15:49 [PATCH] fixes to docs and comments Justin Pryzby <[email protected]>
2021-01-09 15:49 [PATCH] fixes to docs and comments Justin Pryzby <[email protected]>
2021-01-09 15:49 [PATCH] fixes to docs and comments Justin Pryzby <[email protected]>
2021-01-09 15:49 [PATCH] fixes to docs and comments Justin Pryzby <[email protected]>
2021-01-09 15:49 [PATCH] fixes to docs and comments Justin Pryzby <[email protected]>
2021-01-09 15:49 [PATCH] fixes to docs and comments Justin Pryzby <[email protected]>
2021-01-09 15:49 [PATCH] fixes to docs and comments Justin Pryzby <[email protected]>
2021-01-09 15:49 [PATCH] fixes to docs and comments Justin Pryzby <[email protected]>
2021-01-09 15:49 [PATCH] fixes to docs and comments Justin Pryzby <[email protected]>
2021-01-09 15:49 [PATCH] fixes to docs and comments Justin Pryzby <[email protected]>
2021-01-09 15:49 [PATCH] fixes to docs and comments Justin Pryzby <[email protected]>
2023-01-11 15:53 Re: What object types should be in schemas? Tom Lane <[email protected]>

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox