walkero
/
nghttp2
1
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity

Document nghttpx mruby extension

This commit is contained in:
Tatsuhiro Tsujikawa 2015-09-05 21:23:27 +09:00
parent 3029e5c530
commit 18064d1626
2 changed files with 219 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/conf.py.in
View File

@ -41,6 +41,8 @@ import sys, os
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
sys.path.append(os.path.abspath('_exts'))
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
@ -48,7 +50,7 @@ import sys, os
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = []
extensions = ['sphinxcontrib.rubydomain']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['@top_srcdir@/_templates']

216
doc/nghttpx.h2r
View File

@ -153,6 +153,222 @@ from the given file. In this case, nghttpx does not rotate key
automatically. To rotate key, one has to restart nghttpx (see
SIGNALS).
MRUBY SCRIPTING
---------------
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: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
--------