public inbox for [email protected]
help / color / mirror / Atom feedFrom: Justin Pryzby <[email protected]>
Subject: [PATCH] fixes to docs and comments
Date: Sat, 9 Jan 2021 09:49:23 -0600
---
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--
view thread (23+ messages) latest in thread
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: [email protected]
Cc: [email protected]
Subject: Re: [PATCH] fixes to docs and comments
In-Reply-To: <no-message-id-1872969@localhost>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox