From dd74a6dd34074dfc672c55f49047a71befdc733e Mon Sep 17 00:00:00 2001 From: Tatsuhiro Tsujikawa Date: Sun, 2 Sep 2018 14:59:38 +0900 Subject: [PATCH] Update manual pages --- doc/h2load.1 | 2 +- doc/nghttp.1 | 2 +- doc/nghttpd.1 | 2 +- doc/nghttpx.1 | 58 ++++++++++++++++++++++++++++++++++++----------- doc/nghttpx.1.rst | 55 ++++++++++++++++++++++++++++++++++---------- 5 files changed, 91 insertions(+), 28 deletions(-) diff --git a/doc/h2load.1 b/doc/h2load.1 index c6a77781..ed791f12 100644 --- a/doc/h2load.1 +++ b/doc/h2load.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "H2LOAD" "1" "May 08, 2018" "1.32.0" "nghttp2" +.TH "H2LOAD" "1" "Sep 02, 2018" "1.33.0-DEV" "nghttp2" .SH NAME h2load \- HTTP/2 benchmarking tool . diff --git a/doc/nghttp.1 b/doc/nghttp.1 index 2c0e4539..992fa5fd 100644 --- a/doc/nghttp.1 +++ b/doc/nghttp.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "NGHTTP" "1" "May 08, 2018" "1.32.0" "nghttp2" +.TH "NGHTTP" "1" "Sep 02, 2018" "1.33.0-DEV" "nghttp2" .SH NAME nghttp \- HTTP/2 client . diff --git a/doc/nghttpd.1 b/doc/nghttpd.1 index dd40eedf..5a5ecf84 100644 --- a/doc/nghttpd.1 +++ b/doc/nghttpd.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "NGHTTPD" "1" "May 08, 2018" "1.32.0" "nghttp2" +.TH "NGHTTPD" "1" "Sep 02, 2018" "1.33.0-DEV" "nghttp2" .SH NAME nghttpd \- HTTP/2 server . diff --git a/doc/nghttpx.1 b/doc/nghttpx.1 index c90167cc..c966cb06 100644 --- a/doc/nghttpx.1 +++ b/doc/nghttpx.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "NGHTTPX" "1" "May 08, 2018" "1.32.0" "nghttp2" +.TH "NGHTTPX" "1" "Sep 02, 2018" "1.33.0-DEV" "nghttp2" .SH NAME nghttpx \- HTTP/2 proxy . @@ -137,12 +137,13 @@ Several parameters are accepted after . The parameters are delimited by ";". The available parameters are: "proto=", "tls", "sni=", "fall=", "rise=", -"affinity=", "dns", and "redirect\-if\-not\-tls". -The parameter consists of keyword, and optionally -followed by "=" and value. For example, the parameter -"proto=h2" consists of the keyword "proto" and value -"h2". The parameter "tls" consists of the keyword "tls" -without value. Each parameter is described as follows. +"affinity=", "dns", "redirect\-if\-not\-tls", +"upgrade\-scheme", and "mruby=". The parameter +consists of keyword, and optionally followed by "=" and +value. For example, the parameter "proto=h2" consists +of the keyword "proto" and value "h2". The parameter +"tls" consists of the keyword "tls" without value. Each +parameter is described as follows. .sp The backend application protocol can be specified using optional "proto" parameter, and in the form of @@ -235,6 +236,11 @@ particular backend. This is a workaround for a backend server which requires "https" :scheme pseudo header field on TLS encrypted connection. .sp +"mruby=" parameter specifies a path to mruby +script file which is invoked when this pattern is +matched. All backends which share the same pattern must +have the same mruby path. +.sp Since ";" and ":" are used as delimiter, must not contain these characters. Since ";" has special meaning in shell, the option value must be quoted. @@ -1577,6 +1583,13 @@ signal handling feature is disabled. .B \-\-mruby\-file= Set mruby script file .UNINDENT +.INDENT 0.0 +.TP +.B \-\-ignore\-per\-pattern\-mruby\-error +Ignore mruby compile error for per\-pattern mruby script +file. If error occurred, it is treated as if no mruby +file were specified for the pattern. +.UNINDENT .SS Misc .INDENT 0.0 .TP @@ -1934,9 +1947,28 @@ server. These hooks allows users to modify header fields, or common HTTP variables, like authority or request path, and even return custom response without forwarding request to backend servers. .sp -To specify mruby script file, use \fI\%\-\-mruby\-file\fP option. The -script will be evaluated once per thread on startup, and it must -instantiate object and evaluate it as the return value (e.g., +There are 2 levels of mruby script invocations: global and +per\-pattern. The global mruby script is set by \fI\%\-\-mruby\-file\fP +option and is called for all requests. The per\-pattern mruby script +is set by "mruby" parameter in \fI\%\-b\fP option. It is invoked for +a request which matches the particular pattern. The order of hook +invocation is: global request phase hook, per\-pattern request phase +hook, per\-pattern response phase hook, and finally global response +phase hook. If a hook returns a response, any later hooks are not +invoked. The global request hook is invoked before the pattern +matching is made and changing request path may affect the pattern +matching. +.sp +Please note that request and response hooks of per\-pattern mruby +script for a single request might not come from the same script. This +might happen after a request hook is executed, backend failed for some +reason, and at the same time, backend configuration is replaced by API +request, and then the request uses new configuration on retry. The +response hook from new configuration, if it is specified, will be +invoked. +.sp +The all mruby script will be evaluated once per thread on startup, and +it must instantiate object and evaluate it as the return value (e.g., \fBApp.new\fP). This object is called app object. If app object defines \fBon_req\fP method, it is called with \fI\%Nghttpx::Env\fP object on request hook. Similarly, if app object defines \fBon_resp\fP @@ -2224,10 +2256,10 @@ to the backend, and response phase hook for this request will not be invoked. When this method is called in response phase hook, response from backend server is canceled and discarded. The status code and response header fields should be set -before using this method. To set status code, use :rb:meth To -set response header fields, use +before using this method. To set status code, use \fI\%Nghttpx::Response#status\fP\&. If status code is not -set, 200 is used. \fI\%Nghttpx::Response#add_header\fP and +set, 200 is used. To set response header fields, +\fI\%Nghttpx::Response#add_header\fP and \fI\%Nghttpx::Response#set_header\fP\&. When this method is invoked in response phase hook, the response headers are filled with the ones received from backend server. To send diff --git a/doc/nghttpx.1.rst b/doc/nghttpx.1.rst index d040cbf6..dedf4c56 100644 --- a/doc/nghttpx.1.rst +++ b/doc/nghttpx.1.rst @@ -121,12 +121,13 @@ Connections The parameters are delimited by ";". The available parameters are: "proto=", "tls", "sni=", "fall=", "rise=", - "affinity=", "dns", and "redirect-if-not-tls". - The parameter consists of keyword, and optionally - followed by "=" and value. For example, the parameter - "proto=h2" consists of the keyword "proto" and value - "h2". The parameter "tls" consists of the keyword "tls" - without value. Each parameter is described as follows. + "affinity=", "dns", "redirect-if-not-tls", + "upgrade-scheme", and "mruby=". The parameter + consists of keyword, and optionally followed by "=" and + value. For example, the parameter "proto=h2" consists + of the keyword "proto" and value "h2". The parameter + "tls" consists of the keyword "tls" without value. Each + parameter is described as follows. The backend application protocol can be specified using optional "proto" parameter, and in the form of @@ -219,6 +220,11 @@ Connections server which requires "https" :scheme pseudo header field on TLS encrypted connection. + "mruby=" parameter specifies a path to mruby + script file which is invoked when this pattern is + matched. All backends which share the same pattern must + have the same mruby path. + Since ";" and ":" are used as delimiter, must not contain these characters. Since ";" has special meaning in shell, the option value must be quoted. @@ -1439,6 +1445,12 @@ Scripting Set mruby script file +.. option:: --ignore-per-pattern-mruby-error + + Ignore mruby compile error for per-pattern mruby script + file. If error occurred, it is treated as if no mruby + file were specified for the pattern. + Misc ~~~~ @@ -1777,9 +1789,28 @@ server. These hooks allows users to modify header fields, or common HTTP variables, like authority or request path, and even return custom response without forwarding request to backend servers. -To specify mruby script file, use :option:`--mruby-file` option. The -script will be evaluated once per thread on startup, and it must -instantiate object and evaluate it as the return value (e.g., +There are 2 levels of mruby script invocations: global and +per-pattern. The global mruby script is set by :option:`--mruby-file` +option and is called for all requests. The per-pattern mruby script +is set by "mruby" parameter in :option:`-b` option. It is invoked for +a request which matches the particular pattern. The order of hook +invocation is: global request phase hook, per-pattern request phase +hook, per-pattern response phase hook, and finally global response +phase hook. If a hook returns a response, any later hooks are not +invoked. The global request hook is invoked before the pattern +matching is made and changing request path may affect the pattern +matching. + +Please note that request and response hooks of per-pattern mruby +script for a single request might not come from the same script. This +might happen after a request hook is executed, backend failed for some +reason, and at the same time, backend configuration is replaced by API +request, and then the request uses new configuration on retry. The +response hook from new configuration, if it is specified, will be +invoked. + +The all mruby script will be evaluated once per thread on startup, and +it must instantiate object and evaluate it as the return value (e.g., ``App.new``). This object is called app object. If app object defines ``on_req`` method, it is called with :rb:class:`Nghttpx::Env` object on request hook. Similarly, if app object defines ``on_resp`` @@ -2026,10 +2057,10 @@ respectively. not be invoked. When this method is called in response phase hook, response from backend server is canceled and discarded. The status code and response header fields should be set - before using this method. To set status code, use :rb:meth To - set response header fields, use + before using this method. To set status code, use :rb:attr:`Nghttpx::Response#status`. If status code is not - set, 200 is used. :rb:meth:`Nghttpx::Response#add_header` and + set, 200 is used. To set response header fields, + :rb:meth:`Nghttpx::Response#add_header` and :rb:meth:`Nghttpx::Response#set_header`. When this method is invoked in response phase hook, the response headers are filled with the ones received from backend server. To send