Permalink
Browse files

documented the ngx.req.init_body, ngx.req.append_body, and ngx.req.fi…

…nish_body APIs; also bumped the version number to 0.5.10.
  • Loading branch information...
1 parent 4697b1d commit db0bebedb6feb022fcf45513107cffe1e31b1228 @agentzh agentzh committed Jul 30, 2012
Showing with 246 additions and 4 deletions.
  1. +95 −2 README
  2. +77 −1 README.markdown
  3. +74 −1 doc/HttpLuaModule.wiki
View
97 README
@@ -8,8 +8,8 @@ Status
This module is under active development and is production ready.
Version
- This document describes ngx_lua v0.5.9
- (<https://github.com/chaoslawful/lua-nginx-module/tags>) released on 26
+ This document describes ngx_lua v0.5.10
+ (<https://github.com/chaoslawful/lua-nginx-module/tags>) released on 29
July 2012.
Synopsis
@@ -2577,6 +2577,99 @@ Nginx API for Lua
See also ngx.req.set_body_data.
+ ngx.req.init_body
+ syntax: *ngx.req.init_body(buffer_size?)*
+
+ context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua**
+
+ Creates a new blank request body for the current request and inializes
+ the buffer for later request body data writing via the
+ ngx.req.append_body and ngx.req.finish_body APIs.
+
+ If the "buffer_size" argument is specified, then its value will be used
+ for the size of the memory buffer for body writing with
+ ngx.req.append_body. If the argument is omitted, then the value
+ specified by the standard client_body_buffer_size directive will be used
+ instead.
+
+ When the data can no longer be hold in the memory buffer for the request
+ body, then the data will automatically be flushed onto a temporary file
+ just like the standard request body reader in the Nginx core.
+
+ It is important to always call the ngx.req.finish_body after all the
+ data has been appended onto the current request body.
+
+ The usage of this function is often like this:
+
+ ngx.req.init_body(128 * 1024) -- buffer is 128KB
+ for chunk in next_data_chunk() do
+ ngx.req.append_body(chunk) -- each chunk can be 4KB
+ end
+ ngx.req.finish_body()
+
+ This function can be used with ngx.req.append_body, ngx.req.finish_body,
+ and ngx.req.socket to implement efficient input filters in pure Lua (in
+ the context of rewrite_by_lua* or access_by_lua*), which can be used
+ with other Nginx content handler or upstream modules like
+ [[HttpProxyModule]] and [[HttpFastcgiModule]].
+
+ This function was first introduced in the "v0.5.10" release.
+
+ ngx.req.append_body
+ syntax: *ngx.req.append_body(data_chunk)*
+
+ context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua**
+
+ Append new data chunk specified by the "data_chunk" argument onto the
+ existing request body created by the ngx.req.init_body call.
+
+ When the data can no longer be hold in the memory buffer for the request
+ body, then the data will automatically be flushed onto a temporary file
+ just like the standard request body reader in the Nginx core.
+
+ It is important to always call the ngx.req.finish_body after all the
+ data has been appended onto the current request body.
+
+ The usage of this function is often like this:
+
+ ngx.req.init_body(128 * 1024) -- buffer is 128 KB
+ for chunk in next_data_chunk() do
+ ngx.req.append_body(chunk) -- each chunk can be 4KB
+ end
+ ngx.req.finish_body()
+
+ This function can be used with ngx.req.init_body, ngx.req.finish_body,
+ and ngx.req.socket to implement efficient input filters in pure Lua (in
+ the context of rewrite_by_lua* or access_by_lua*), which can be used
+ with other Nginx content handler or upstream modules like
+ [[HttpProxyModule]] and [[HttpFastcgiModule]].
+
+ This function was first introduced in the "v0.5.10" release.
+
+ ngx.req.finish_body
+ syntax: *ngx.req.finish_body()*
+
+ context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua**
+
+ Completes the construction process of the new request body created by
+ the ngx.req.init_body and ngx.req.append_body calls.
+
+ The usage of this function is often like this:
+
+ ngx.req.init_body(128 * 1024) -- buffer is 128KB
+ for chunk in next_data_chunk() do
+ ngx.req.append_body(chunk) -- each chunk can be 4KB
+ end
+ ngx.req.finish_body()
+
+ This function can be used with ngx.req.init_body, ngx.req.append_body,
+ and ngx.req.socket to implement efficient input filters in pure Lua (in
+ the context of rewrite_by_lua* or access_by_lua*), which can be used
+ with other Nginx content handler or upstream modules like
+ [[HttpProxyModule]] and [[HttpFastcgiModule]].
+
+ This function was first introduced in the "v0.5.10" release.
+
ngx.req.socket
syntax: *tcpsock, err = ngx.req.socket()*
View
@@ -18,7 +18,7 @@ This module is under active development and is production ready.
Version
=======
-This document describes ngx_lua [v0.5.9](https://github.com/chaoslawful/lua-nginx-module/tags) released on 26 July 2012.
+This document describes ngx_lua [v0.5.10](https://github.com/chaoslawful/lua-nginx-module/tags) released on 29 July 2012.
Synopsis
========
@@ -2406,6 +2406,82 @@ This function was first introduced in the `v0.3.1rc18` release.
See also [ngx.req.set_body_data](http://wiki.nginx.org/HttpLuaModule#ngx.req.set_body_data).
+ngx.req.init_body
+-----------------
+**syntax:** *ngx.req.init_body(buffer_size?)*
+
+**context:** *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua**
+
+Creates a new blank request body for the current request and inializes the buffer for later request body data writing via the [ngx.req.append_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.append_body) and [ngx.req.finish_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.finish_body) APIs.
+
+If the `buffer_size` argument is specified, then its value will be used for the size of the memory buffer for body writing with [ngx.req.append_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.append_body). If the argument is omitted, then the value specified by the standard [client_body_buffer_size](http://wiki.nginx.org/HttpCoreModule#client_body_buffer_size) directive will be used instead.
+
+When the data can no longer be hold in the memory buffer for the request body, then the data will automatically be flushed onto a temporary file just like the standard request body reader in the Nginx core.
+
+It is important to always call the [ngx.req.finish_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.finish_body) after all the data has been appended onto the current request body.
+
+The usage of this function is often like this:
+
+
+ ngx.req.init_body(128 * 1024) -- buffer is 128KB
+ for chunk in next_data_chunk() do
+ ngx.req.append_body(chunk) -- each chunk can be 4KB
+ end
+ ngx.req.finish_body()
+
+
+This function can be used with [ngx.req.append_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.append_body), [ngx.req.finish_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.finish_body), and [ngx.req.socket](http://wiki.nginx.org/HttpLuaModule#ngx.req.socket) to implement efficient input filters in pure Lua (in the context of [rewrite_by_lua](http://wiki.nginx.org/HttpLuaModule#rewrite_by_lua)* or [access_by_lua](http://wiki.nginx.org/HttpLuaModule#access_by_lua)*), which can be used with other Nginx content handler or upstream modules like [HttpProxyModule](http://wiki.nginx.org/HttpProxyModule) and [HttpFastcgiModule](http://wiki.nginx.org/HttpFastcgiModule).
+
+This function was first introduced in the `v0.5.10` release.
+
+ngx.req.append_body
+-------------------
+**syntax:** *ngx.req.append_body(data_chunk)*
+
+**context:** *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua**
+
+Append new data chunk specified by the `data_chunk` argument onto the existing request body created by the [ngx.req.init_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.init_body) call.
+
+When the data can no longer be hold in the memory buffer for the request body, then the data will automatically be flushed onto a temporary file just like the standard request body reader in the Nginx core.
+
+It is important to always call the [ngx.req.finish_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.finish_body) after all the data has been appended onto the current request body.
+
+The usage of this function is often like this:
+
+
+ ngx.req.init_body(128 * 1024) -- buffer is 128 KB
+ for chunk in next_data_chunk() do
+ ngx.req.append_body(chunk) -- each chunk can be 4KB
+ end
+ ngx.req.finish_body()
+
+
+This function can be used with [ngx.req.init_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.init_body), [ngx.req.finish_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.finish_body), and [ngx.req.socket](http://wiki.nginx.org/HttpLuaModule#ngx.req.socket) to implement efficient input filters in pure Lua (in the context of [rewrite_by_lua](http://wiki.nginx.org/HttpLuaModule#rewrite_by_lua)* or [access_by_lua](http://wiki.nginx.org/HttpLuaModule#access_by_lua)*), which can be used with other Nginx content handler or upstream modules like [HttpProxyModule](http://wiki.nginx.org/HttpProxyModule) and [HttpFastcgiModule](http://wiki.nginx.org/HttpFastcgiModule).
+
+This function was first introduced in the `v0.5.10` release.
+
+ngx.req.finish_body
+-------------------
+**syntax:** *ngx.req.finish_body()*
+
+**context:** *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua**
+
+Completes the construction process of the new request body created by the [ngx.req.init_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.init_body) and [ngx.req.append_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.append_body) calls.
+
+The usage of this function is often like this:
+
+
+ ngx.req.init_body(128 * 1024) -- buffer is 128KB
+ for chunk in next_data_chunk() do
+ ngx.req.append_body(chunk) -- each chunk can be 4KB
+ end
+ ngx.req.finish_body()
+
+
+This function can be used with [ngx.req.init_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.init_body), [ngx.req.append_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.append_body), and [ngx.req.socket](http://wiki.nginx.org/HttpLuaModule#ngx.req.socket) to implement efficient input filters in pure Lua (in the context of [rewrite_by_lua](http://wiki.nginx.org/HttpLuaModule#rewrite_by_lua)* or [access_by_lua](http://wiki.nginx.org/HttpLuaModule#access_by_lua)*), which can be used with other Nginx content handler or upstream modules like [HttpProxyModule](http://wiki.nginx.org/HttpProxyModule) and [HttpFastcgiModule](http://wiki.nginx.org/HttpFastcgiModule).
+
+This function was first introduced in the `v0.5.10` release.
+
ngx.req.socket
--------------
**syntax:** *tcpsock, err = ngx.req.socket()*
View
@@ -10,7 +10,7 @@ This module is under active development and is production ready.
= Version =
-This document describes ngx_lua [https://github.com/chaoslawful/lua-nginx-module/tags v0.5.9] released on 26 July 2012.
+This document describes ngx_lua [https://github.com/chaoslawful/lua-nginx-module/tags v0.5.10] released on 29 July 2012.
= Synopsis =
<geshi lang="nginx">
@@ -2335,6 +2335,79 @@ This function was first introduced in the <code>v0.3.1rc18</code> release.
See also [[#ngx.req.set_body_data|ngx.req.set_body_data]].
+== ngx.req.init_body ==
+'''syntax:''' ''ngx.req.init_body(buffer_size?)''
+
+'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*''
+
+Creates a new blank request body for the current request and inializes the buffer for later request body data writing via the [[#ngx.req.append_body|ngx.req.append_body]] and [[#ngx.req.finish_body|ngx.req.finish_body]] APIs.
+
+If the <code>buffer_size</code> argument is specified, then its value will be used for the size of the memory buffer for body writing with [[#ngx.req.append_body|ngx.req.append_body]]. If the argument is omitted, then the value specified by the standard [[HttpCoreModule#client_body_buffer_size|client_body_buffer_size]] directive will be used instead.
+
+When the data can no longer be hold in the memory buffer for the request body, then the data will automatically be flushed onto a temporary file just like the standard request body reader in the Nginx core.
+
+It is important to always call the [[#ngx.req.finish_body|ngx.req.finish_body]] after all the data has been appended onto the current request body.
+
+The usage of this function is often like this:
+
+<geshi lang="lua">
+ ngx.req.init_body(128 * 1024) -- buffer is 128KB
+ for chunk in next_data_chunk() do
+ ngx.req.append_body(chunk) -- each chunk can be 4KB
+ end
+ ngx.req.finish_body()
+</geshi>
+
+This function can be used with [[#ngx.req.append_body|ngx.req.append_body]], [[#ngx.req.finish_body|ngx.req.finish_body]], and [[#ngx.req.socket|ngx.req.socket]] to implement efficient input filters in pure Lua (in the context of [[#rewrite_by_lua|rewrite_by_lua]]* or [[#access_by_lua|access_by_lua]]*), which can be used with other Nginx content handler or upstream modules like [[HttpProxyModule]] and [[HttpFastcgiModule]].
+
+This function was first introduced in the <code>v0.5.10</code> release.
+
+== ngx.req.append_body ==
+'''syntax:''' ''ngx.req.append_body(data_chunk)''
+
+'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*''
+
+Append new data chunk specified by the <code>data_chunk</code> argument onto the existing request body created by the [[#ngx.req.init_body|ngx.req.init_body]] call.
+
+When the data can no longer be hold in the memory buffer for the request body, then the data will automatically be flushed onto a temporary file just like the standard request body reader in the Nginx core.
+
+It is important to always call the [[#ngx.req.finish_body|ngx.req.finish_body]] after all the data has been appended onto the current request body.
+
+The usage of this function is often like this:
+
+<geshi lang="lua">
+ ngx.req.init_body(128 * 1024) -- buffer is 128 KB
+ for chunk in next_data_chunk() do
+ ngx.req.append_body(chunk) -- each chunk can be 4KB
+ end
+ ngx.req.finish_body()
+</geshi>
+
+This function can be used with [[#ngx.req.init_body|ngx.req.init_body]], [[#ngx.req.finish_body|ngx.req.finish_body]], and [[#ngx.req.socket|ngx.req.socket]] to implement efficient input filters in pure Lua (in the context of [[#rewrite_by_lua|rewrite_by_lua]]* or [[#access_by_lua|access_by_lua]]*), which can be used with other Nginx content handler or upstream modules like [[HttpProxyModule]] and [[HttpFastcgiModule]].
+
+This function was first introduced in the <code>v0.5.10</code> release.
+
+== ngx.req.finish_body ==
+'''syntax:''' ''ngx.req.finish_body()''
+
+'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*''
+
+Completes the construction process of the new request body created by the [[#ngx.req.init_body|ngx.req.init_body]] and [[#ngx.req.append_body|ngx.req.append_body]] calls.
+
+The usage of this function is often like this:
+
+<geshi lang="lua">
+ ngx.req.init_body(128 * 1024) -- buffer is 128KB
+ for chunk in next_data_chunk() do
+ ngx.req.append_body(chunk) -- each chunk can be 4KB
+ end
+ ngx.req.finish_body()
+</geshi>
+
+This function can be used with [[#ngx.req.init_body|ngx.req.init_body]], [[#ngx.req.append_body|ngx.req.append_body]], and [[#ngx.req.socket|ngx.req.socket]] to implement efficient input filters in pure Lua (in the context of [[#rewrite_by_lua|rewrite_by_lua]]* or [[#access_by_lua|access_by_lua]]*), which can be used with other Nginx content handler or upstream modules like [[HttpProxyModule]] and [[HttpFastcgiModule]].
+
+This function was first introduced in the <code>v0.5.10</code> release.
+
== ngx.req.socket ==
'''syntax:''' ''tcpsock, err = ngx.req.socket()''

0 comments on commit db0bebe

Please sign in to comment.