-- cgit v0.12 From e95aa99b53ecc065995e046417ae4379a4b0c160 Mon Sep 17 00:00:00 2001 From: kjnash Date: Wed, 11 May 2022 17:21:37 +0000 Subject: Revise http(n) to fix #15e4bd83c2 --- doc/http.n | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/http.n b/doc/http.n index a451f80..ed698f2 100644 --- a/doc/http.n +++ b/doc/http.n @@ -318,7 +318,8 @@ otherwise complain about HTTP/1.1. .TP \fB\-query\fR \fIquery\fR . -This flag causes \fB::http::geturl\fR to do a POST request that passes the +This flag (if the value is non-empty) causes \fB::http::geturl\fR to do a +POST request that passes the \fIquery\fR as payload verbatim to the server. The content format (and encoding) of \fIquery\fR is announced by the header field \fBcontent-type\fR set by the option \fB-type\fR. -- cgit v0.12 From f9d3eb28e94e4e1a235e70e3ca01c25e5aeeaed0 Mon Sep 17 00:00:00 2001 From: kjnash Date: Wed, 11 May 2022 18:13:32 +0000 Subject: Revise http(n) to fix #1414262 --- doc/http.n | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/doc/http.n b/doc/http.n index ed698f2..7bcf21c 100644 --- a/doc/http.n +++ b/doc/http.n @@ -135,6 +135,13 @@ the proxy server and proxy port. Otherwise the filter should return an empty list. The default filter returns the values of the \fB\-proxyhost\fR and \fB\-proxyport\fR settings if they are non-empty. +.RS +.PP +The \fB::http::geturl\fR command runs the \fB-proxyfilter\fR callback inside +a \fBcatch\fR command. Therefore an error in the callback command does +not call the \fBbgerror\fR handler. See the \fBERRORS\fR section for +details. +.RE .TP \fB\-repost\fR \fIboolean\fR . @@ -228,6 +235,11 @@ proc httpCallback {token} { # Access state as a Tcl array } .CE +.PP +The \fB::http::geturl\fR command runs the \fB-command\fR callback inside +a \fBcatch\fR command. Therefore an error in the callback command does +not call the \fBbgerror\fR handler. See the \fBERRORS\fR section for +details. .RE .TP \fB\-handler\fR \fIcallback\fR @@ -257,6 +269,11 @@ proc httpHandlerCallback {socket token} { The \fBhttp::geturl\fR code for the \fB-handler\fR option is not compatible with either compression or chunked transfer-encoding. If \fB-handler\fR is specified, then to work around these issues \fBhttp::geturl\fR will reduce the HTTP protocol to 1.0, and override the \fB-zip\fR option (i.e. it will not send the header "\fBAccept-Encoding: gzip,deflate,compress\fR"). .PP If options \fB-handler\fR and \fB-channel\fR are used together, the handler is responsible for copying the data from the HTTP socket to the specified channel. The name of the channel is available to the handler as element \fB-channel\fR of the token array. +.PP +The \fB::http::geturl\fR command runs the \fB-handler\fR callback inside +a \fBcatch\fR command. Therefore an error in the callback command does +not call the \fBbgerror\fR handler. See the \fBERRORS\fR section for +details. .RE .TP \fB\-headers\fR \fIkeyvaluelist\fR @@ -523,6 +540,14 @@ to know the result of the asynchronous HTTP request, it can call \fB::http::wait\fR and then check status and error, just as the callback does. .PP +The \fB::http::geturl\fR command runs the \fB-command\fR, \fB-handler\fR, +and \fB-proxyfilter\fR callbacks inside a \fBcatch\fR command. Therefore +an error in the callback command does not call the \fBbgerror\fR handler. +When debugging one of these +callbacks, it may be convenient to report errors by using a +\fBcatch\fR command within the callback command itself, e.g. to write +an error message to stdout. +.PP In any case, you must still call \fB::http::cleanup\fR to delete the state array when you are done. .PP -- cgit v0.12 From cdea365a569c1ba3e22c816c475847b4bd3f5085 Mon Sep 17 00:00:00 2001 From: kjnash Date: Wed, 11 May 2022 18:24:00 +0000 Subject: Revise http(n) to fix #443195 --- doc/http.n | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/http.n b/doc/http.n index 7bcf21c..c4a8688 100644 --- a/doc/http.n +++ b/doc/http.n @@ -49,6 +49,11 @@ http \- Client-side implementation of the HTTP/1.1 protocol \fB::http::registerError \fIport\fR ?\fImessage\fR? .sp \fB::http::unregister \fIproto\fR +.SH "EXPORTED COMMANDS" +.PP +Namespace \fBhttp\fR exports the commands \fBconfig\fR, \fBformatQuery\fR, \fBgeturl\fR, \fBquoteString\fR, \fBregister\fR, \fBregisterError\fR, \fBreset\fR, \fBunregister\fR, and \fBwait\fR. +.PP +It does not export the commands \fBcleanup\fR, \fBcode\fR, \fBdata\fR, \fBerror\fR, \fBmeta\fR, \fBncode\fR, \fBsize\fR, or \fBstatus\fR. .BE .SH DESCRIPTION .PP -- cgit v0.12 From a96ca020dfbf40d8a61669620d17c5a1e455a99a Mon Sep 17 00:00:00 2001 From: kjnash Date: Wed, 11 May 2022 18:25:55 +0000 Subject: Revise library/http/http.tcl to fix shift_jis typo and #6898f9cb71 --- library/http/http.tcl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/http/http.tcl b/library/http/http.tcl index e754264..838fbee 100644 --- a/library/http/http.tcl +++ b/library/http/http.tcl @@ -3479,7 +3479,7 @@ proc http::CharsetToEncoding {charset} { set encoding "iso8859-$num" } elseif {[regexp {iso-?2022-(jp|kr)} $charset -> ext]} { set encoding "iso2022-$ext" - } elseif {[regexp {shift[-_]?js} $charset]} { + } elseif {[regexp {shift[-_]?jis} $charset]} { set encoding "shiftjis" } elseif {[regexp {(?:windows|cp)-?([0-9]+)} $charset -> num]} { set encoding "cp$num" -- cgit v0.12 From b9ef9f9cefccc2ef851149acbd14c280dd70e622 Mon Sep 17 00:00:00 2001 From: kjnash Date: Wed, 11 May 2022 18:48:20 +0000 Subject: Revise http(n) to fix #14e3c258d9 --- doc/http.n | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/doc/http.n b/doc/http.n index c4a8688..47ed057 100644 --- a/doc/http.n +++ b/doc/http.n @@ -341,12 +341,20 @@ otherwise complain about HTTP/1.1. \fB\-query\fR \fIquery\fR . This flag (if the value is non-empty) causes \fB::http::geturl\fR to do a -POST request that passes the -\fIquery\fR as payload verbatim to the server. -The content format (and encoding) of \fIquery\fR is announced by the header -field \fBcontent-type\fR set by the option \fB-type\fR. -\fIquery\fR is an x-url-encoding formatted query, if used for html forms. -The \fB::http::formatQuery\fR procedure can be used to do the formatting. +POST request that passes the string +\fIquery\fR verbatim to the server as the request payload. +The content format (and encoding) of \fIquery\fR is announced by the request +header \fBContent-Type\fR which is set by the option \fB-type\fR. Any value +of \fB-type\fR is permitted, and it is the responsibility of the caller to +supply \fIquery\fR in the correct format. +.RS +.PP +If \fB-type\fR is not specified, it defaults to +\fIapplication/x-www-form-urlencoded\fR, which requires \fIquery\fR to be an +x-url-encoding formatted query-string (this \fB-type\fR and query format are +used in a POST submitted from an html form). The \fB::http::formatQuery\fR +procedure can be used to do the formatting. +.RE .TP \fB\-queryblocksize\fR \fIsize\fR . -- cgit v0.12 From 355490c37c7a596e846ffeb26c4d82f2dfed9d37 Mon Sep 17 00:00:00 2001 From: kjnash Date: Wed, 11 May 2022 19:05:33 +0000 Subject: Revise http(n) to fix #6afa947d1a --- doc/http.n | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/doc/http.n b/doc/http.n index 47ed057..b5197a9 100644 --- a/doc/http.n +++ b/doc/http.n @@ -306,8 +306,16 @@ multiple requests. Default is 0. \fB\-method\fR \fItype\fR . Force the HTTP request method to \fItype\fR. \fB::http::geturl\fR will -auto-select GET, POST or HEAD based on other options, but this option -enables choices like PUT and DELETE for webdav support. +auto-select GET, POST or HEAD based on other options, but this option overrides +that selection and enables choices like PUT and DELETE for WebDAV support. +.RS +.PP +It is the caller's responsibility to ensure that the headers and request body +(if any) conform to the requirements of the request method. For example, if +using \fB\-method\fR \fIPOST\fR to send a POST with an empty request body, the +caller must also supply the option +.QW "-headers {Content-Length 0}" . +.RE .TP \fB\-myaddr\fR \fIaddress\fR . -- cgit v0.12 From b68a248552b95b41779deac3bb98023718502216 Mon Sep 17 00:00:00 2001 From: kjnash Date: Wed, 11 May 2022 20:00:48 +0000 Subject: In http(n), escape - to \- in all command options except example code. --- doc/http.n | 62 +++++++++++++++++++++++++++++++------------------------------- 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/doc/http.n b/doc/http.n index b5197a9..89af32f 100644 --- a/doc/http.n +++ b/doc/http.n @@ -84,7 +84,7 @@ must be active. In Tk applications this is always true. For pure-Tcl applications, the caller can use \fB::http::wait\fR after calling \fB::http::geturl\fR to start the event loop. .PP -\fBNote:\fR The event queue is even used without the \fB-command\fR option. +\fBNote:\fR The event queue is even used without the \fB\-command\fR option. As a side effect, arbitrary commands may be processed while \fBhttp::geturl\fR is running. .SH COMMANDS .TP @@ -116,7 +116,7 @@ is 1. \fB\-postfresh\fR \fIboolean\fR . Specifies whether requests that use the \fBPOST\fR method will always use a -fresh socket, overriding the \fB-keepalive\fR option of +fresh socket, overriding the \fB\-keepalive\fR option of command \fBhttp::geturl\fR. See the \fBPERSISTENT SOCKETS\fR section for details. The default is 0. .TP @@ -142,7 +142,7 @@ an empty list. The default filter returns the values of the non-empty. .RS .PP -The \fB::http::geturl\fR command runs the \fB-proxyfilter\fR callback inside +The \fB::http::geturl\fR command runs the \fB\-proxyfilter\fR callback inside a \fBcatch\fR command. Therefore an error in the callback command does not call the \fBbgerror\fR handler. See the \fBERRORS\fR section for details. @@ -187,7 +187,7 @@ If the value is boolean \fBtrue\fR, then by default requests will send a header .QW "\fBAccept-Encoding: gzip,deflate,compress\fR" . If the value is boolean \fBfalse\fR, then by default this header will not be sent. In either case the default can be overridden for an individual request by -supplying a custom \fBAccept-Encoding\fR header in the \fB-headers\fR option +supplying a custom \fBAccept-Encoding\fR header in the \fB\-headers\fR option of \fBhttp::geturl\fR. The default is 1. .RE .TP @@ -241,7 +241,7 @@ proc httpCallback {token} { } .CE .PP -The \fB::http::geturl\fR command runs the \fB-command\fR callback inside +The \fB::http::geturl\fR command runs the \fB\-command\fR callback inside a \fBcatch\fR command. Therefore an error in the callback command does not call the \fBbgerror\fR handler. See the \fBERRORS\fR section for details. @@ -271,11 +271,11 @@ proc httpHandlerCallback {socket token} { } .CE .PP -The \fBhttp::geturl\fR code for the \fB-handler\fR option is not compatible with either compression or chunked transfer-encoding. If \fB-handler\fR is specified, then to work around these issues \fBhttp::geturl\fR will reduce the HTTP protocol to 1.0, and override the \fB-zip\fR option (i.e. it will not send the header "\fBAccept-Encoding: gzip,deflate,compress\fR"). +The \fBhttp::geturl\fR code for the \fB\-handler\fR option is not compatible with either compression or chunked transfer-encoding. If \fB\-handler\fR is specified, then to work around these issues \fBhttp::geturl\fR will reduce the HTTP protocol to 1.0, and override the \fB\-zip\fR option (i.e. it will not send the header "\fBAccept-Encoding: gzip,deflate,compress\fR"). .PP -If options \fB-handler\fR and \fB-channel\fR are used together, the handler is responsible for copying the data from the HTTP socket to the specified channel. The name of the channel is available to the handler as element \fB-channel\fR of the token array. +If options \fB\-handler\fR and \fB\-channel\fR are used together, the handler is responsible for copying the data from the HTTP socket to the specified channel. The name of the channel is available to the handler as element \fB\-channel\fR of the token array. .PP -The \fB::http::geturl\fR command runs the \fB-handler\fR callback inside +The \fB::http::geturl\fR command runs the \fB\-handler\fR callback inside a \fBcatch\fR command. Therefore an error in the callback command does not call the \fBbgerror\fR handler. See the \fBERRORS\fR section for details. @@ -314,7 +314,7 @@ It is the caller's responsibility to ensure that the headers and request body (if any) conform to the requirements of the request method. For example, if using \fB\-method\fR \fIPOST\fR to send a POST with an empty request body, the caller must also supply the option -.QW "-headers {Content-Length 0}" . +.QW "\-headers {Content-Length 0}" . .RE .TP \fB\-myaddr\fR \fIaddress\fR @@ -352,14 +352,14 @@ This flag (if the value is non-empty) causes \fB::http::geturl\fR to do a POST request that passes the string \fIquery\fR verbatim to the server as the request payload. The content format (and encoding) of \fIquery\fR is announced by the request -header \fBContent-Type\fR which is set by the option \fB-type\fR. Any value -of \fB-type\fR is permitted, and it is the responsibility of the caller to +header \fBContent-Type\fR which is set by the option \fB\-type\fR. Any value +of \fB\-type\fR is permitted, and it is the responsibility of the caller to supply \fIquery\fR in the correct format. .RS .PP -If \fB-type\fR is not specified, it defaults to +If \fB\-type\fR is not specified, it defaults to \fIapplication/x-www-form-urlencoded\fR, which requires \fIquery\fR to be an -x-url-encoding formatted query-string (this \fB-type\fR and query format are +x-url-encoding formatted query-string (this \fB\-type\fR and query format are used in a POST submitted from an html form). The \fB::http::formatQuery\fR procedure can be used to do the formatting. .RE @@ -561,8 +561,8 @@ to know the result of the asynchronous HTTP request, it can call \fB::http::wait\fR and then check status and error, just as the callback does. .PP -The \fB::http::geturl\fR command runs the \fB-command\fR, \fB-handler\fR, -and \fB-proxyfilter\fR callbacks inside a \fBcatch\fR command. Therefore +The \fB::http::geturl\fR command runs the \fB\-command\fR, \fB\-handler\fR, +and \fB\-proxyfilter\fR callbacks inside a \fBcatch\fR command. Therefore an error in the callback command does not call the \fBbgerror\fR handler. When debugging one of these callbacks, it may be convenient to report errors by using a @@ -751,9 +751,9 @@ whether the server was modified by the failed POST request, before sending the same request again. .PP A HTTP request will use a persistent socket if the call to -\fBhttp::geturl\fR has the option \fB-keepalive true\fR. It will use +\fBhttp::geturl\fR has the option \fB\-keepalive true\fR. It will use pipelining where permitted if the \fBhttp::config\fR option -\fB-pipeline\fR is boolean \fBtrue\fR (its default value). +\fB\-pipeline\fR is boolean \fBtrue\fR (its default value). .PP The http package maintains no more than one persistent connection to each server (i.e. each value of @@ -775,7 +775,7 @@ In accordance with RFC 7230, \fBhttp::geturl\fR does not pipeline requests that use the POST method. If a POST uses a persistent connection and is not the first request on that connection, \fBhttp::geturl\fR waits until it has received the response for the previous -request; or (if \fBhttp::config\fR option \fB-postfresh\fR is boolean \fBtrue\fR) it +request; or (if \fBhttp::config\fR option \fB\-postfresh\fR is boolean \fBtrue\fR) it uses a new connection for each POST. .PP If the server is processing a number of pipelined requests, and sends a @@ -796,7 +796,7 @@ GET requests, \fBhttp::geturl\fR opens another connection and retransmits the failed request. However, if the request was a POST, RFC 7230 forbids automatic retry by default, suggesting either user confirmation, or confirmation by user-agent software that has semantic understanding of -the application. The \fBhttp::config\fR option \fB-repost\fR allows for +the application. The \fBhttp::config\fR option \fB\-repost\fR allows for either possibility. .PP Asynchronous close events can occur only in a short interval of time. The @@ -804,16 +804,16 @@ Asynchronous close events can occur only in a short interval of time. The server. Upon detection, the connection is also closed at the client end, and subsequent requests will use a fresh connection. .PP -If the \fBhttp::geturl\fR command is called with option \fB-keepalive true\fR, +If the \fBhttp::geturl\fR command is called with option \fB\-keepalive true\fR, then it will both try to use an existing persistent connection (if one is available), and it will send the server a .QW "\fBConnection: keep-alive\fR" request header asking to keep the connection open for future requests. .PP -The \fBhttp::config\fR options \fB-pipeline\fR, \fB-postfresh\fR, and -\fB-repost\fR relate to persistent connections. +The \fBhttp::config\fR options \fB\-pipeline\fR, \fB\-postfresh\fR, and +\fB\-repost\fR relate to persistent connections. .PP -Option \fB-pipeline\fR, if boolean \fBtrue\fR, will pipeline GET and HEAD requests +Option \fB\-pipeline\fR, if boolean \fBtrue\fR, will pipeline GET and HEAD requests made over a persistent connection. POST requests will not be pipelined - if the POST is not the first transaction on the connection, its request will not @@ -821,15 +821,15 @@ be sent until the previous response has finished. GET and HEAD requests made after a POST will not be sent until the POST response has been delivered, and will not be sent if the POST fails. .PP -Option \fB-postfresh\fR, if boolean \fBtrue\fR, will override the \fBhttp::geturl\fR option -\fB-keepalive\fR, and always open a fresh connection for a POST request. +Option \fB\-postfresh\fR, if boolean \fBtrue\fR, will override the \fBhttp::geturl\fR option +\fB\-keepalive\fR, and always open a fresh connection for a POST request. .PP -Option \fB-repost\fR, if \fBtrue\fR, permits automatic retry of a POST request +Option \fB\-repost\fR, if \fBtrue\fR, permits automatic retry of a POST request that fails because it uses a persistent connection that the server has half-closed (an .QW "asynchronous close event" ). Subsequent GET and HEAD requests in a failed pipeline will also be retried. -\fIThe -repost option should be used only if the application understands +\fIThe \-repost option should be used only if the application understands that the retry is appropriate\fR - specifically, the application must know that if the failed POST successfully modified the state of the server, a repeat POST would have no adverse effect. @@ -841,12 +841,12 @@ that the client wishes to change the protocol used over the existing connection higher version of the HTTP protocol (HTTP 2 or 3), or TLS encryption. If the server accepts the upgrade request, its response code will be 101. .PP -To request a protocol upgrade when calling \fBhttp::geturl\fR, the \fB-headers\fR +To request a protocol upgrade when calling \fBhttp::geturl\fR, the \fB\-headers\fR option must supply appropriate values for \fBConnection\fR and \fBUpgrade\fR, and -the \fB-command\fR option must supply a command that implements the requested +the \fB\-command\fR option must supply a command that implements the requested protocol and can also handle the server response if the server refuses the protocol upgrade. For upgrade requests \fBhttp::geturl\fR ignores the value of -option \fB-keepalive\fR, and always uses the value \fB0\fR so that the upgrade +option \fB\-keepalive\fR, and always uses the value \fB0\fR so that the upgrade request is not made over a connection that is intended for multiple HTTP requests. .PP The Tcllib library \fBwebsocket\fR implements WebSockets, and makes the necessary @@ -902,7 +902,7 @@ proc httpcopy { url file {chunk 4096} } { return $token } proc httpCopyProgress {args} { - puts -nonewline stderr . + puts \-nonewline stderr . flush stderr } .CE -- cgit v0.12 From 511688085318c6f4a765786b9ea88a8f77861d6c Mon Sep 17 00:00:00 2001 From: kjnash Date: Wed, 11 May 2022 20:08:57 +0000 Subject: In http(n), repaginate long lines. --- doc/http.n | 51 ++++++++++++++++++++++++++++++++------------------- 1 file changed, 32 insertions(+), 19 deletions(-) diff --git a/doc/http.n b/doc/http.n index 89af32f..9617934 100644 --- a/doc/http.n +++ b/doc/http.n @@ -51,9 +51,12 @@ http \- Client-side implementation of the HTTP/1.1 protocol \fB::http::unregister \fIproto\fR .SH "EXPORTED COMMANDS" .PP -Namespace \fBhttp\fR exports the commands \fBconfig\fR, \fBformatQuery\fR, \fBgeturl\fR, \fBquoteString\fR, \fBregister\fR, \fBregisterError\fR, \fBreset\fR, \fBunregister\fR, and \fBwait\fR. +Namespace \fBhttp\fR exports the commands \fBconfig\fR, \fBformatQuery\fR, +\fBgeturl\fR, \fBquoteString\fR, \fBregister\fR, \fBregisterError\fR, +\fBreset\fR, \fBunregister\fR, and \fBwait\fR. .PP -It does not export the commands \fBcleanup\fR, \fBcode\fR, \fBdata\fR, \fBerror\fR, \fBmeta\fR, \fBncode\fR, \fBsize\fR, or \fBstatus\fR. +It does not export the commands \fBcleanup\fR, \fBcode\fR, \fBdata\fR, +\fBerror\fR, \fBmeta\fR, \fBncode\fR, \fBsize\fR, or \fBstatus\fR. .BE .SH DESCRIPTION .PP @@ -85,7 +88,8 @@ applications, the caller can use \fB::http::wait\fR after calling \fB::http::geturl\fR to start the event loop. .PP \fBNote:\fR The event queue is even used without the \fB\-command\fR option. -As a side effect, arbitrary commands may be processed while \fBhttp::geturl\fR is running. +As a side effect, arbitrary commands may be processed while \fBhttp::geturl\fR +is running. .SH COMMANDS .TP \fB::http::config\fR ?\fIoptions\fR? @@ -117,8 +121,8 @@ is 1. . Specifies whether requests that use the \fBPOST\fR method will always use a fresh socket, overriding the \fB\-keepalive\fR option of -command \fBhttp::geturl\fR. See the \fBPERSISTENT SOCKETS\fR section for details. -The default is 0. +command \fBhttp::geturl\fR. See the \fBPERSISTENT SOCKETS\fR section for +details. The default is 0. .TP \fB\-proxyhost\fR \fIhostname\fR . @@ -185,8 +189,8 @@ numbers of \fBhttp\fR and \fBTcl\fR. . If the value is boolean \fBtrue\fR, then by default requests will send a header .QW "\fBAccept-Encoding: gzip,deflate,compress\fR" . -If the value is boolean \fBfalse\fR, then by default this header will not be sent. -In either case the default can be overridden for an individual request by +If the value is boolean \fBfalse\fR, then by default this header will not be +sent. In either case the default can be overridden for an individual request by supplying a custom \fBAccept-Encoding\fR header in the \fB\-headers\fR option of \fBhttp::geturl\fR. The default is 1. .RE @@ -271,9 +275,16 @@ proc httpHandlerCallback {socket token} { } .CE .PP -The \fBhttp::geturl\fR code for the \fB\-handler\fR option is not compatible with either compression or chunked transfer-encoding. If \fB\-handler\fR is specified, then to work around these issues \fBhttp::geturl\fR will reduce the HTTP protocol to 1.0, and override the \fB\-zip\fR option (i.e. it will not send the header "\fBAccept-Encoding: gzip,deflate,compress\fR"). +The \fBhttp::geturl\fR code for the \fB\-handler\fR option is not compatible +with either compression or chunked transfer-encoding. If \fB\-handler\fR is +specified, then to work around these issues \fBhttp::geturl\fR will reduce the +HTTP protocol to 1.0, and override the \fB\-zip\fR option (i.e. it will not +send the header "\fBAccept-Encoding: gzip,deflate,compress\fR"). .PP -If options \fB\-handler\fR and \fB\-channel\fR are used together, the handler is responsible for copying the data from the HTTP socket to the specified channel. The name of the channel is available to the handler as element \fB\-channel\fR of the token array. +If options \fB\-handler\fR and \fB\-channel\fR are used together, the handler +is responsible for copying the data from the HTTP socket to the specified +channel. The name of the channel is available to the handler as element +\fB\-channel\fR of the token array. .PP The \fB::http::geturl\fR command runs the \fB\-handler\fR callback inside a \fBcatch\fR command. Therefore an error in the callback command does @@ -639,7 +650,8 @@ if the HTTP response is text. \fBbody\fR . The contents of the URL. This will be empty if the \fB\-channel\fR -option has been specified. This value is returned by the \fB::http::data\fR command. +option has been specified. This value is returned by the \fB::http::data\fR +command. .TP \fBcharset\fR . @@ -775,8 +787,8 @@ In accordance with RFC 7230, \fBhttp::geturl\fR does not pipeline requests that use the POST method. If a POST uses a persistent connection and is not the first request on that connection, \fBhttp::geturl\fR waits until it has received the response for the previous -request; or (if \fBhttp::config\fR option \fB\-postfresh\fR is boolean \fBtrue\fR) it -uses a new connection for each POST. +request; or (if \fBhttp::config\fR option \fB\-postfresh\fR is boolean +\fBtrue\fR) it uses a new connection for each POST. .PP If the server is processing a number of pipelined requests, and sends a response header @@ -813,16 +825,17 @@ request header asking to keep the connection open for future requests. The \fBhttp::config\fR options \fB\-pipeline\fR, \fB\-postfresh\fR, and \fB\-repost\fR relate to persistent connections. .PP -Option \fB\-pipeline\fR, if boolean \fBtrue\fR, will pipeline GET and HEAD requests -made -over a persistent connection. POST requests will not be pipelined - if the +Option \fB\-pipeline\fR, if boolean \fBtrue\fR, will pipeline GET and HEAD +requests made over a persistent connection. POST requests will not be +pipelined - if the POST is not the first transaction on the connection, its request will not be sent until the previous response has finished. GET and HEAD requests made after a POST will not be sent until the POST response has been delivered, and will not be sent if the POST fails. .PP -Option \fB\-postfresh\fR, if boolean \fBtrue\fR, will override the \fBhttp::geturl\fR option -\fB\-keepalive\fR, and always open a fresh connection for a POST request. +Option \fB\-postfresh\fR, if boolean \fBtrue\fR, will override the +\fBhttp::geturl\fR option \fB\-keepalive\fR, and always open a fresh connection +for a POST request. .PP Option \fB\-repost\fR, if \fBtrue\fR, permits automatic retry of a POST request that fails because it uses a persistent connection that the server has @@ -831,8 +844,8 @@ half-closed (an Subsequent GET and HEAD requests in a failed pipeline will also be retried. \fIThe \-repost option should be used only if the application understands that the retry is appropriate\fR - specifically, the application must know -that if the failed POST successfully modified the state of the server, a repeat POST -would have no adverse effect. +that if the failed POST successfully modified the state of the server, a repeat +POST would have no adverse effect. .SH "PROTOCOL UPGRADES" .PP The HTTP/1.1 \fBConnection\fR and \fBUpgrade\fR client headers inform the server -- cgit v0.12 From ded51e0c9087a9fe17500b24f7f5fb1ec2171aa2 Mon Sep 17 00:00:00 2001 From: kjnash Date: Fri, 13 May 2022 22:49:06 +0000 Subject: Correction to http(n) - cannot use Upgrade header to upgrade to http/3 --- doc/http.n | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/http.n b/doc/http.n index 9617934..c3ce165 100644 --- a/doc/http.n +++ b/doc/http.n @@ -851,7 +851,7 @@ POST would have no adverse effect. The HTTP/1.1 \fBConnection\fR and \fBUpgrade\fR client headers inform the server that the client wishes to change the protocol used over the existing connection (RFC 7230). This mechanism can be used to request a WebSocket (RFC 6455), a -higher version of the HTTP protocol (HTTP 2 or 3), or TLS encryption. If the +higher version of the HTTP protocol (HTTP 2), or TLS encryption. If the server accepts the upgrade request, its response code will be 101. .PP To request a protocol upgrade when calling \fBhttp::geturl\fR, the \fB\-headers\fR @@ -865,7 +865,7 @@ request is not made over a connection that is intended for multiple HTTP request The Tcllib library \fBwebsocket\fR implements WebSockets, and makes the necessary calls to commands in the \fBhttp\fR package. .PP -There is currently no native Tcl client library for HTTP/2 or HTTP/3. +There is currently no native Tcl client library for HTTP/2. .PP The \fBUpgrade\fR mechanism is not used to request TLS in web browsers, because \fBhttp\fR and \fBhttps\fR are served over different ports. It is used by -- cgit v0.12