Update man pages
This commit is contained in:
Tatsuhiro Tsujikawa
parent
c30d252f94
commit
231db4a3e6
20
doc/h2load.1
20
doc/h2load.1
|
|
@ -1,6 +1,6 @@
|
||||||
.\" Man page generated from reStructuredText.
|
.\" Man page generated from reStructuredText.
|
||||||
.
|
.
|
||||||
.TH "H2LOAD" "1" "August 30, 2015" "1.3.0" "nghttp2"
|
.TH "H2LOAD" "1" "September 06, 2015" "1.3.1-DEV" "nghttp2"
|
||||||
.SH NAME
|
.SH NAME
|
||||||
h2load \- HTTP/2 benchmarking tool
|
h2load \- HTTP/2 benchmarking tool
|
||||||
.
|
.
|
||||||
|
|
@ -185,15 +185,15 @@ indefinitely, waiting for a response.
|
||||||
Path of a file containing one or more lines separated by
|
Path of a file containing one or more lines separated by
|
||||||
EOLs. Each script line is composed of two tab\-separated
|
EOLs. Each script line is composed of two tab\-separated
|
||||||
fields. The first field represents the time offset from
|
fields. The first field represents the time offset from
|
||||||
the start of execution, expressed as milliseconds with
|
the start of execution, expressed as a positive value of
|
||||||
microsecond resolution. The second field represents the
|
milliseconds with microsecond resolution. The second
|
||||||
URI. This option will disable URIs getting from
|
field represents the URI. This option will disable URIs
|
||||||
command\-line. If \(aq\-\(aq is given as <PATH>, script lines
|
getting from command\-line. If \(aq\-\(aq is given as <PATH>,
|
||||||
will be read from stdin. Script lines are used in order
|
script lines will be read from stdin. Script lines are
|
||||||
for each client. If \fI\%\-n\fP is given, it must be less than
|
used in order for each client. If \fI\%\-n\fP is given, it must be
|
||||||
or equal to the number of script lines, larger values are
|
less than or equal to the number of script lines, larger
|
||||||
clamped to the number of script lines. If \fI\%\-n\fP is
|
values are clamped to the number of script lines. If \fI\%\-n\fP
|
||||||
not given, the number of requests will default to the
|
is not given, the number of requests will default to the
|
||||||
number of script lines. The scheme, host and port defined
|
number of script lines. The scheme, host and port defined
|
||||||
in the first URI are used solely. Values contained in
|
in the first URI are used solely. Values contained in
|
||||||
other URIs, if present, are ignored. Definition of a
|
other URIs, if present, are ignored. Definition of a
|
||||||
|
|
|
||||||
|
|
@ -150,15 +150,15 @@ OPTIONS
|
||||||
Path of a file containing one or more lines separated by
|
Path of a file containing one or more lines separated by
|
||||||
EOLs. Each script line is composed of two tab-separated
|
EOLs. Each script line is composed of two tab-separated
|
||||||
fields. The first field represents the time offset from
|
fields. The first field represents the time offset from
|
||||||
the start of execution, expressed as milliseconds with
|
the start of execution, expressed as a positive value of
|
||||||
microsecond resolution. The second field represents the
|
milliseconds with microsecond resolution. The second
|
||||||
URI. This option will disable URIs getting from
|
field represents the URI. This option will disable URIs
|
||||||
command-line. If '-' is given as <PATH>, script lines
|
getting from command-line. If '-' is given as <PATH>,
|
||||||
will be read from stdin. Script lines are used in order
|
script lines will be read from stdin. Script lines are
|
||||||
for each client. If :option:`-n` is given, it must be less than
|
used in order for each client. If :option:`-n` is given, it must be
|
||||||
or equal to the number of script lines, larger values are
|
less than or equal to the number of script lines, larger
|
||||||
clamped to the number of script lines. If :option:`-n` is
|
values are clamped to the number of script lines. If :option:`-n`
|
||||||
not given, the number of requests will default to the
|
is not given, the number of requests will default to the
|
||||||
number of script lines. The scheme, host and port defined
|
number of script lines. The scheme, host and port defined
|
||||||
in the first URI are used solely. Values contained in
|
in the first URI are used solely. Values contained in
|
||||||
other URIs, if present, are ignored. Definition of a
|
other URIs, if present, are ignored. Definition of a
|
||||||
|
|
|
||||||
|
|
@ -1,6 +1,6 @@
|
||||||
.\" Man page generated from reStructuredText.
|
.\" Man page generated from reStructuredText.
|
||||||
.
|
.
|
||||||
.TH "NGHTTP" "1" "August 30, 2015" "1.3.0" "nghttp2"
|
.TH "NGHTTP" "1" "September 06, 2015" "1.3.1-DEV" "nghttp2"
|
||||||
.SH NAME
|
.SH NAME
|
||||||
nghttp \- HTTP/2 experimental client
|
nghttp \- HTTP/2 experimental client
|
||||||
.
|
.
|
||||||
|
|
|
||||||
|
|
@ -1,6 +1,6 @@
|
||||||
.\" Man page generated from reStructuredText.
|
.\" Man page generated from reStructuredText.
|
||||||
.
|
.
|
||||||
.TH "NGHTTPD" "1" "August 30, 2015" "1.3.0" "nghttp2"
|
.TH "NGHTTPD" "1" "September 06, 2015" "1.3.1-DEV" "nghttp2"
|
||||||
.SH NAME
|
.SH NAME
|
||||||
nghttpd \- HTTP/2 experimental server
|
nghttpd \- HTTP/2 experimental server
|
||||||
.
|
.
|
||||||
|
|
|
||||||
298
doc/nghttpx.1
298
doc/nghttpx.1
|
|
@ -1,6 +1,6 @@
|
||||||
.\" Man page generated from reStructuredText.
|
.\" Man page generated from reStructuredText.
|
||||||
.
|
.
|
||||||
.TH "NGHTTPX" "1" "August 30, 2015" "1.3.0" "nghttp2"
|
.TH "NGHTTPX" "1" "September 06, 2015" "1.3.1-DEV" "nghttp2"
|
||||||
.SH NAME
|
.SH NAME
|
||||||
nghttpx \- HTTP/2 experimental proxy
|
nghttpx \- HTTP/2 experimental proxy
|
||||||
.
|
.
|
||||||
|
|
@ -905,6 +905,21 @@ Set path to save PID of this program.
|
||||||
Run this program as <USER>. This option is intended to
|
Run this program as <USER>. This option is intended to
|
||||||
be used to drop root privileges.
|
be used to drop root privileges.
|
||||||
.UNINDENT
|
.UNINDENT
|
||||||
|
.SS Scripting
|
||||||
|
.INDENT 0.0
|
||||||
|
.TP
|
||||||
|
.B \-\-request\-phase\-file=<PATH>
|
||||||
|
Set mruby script file which will be executed when
|
||||||
|
request header fields are completely received from
|
||||||
|
frontend. This hook is called request phase hook.
|
||||||
|
.UNINDENT
|
||||||
|
.INDENT 0.0
|
||||||
|
.TP
|
||||||
|
.B \-\-response\-phase\-file=<PATH>
|
||||||
|
Set mruby script file which will be executed when
|
||||||
|
response header fields are completely received from
|
||||||
|
backend. This hook is called response phase hook.
|
||||||
|
.UNINDENT
|
||||||
.SS Misc
|
.SS Misc
|
||||||
.INDENT 0.0
|
.INDENT 0.0
|
||||||
.TP
|
.TP
|
||||||
|
|
@ -1003,19 +1018,14 @@ Link: </css/theme.css>; rel=preload
|
||||||
.UNINDENT
|
.UNINDENT
|
||||||
.UNINDENT
|
.UNINDENT
|
||||||
.sp
|
.sp
|
||||||
Currently, the following restrictions are applied for server push:
|
Currently, the following restriction is applied for server push:
|
||||||
.INDENT 0.0
|
.INDENT 0.0
|
||||||
.IP 1. 3
|
.IP 1. 3
|
||||||
URI\-reference must not contain authority. If it exists, it is not
|
|
||||||
pushed. \fB/fonts/font.woff\fP and \fBcss/theme.css\fP are eligible to
|
|
||||||
be pushed. \fBhttps://example.org/fonts/font.woff\fP and
|
|
||||||
\fB//example.org/css/theme.css\fP are not.
|
|
||||||
.IP 2. 3
|
|
||||||
The associated stream must have method "GET" or "POST". The
|
The associated stream must have method "GET" or "POST". The
|
||||||
associated stream\(aqs status code must be 200.
|
associated stream\(aqs status code must be 200.
|
||||||
.UNINDENT
|
.UNINDENT
|
||||||
.sp
|
.sp
|
||||||
These limitations may be loosened in the future release.
|
This limitation may be loosened in the future release.
|
||||||
.SH UNIX DOMAIN SOCKET
|
.SH UNIX DOMAIN SOCKET
|
||||||
.sp
|
.sp
|
||||||
nghttpx supports UNIX domain socket with a filename for both frontend
|
nghttpx supports UNIX domain socket with a filename for both frontend
|
||||||
|
|
@ -1101,6 +1111,278 @@ If \fI\%\-\-tls\-ticket\-key\-file\fP is given, encryption key is read
|
||||||
from the given file. In this case, nghttpx does not rotate key
|
from the given file. In this case, nghttpx does not rotate key
|
||||||
automatically. To rotate key, one has to restart nghttpx (see
|
automatically. To rotate key, one has to restart nghttpx (see
|
||||||
SIGNALS).
|
SIGNALS).
|
||||||
|
.SH MRUBY SCRIPTING
|
||||||
|
.sp
|
||||||
|
\fBWARNING:\fP
|
||||||
|
.INDENT 0.0
|
||||||
|
.INDENT 3.5
|
||||||
|
The current mruby extension API is experimental and not frozen. The
|
||||||
|
API is subject to change in the future release.
|
||||||
|
.UNINDENT
|
||||||
|
.UNINDENT
|
||||||
|
.sp
|
||||||
|
nghttpx allows users to extend its capability using mruby scripts.
|
||||||
|
nghttpx has 2 hook points to execute mruby script: request phase and
|
||||||
|
response phase. The request phase hook is invoked after all request
|
||||||
|
header fields are received from client. The response phase hook is
|
||||||
|
invoked after all response header fields are received from backend
|
||||||
|
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 set request phase hook, use \fI\%\-\-request\-phase\-file\fP option.
|
||||||
|
To set response phase hook, use \fI\%\-\-response\-phase\-file\fP
|
||||||
|
option.
|
||||||
|
.sp
|
||||||
|
For request and response phase hook, user calls \fI\%Nghttpx.run\fP
|
||||||
|
with block. The \fI\%Nghttpx::Env\fP is passed to the block.
|
||||||
|
User can can access \fI\%Nghttpx::Request\fP and
|
||||||
|
\fI\%Nghttpx::Response\fP objects via \fI\%Nghttpx::Env#req\fP
|
||||||
|
and \fI\%Nghttpx::Env#resp\fP respectively.
|
||||||
|
.INDENT 0.0
|
||||||
|
.TP
|
||||||
|
.B classmethod .Nghttpx.run(&block)
|
||||||
|
Run request or response phase hook with given \fIblock\fP\&.
|
||||||
|
\fI\%Nghttpx::Env\fP object is passed to the given block.
|
||||||
|
.UNINDENT
|
||||||
|
.INDENT 0.0
|
||||||
|
.TP
|
||||||
|
.B Nghttpx::REQUEST_PHASE
|
||||||
|
Constant to represent request phase.
|
||||||
|
.UNINDENT
|
||||||
|
.INDENT 0.0
|
||||||
|
.TP
|
||||||
|
.B Nghttpx::RESPONSE_PHASE
|
||||||
|
Constant to represent response phase.
|
||||||
|
.UNINDENT
|
||||||
|
.INDENT 0.0
|
||||||
|
.TP
|
||||||
|
.B class Nghttpx::Env
|
||||||
|
Object to represent current request specific context.
|
||||||
|
.INDENT 7.0
|
||||||
|
.TP
|
||||||
|
.B attribute [R] req
|
||||||
|
Return \fI\%Request\fP object.
|
||||||
|
.UNINDENT
|
||||||
|
.INDENT 7.0
|
||||||
|
.TP
|
||||||
|
.B attribute [R] resp
|
||||||
|
Return \fI\%Response\fP object.
|
||||||
|
.UNINDENT
|
||||||
|
.INDENT 7.0
|
||||||
|
.TP
|
||||||
|
.B attribute [R] ctx
|
||||||
|
Return Ruby hash object. It persists until request finishes.
|
||||||
|
So values set in request phase hoo can be retrieved in
|
||||||
|
response phase hook.
|
||||||
|
.UNINDENT
|
||||||
|
.INDENT 7.0
|
||||||
|
.TP
|
||||||
|
.B attribute [R] phase
|
||||||
|
Return the current phase.
|
||||||
|
.UNINDENT
|
||||||
|
.INDENT 7.0
|
||||||
|
.TP
|
||||||
|
.B attribute [R] remote_addr
|
||||||
|
Return IP address of a remote client.
|
||||||
|
.UNINDENT
|
||||||
|
.UNINDENT
|
||||||
|
.INDENT 0.0
|
||||||
|
.TP
|
||||||
|
.B class Nghttpx::Request
|
||||||
|
Object to represent request from client. The modification to
|
||||||
|
Request object is allowed only in request phase hook.
|
||||||
|
.INDENT 7.0
|
||||||
|
.TP
|
||||||
|
.B attribute [R] http_version_major
|
||||||
|
Return HTTP major version.
|
||||||
|
.UNINDENT
|
||||||
|
.INDENT 7.0
|
||||||
|
.TP
|
||||||
|
.B attribute [R] http_version_minor
|
||||||
|
Return HTTP minor version.
|
||||||
|
.UNINDENT
|
||||||
|
.INDENT 7.0
|
||||||
|
.TP
|
||||||
|
.B attribute [R/W] method
|
||||||
|
HTTP method. On assignment, copy of given value is assigned.
|
||||||
|
We don\(aqt accept arbitrary method name. We will document them
|
||||||
|
later, but well known methods, like GET, PUT and POST, are all
|
||||||
|
supported.
|
||||||
|
.UNINDENT
|
||||||
|
.INDENT 7.0
|
||||||
|
.TP
|
||||||
|
.B attribute [R/W] authority
|
||||||
|
Authority (i.e., example.org), including optional port
|
||||||
|
component . On assignment, copy of given value is assigned.
|
||||||
|
.UNINDENT
|
||||||
|
.INDENT 7.0
|
||||||
|
.TP
|
||||||
|
.B attribute [R/W] scheme
|
||||||
|
Scheme (i.e., http, https). On assignment, copy of given
|
||||||
|
value is assigned.
|
||||||
|
.UNINDENT
|
||||||
|
.INDENT 7.0
|
||||||
|
.TP
|
||||||
|
.B attribute [R/W] path
|
||||||
|
Request path, including query component (i.e., /index.html).
|
||||||
|
On assignment, copy of given value is assigned. The path does
|
||||||
|
not include authority component of URI.
|
||||||
|
.UNINDENT
|
||||||
|
.INDENT 7.0
|
||||||
|
.TP
|
||||||
|
.B attribute [R] headers
|
||||||
|
Return Ruby hash containing copy of request header fields.
|
||||||
|
Changing values in returned hash does not change request
|
||||||
|
header fields actually used in request processing. Use
|
||||||
|
\fI\%Nghttpx::Request#add_header\fP or
|
||||||
|
\fI\%Nghttpx::Request#set_header\fP to change request
|
||||||
|
header fields.
|
||||||
|
.UNINDENT
|
||||||
|
.INDENT 7.0
|
||||||
|
.TP
|
||||||
|
.B add_header(key, value)
|
||||||
|
Add header entry associated with key. The value can be single
|
||||||
|
string or array of string. It does not replace any existing
|
||||||
|
values associated with key.
|
||||||
|
.UNINDENT
|
||||||
|
.INDENT 7.0
|
||||||
|
.TP
|
||||||
|
.B set_header(key, value)
|
||||||
|
Set header entry associated with key. The value can be single
|
||||||
|
string or array of string. It replaces any existing values
|
||||||
|
associated with key.
|
||||||
|
.UNINDENT
|
||||||
|
.INDENT 7.0
|
||||||
|
.TP
|
||||||
|
.B clear_headers()
|
||||||
|
Clear all existing request header fields.
|
||||||
|
.UNINDENT
|
||||||
|
.INDENT 7.0
|
||||||
|
.TP
|
||||||
|
.B push uri
|
||||||
|
Initiate to push resource identified by \fIuri\fP\&. Only HTTP/2
|
||||||
|
protocol supports this feature. For the other protocols, this
|
||||||
|
method is noop. \fIuri\fP can be absolute URI, absolute path or
|
||||||
|
relative path to the current request. For absolute or
|
||||||
|
relative path, scheme and authority are inherited from the
|
||||||
|
current request. Currently, method is always GET. nghttpx
|
||||||
|
will issue request to backend servers to fulfill this request.
|
||||||
|
The request and response phase hooks will be called for pushed
|
||||||
|
resource as well.
|
||||||
|
.UNINDENT
|
||||||
|
.UNINDENT
|
||||||
|
.INDENT 0.0
|
||||||
|
.TP
|
||||||
|
.B class Nghttpx::Response
|
||||||
|
Object to represent response from backend server.
|
||||||
|
.INDENT 7.0
|
||||||
|
.TP
|
||||||
|
.B attribute [R] http_version_major
|
||||||
|
Return HTTP major version.
|
||||||
|
.UNINDENT
|
||||||
|
.INDENT 7.0
|
||||||
|
.TP
|
||||||
|
.B attribute [R] http_version_minor
|
||||||
|
Return HTTP minor version.
|
||||||
|
.UNINDENT
|
||||||
|
.INDENT 7.0
|
||||||
|
.TP
|
||||||
|
.B attribute [R/W] status
|
||||||
|
HTTP status code. It must be in the range [200, 999],
|
||||||
|
inclusive. The non\-final status code is not supported in
|
||||||
|
mruby scripting at the moment.
|
||||||
|
.UNINDENT
|
||||||
|
.INDENT 7.0
|
||||||
|
.TP
|
||||||
|
.B attribute [R] headers
|
||||||
|
Return Ruby hash containing copy of response header fields.
|
||||||
|
Changing values in returned hash does not change response
|
||||||
|
header fields actually used in response processing. Use
|
||||||
|
\fI\%Nghttpx::Response#add_header\fP or
|
||||||
|
\fI\%Nghttpx::Response#set_header\fP to change response
|
||||||
|
header fields.
|
||||||
|
.UNINDENT
|
||||||
|
.INDENT 7.0
|
||||||
|
.TP
|
||||||
|
.B add_header(key, value)
|
||||||
|
Add header entry associated with key. The value can be single
|
||||||
|
string or array of string. It does not replace any existing
|
||||||
|
values associated with key.
|
||||||
|
.UNINDENT
|
||||||
|
.INDENT 7.0
|
||||||
|
.TP
|
||||||
|
.B set_header(key, value)
|
||||||
|
Set header entry associated with key. The value can be single
|
||||||
|
string or array of string. It replaces any existing values
|
||||||
|
associated with key.
|
||||||
|
.UNINDENT
|
||||||
|
.INDENT 7.0
|
||||||
|
.TP
|
||||||
|
.B clear_headers()
|
||||||
|
Clear all existing response header fields.
|
||||||
|
.UNINDENT
|
||||||
|
.INDENT 7.0
|
||||||
|
.TP
|
||||||
|
.B return(body)
|
||||||
|
Return custom response \fIbody\fP to a client. When this method
|
||||||
|
is called in request phase hook, the request is not forwarded
|
||||||
|
to the backend, and response phase hook for this request will
|
||||||
|
not be invoked. When this method is called in resonse 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
|
||||||
|
\fI\%Nghttpx::Response#status\fP\&. If status code is not
|
||||||
|
set, 200 is used. \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
|
||||||
|
completely custom header fields, first call
|
||||||
|
\fI\%Nghttpx::Response#clear_headers\fP to erase all
|
||||||
|
existing header fields, and then add required header fields.
|
||||||
|
It is an error to call this method twice for a given request.
|
||||||
|
.UNINDENT
|
||||||
|
.UNINDENT
|
||||||
|
.SS MRUBY EXAMPLES
|
||||||
|
.sp
|
||||||
|
Modify requet path:
|
||||||
|
.INDENT 0.0
|
||||||
|
.INDENT 3.5
|
||||||
|
.sp
|
||||||
|
.nf
|
||||||
|
.ft C
|
||||||
|
Nghttpx.run do |env|
|
||||||
|
env.req.path = "/apps#{env.req.path}"
|
||||||
|
end
|
||||||
|
.ft P
|
||||||
|
.fi
|
||||||
|
.UNINDENT
|
||||||
|
.UNINDENT
|
||||||
|
.sp
|
||||||
|
Note that the file containing the above script must be set with
|
||||||
|
\fI\%\-\-request\-phase\-file\fP option since we modify request path.
|
||||||
|
.sp
|
||||||
|
Restrict permission of viewing a content to a specific client
|
||||||
|
addresses:
|
||||||
|
.INDENT 0.0
|
||||||
|
.INDENT 3.5
|
||||||
|
.sp
|
||||||
|
.nf
|
||||||
|
.ft C
|
||||||
|
Nghttpx.run do |env|
|
||||||
|
allowed_clients = ["127.0.0.1", "::1"]
|
||||||
|
|
||||||
|
if env.req.path.start_with?("/log/") &&
|
||||||
|
!allowed_clients.include?(env.remote_addr) then
|
||||||
|
env.resp.status = 404
|
||||||
|
env.resp.return "permission denied"
|
||||||
|
end
|
||||||
|
end
|
||||||
|
.ft P
|
||||||
|
.fi
|
||||||
|
.UNINDENT
|
||||||
|
.UNINDENT
|
||||||
.SH SEE ALSO
|
.SH SEE ALSO
|
||||||
.sp
|
.sp
|
||||||
\fInghttp(1)\fP, \fInghttpd(1)\fP, \fIh2load(1)\fP
|
\fInghttp(1)\fP, \fInghttpd(1)\fP, \fIh2load(1)\fP
|
||||||
|
|
|
||||||
|
|
@ -811,6 +811,22 @@ Process
|
||||||
be used to drop root privileges.
|
be used to drop root privileges.
|
||||||
|
|
||||||
|
|
||||||
|
Scripting
|
||||||
|
~~~~~~~~~
|
||||||
|
|
||||||
|
.. option:: --request-phase-file=<PATH>
|
||||||
|
|
||||||
|
Set mruby script file which will be executed when
|
||||||
|
request header fields are completely received from
|
||||||
|
frontend. This hook is called request phase hook.
|
||||||
|
|
||||||
|
.. option:: --response-phase-file=<PATH>
|
||||||
|
|
||||||
|
Set mruby script file which will be executed when
|
||||||
|
response header fields are completely received from
|
||||||
|
backend. This hook is called response phase hook.
|
||||||
|
|
||||||
|
|
||||||
Misc
|
Misc
|
||||||
~~~~
|
~~~~
|
||||||
|
|
||||||
|
|
@ -906,17 +922,12 @@ header field to initiate server push:
|
||||||
Link: </fonts/font.woff>; rel=preload
|
Link: </fonts/font.woff>; rel=preload
|
||||||
Link: </css/theme.css>; rel=preload
|
Link: </css/theme.css>; rel=preload
|
||||||
|
|
||||||
Currently, the following restrictions are applied for server push:
|
Currently, the following restriction is applied for server push:
|
||||||
|
|
||||||
1. URI-reference must not contain authority. If it exists, it is not
|
1. The associated stream must have method "GET" or "POST". The
|
||||||
pushed. ``/fonts/font.woff`` and ``css/theme.css`` are eligible to
|
|
||||||
be pushed. ``https://example.org/fonts/font.woff`` and
|
|
||||||
``//example.org/css/theme.css`` are not.
|
|
||||||
|
|
||||||
2. The associated stream must have method "GET" or "POST". The
|
|
||||||
associated stream's status code must be 200.
|
associated stream's status code must be 200.
|
||||||
|
|
||||||
These limitations may be loosened in the future release.
|
This limitation may be loosened in the future release.
|
||||||
|
|
||||||
UNIX DOMAIN SOCKET
|
UNIX DOMAIN SOCKET
|
||||||
------------------
|
------------------
|
||||||
|
|
@ -1005,6 +1016,239 @@ from the given file. In this case, nghttpx does not rotate key
|
||||||
automatically. To rotate key, one has to restart nghttpx (see
|
automatically. To rotate key, one has to restart nghttpx (see
|
||||||
SIGNALS).
|
SIGNALS).
|
||||||
|
|
||||||
|
MRUBY SCRIPTING
|
||||||
|
---------------
|
||||||
|
|
||||||
|
.. warning::
|
||||||
|
|
||||||
|
The current mruby extension API is experimental and not frozen. The
|
||||||
|
API is subject to change in the future release.
|
||||||
|
|
||||||
|
nghttpx allows users to extend its capability using mruby scripts.
|
||||||
|
nghttpx has 2 hook points to execute mruby script: request phase and
|
||||||
|
response phase. The request phase hook is invoked after all request
|
||||||
|
header fields are received from client. The response phase hook is
|
||||||
|
invoked after all response header fields are received from backend
|
||||||
|
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 set request phase hook, use :option:`--request-phase-file` option.
|
||||||
|
To set response phase hook, use :option:`--response-phase-file`
|
||||||
|
option.
|
||||||
|
|
||||||
|
For request and response phase hook, user calls :rb:meth:`Nghttpx.run`
|
||||||
|
with block. The :rb:class:`Nghttpx::Env` is passed to the block.
|
||||||
|
User can can access :rb:class:`Nghttpx::Request` and
|
||||||
|
:rb:class:`Nghttpx::Response` objects via :rb:attr:`Nghttpx::Env#req`
|
||||||
|
and :rb:attr:`Nghttpx::Env#resp` respectively.
|
||||||
|
|
||||||
|
.. rb:module:: Nghttpx
|
||||||
|
|
||||||
|
.. rb:classmethod:: run(&block)
|
||||||
|
|
||||||
|
Run request or response phase hook with given *block*.
|
||||||
|
:rb:class:`Nghttpx::Env` object is passed to the given block.
|
||||||
|
|
||||||
|
.. rb:const:: REQUEST_PHASE
|
||||||
|
|
||||||
|
Constant to represent request phase.
|
||||||
|
|
||||||
|
.. rb:const:: RESPONSE_PHASE
|
||||||
|
|
||||||
|
Constant to represent response phase.
|
||||||
|
|
||||||
|
.. rb:class:: Env
|
||||||
|
|
||||||
|
Object to represent current request specific context.
|
||||||
|
|
||||||
|
.. rb:attr_reader:: req
|
||||||
|
|
||||||
|
Return :rb:class:`Request` object.
|
||||||
|
|
||||||
|
.. rb:attr_reader:: resp
|
||||||
|
|
||||||
|
Return :rb:class:`Response` object.
|
||||||
|
|
||||||
|
.. rb:attr_reader:: ctx
|
||||||
|
|
||||||
|
Return Ruby hash object. It persists until request finishes.
|
||||||
|
So values set in request phase hoo can be retrieved in
|
||||||
|
response phase hook.
|
||||||
|
|
||||||
|
.. rb:attr_reader:: phase
|
||||||
|
|
||||||
|
Return the current phase.
|
||||||
|
|
||||||
|
.. rb:attr_reader:: remote_addr
|
||||||
|
|
||||||
|
Return IP address of a remote client.
|
||||||
|
|
||||||
|
.. rb:class:: Request
|
||||||
|
|
||||||
|
Object to represent request from client. The modification to
|
||||||
|
Request object is allowed only in request phase hook.
|
||||||
|
|
||||||
|
.. rb:attr_reader:: http_version_major
|
||||||
|
|
||||||
|
Return HTTP major version.
|
||||||
|
|
||||||
|
.. rb:attr_reader:: http_version_minor
|
||||||
|
|
||||||
|
Return HTTP minor version.
|
||||||
|
|
||||||
|
.. rb:attr_accessor:: method
|
||||||
|
|
||||||
|
HTTP method. On assignment, copy of given value is assigned.
|
||||||
|
We don't accept arbitrary method name. We will document them
|
||||||
|
later, but well known methods, like GET, PUT and POST, are all
|
||||||
|
supported.
|
||||||
|
|
||||||
|
.. rb:attr_accessor:: authority
|
||||||
|
|
||||||
|
Authority (i.e., example.org), including optional port
|
||||||
|
component . On assignment, copy of given value is assigned.
|
||||||
|
|
||||||
|
.. rb:attr_accessor:: scheme
|
||||||
|
|
||||||
|
Scheme (i.e., http, https). On assignment, copy of given
|
||||||
|
value is assigned.
|
||||||
|
|
||||||
|
.. rb:attr_accessor:: path
|
||||||
|
|
||||||
|
Request path, including query component (i.e., /index.html).
|
||||||
|
On assignment, copy of given value is assigned. The path does
|
||||||
|
not include authority component of URI.
|
||||||
|
|
||||||
|
.. rb:attr_reader:: headers
|
||||||
|
|
||||||
|
Return Ruby hash containing copy of request header fields.
|
||||||
|
Changing values in returned hash does not change request
|
||||||
|
header fields actually used in request processing. Use
|
||||||
|
:rb:meth:`Nghttpx::Request#add_header` or
|
||||||
|
:rb:meth:`Nghttpx::Request#set_header` to change request
|
||||||
|
header fields.
|
||||||
|
|
||||||
|
.. rb:method:: add_header(key, value)
|
||||||
|
|
||||||
|
Add header entry associated with key. The value can be single
|
||||||
|
string or array of string. It does not replace any existing
|
||||||
|
values associated with key.
|
||||||
|
|
||||||
|
.. rb:method:: set_header(key, value)
|
||||||
|
|
||||||
|
Set header entry associated with key. The value can be single
|
||||||
|
string or array of string. It replaces any existing values
|
||||||
|
associated with key.
|
||||||
|
|
||||||
|
.. rb:method:: clear_headers
|
||||||
|
|
||||||
|
Clear all existing request header fields.
|
||||||
|
|
||||||
|
.. rb:method:: push uri
|
||||||
|
|
||||||
|
Initiate to push resource identified by *uri*. Only HTTP/2
|
||||||
|
protocol supports this feature. For the other protocols, this
|
||||||
|
method is noop. *uri* can be absolute URI, absolute path or
|
||||||
|
relative path to the current request. For absolute or
|
||||||
|
relative path, scheme and authority are inherited from the
|
||||||
|
current request. Currently, method is always GET. nghttpx
|
||||||
|
will issue request to backend servers to fulfill this request.
|
||||||
|
The request and response phase hooks will be called for pushed
|
||||||
|
resource as well.
|
||||||
|
|
||||||
|
.. rb:class:: Response
|
||||||
|
|
||||||
|
Object to represent response from backend server.
|
||||||
|
|
||||||
|
.. rb:attr_reader:: http_version_major
|
||||||
|
|
||||||
|
Return HTTP major version.
|
||||||
|
|
||||||
|
.. rb:attr_reader:: http_version_minor
|
||||||
|
|
||||||
|
Return HTTP minor version.
|
||||||
|
|
||||||
|
.. rb:attr_accessor:: status
|
||||||
|
|
||||||
|
HTTP status code. It must be in the range [200, 999],
|
||||||
|
inclusive. The non-final status code is not supported in
|
||||||
|
mruby scripting at the moment.
|
||||||
|
|
||||||
|
.. rb:attr_reader:: headers
|
||||||
|
|
||||||
|
Return Ruby hash containing copy of response header fields.
|
||||||
|
Changing values in returned hash does not change response
|
||||||
|
header fields actually used in response processing. Use
|
||||||
|
:rb:meth:`Nghttpx::Response#add_header` or
|
||||||
|
:rb:meth:`Nghttpx::Response#set_header` to change response
|
||||||
|
header fields.
|
||||||
|
|
||||||
|
.. rb:method:: add_header(key, value)
|
||||||
|
|
||||||
|
Add header entry associated with key. The value can be single
|
||||||
|
string or array of string. It does not replace any existing
|
||||||
|
values associated with key.
|
||||||
|
|
||||||
|
.. rb:method:: set_header(key, value)
|
||||||
|
|
||||||
|
Set header entry associated with key. The value can be single
|
||||||
|
string or array of string. It replaces any existing values
|
||||||
|
associated with key.
|
||||||
|
|
||||||
|
.. rb:method:: clear_headers
|
||||||
|
|
||||||
|
Clear all existing response header fields.
|
||||||
|
|
||||||
|
.. rb:method:: return(body)
|
||||||
|
|
||||||
|
Return custom response *body* to a client. When this method
|
||||||
|
is called in request phase hook, the request is not forwarded
|
||||||
|
to the backend, and response phase hook for this request will
|
||||||
|
not be invoked. When this method is called in resonse 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
|
||||||
|
:rb:attr:`Nghttpx::Response#status`. If status code is not
|
||||||
|
set, 200 is used. :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
|
||||||
|
completely custom header fields, first call
|
||||||
|
:rb:meth:`Nghttpx::Response#clear_headers` to erase all
|
||||||
|
existing header fields, and then add required header fields.
|
||||||
|
It is an error to call this method twice for a given request.
|
||||||
|
|
||||||
|
MRUBY EXAMPLES
|
||||||
|
~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Modify requet path:
|
||||||
|
|
||||||
|
.. code-block:: ruby
|
||||||
|
|
||||||
|
Nghttpx.run do |env|
|
||||||
|
env.req.path = "/apps#{env.req.path}"
|
||||||
|
end
|
||||||
|
|
||||||
|
Note that the file containing the above script must be set with
|
||||||
|
:option:`--request-phase-file` option since we modify request path.
|
||||||
|
|
||||||
|
Restrict permission of viewing a content to a specific client
|
||||||
|
addresses:
|
||||||
|
|
||||||
|
.. code-block:: ruby
|
||||||
|
|
||||||
|
Nghttpx.run do |env|
|
||||||
|
allowed_clients = ["127.0.0.1", "::1"]
|
||||||
|
|
||||||
|
if env.req.path.start_with?("/log/") &&
|
||||||
|
!allowed_clients.include?(env.remote_addr) then
|
||||||
|
env.resp.status = 404
|
||||||
|
env.resp.return "permission denied"
|
||||||
|
end
|
||||||
|
end
|
||||||
|
|
||||||
SEE ALSO
|
SEE ALSO
|
||||||
--------
|
--------
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue