docs: documented the new ngx.req.socket(true) API, upon which fancy protocols like WebSocket can be implemented.

Author: agentzh

README

@@ -2946,6 +2946,8 @@ Nginx API for Lua
   ngx.req.socket
     syntax: *tcpsock, err = ngx.req.socket()*
 
+    syntax: *tcpsock, err = ngx.req.socket(raw)*
+
     context: *rewrite_by_lua*, access_by_lua*, content_by_lua**
 
     Returns a read-only cosocket object that wraps the downstream
@@ -2962,9 +2964,29 @@ Nginx API for Lua
 
     If any request body data has been pre-read into the Nginx core request
     header buffer, the resulting cosocket object will take care of this to
-    avoid potential data loss resulting from such pre-reading.
-
-    Chunked request bodies are not yet supported in this API.
+    avoid potential data loss resulting from such pre-reading. Chunked
+    request bodies are not yet supported in this API.
+
+    Since the "v0.9.0" release, this function accepts an optional boolean
+    "raw" argument. When this argument is "true", this function returns a
+    full duplex cosocket object wrapping around the raw downstream
+    connection socket, upon which you can call the receive, receiveuntil,
+    and send methods.
+
+    When the "raw" argument is "true", it is required that no pending data
+    from any previous ngx.say, ngx.print, or ngx.send_headers calls exists.
+    So if you have these downstream output calls previously, you should call
+    ngx.flush(true) before calling "ngx.req.socket(true)" to ensure that
+    there is no pending output data. Another requirement for this case is
+    that the request body must have already been read completely.
+
+    You can use the "raw request socket" returned by "ngx.req.socket(true)"
+    to implement fancy protocols like WebSocket
+    (<http://en.wikipedia.org/wiki/WebSocket>), or just emit your own raw
+    HTTP response header or body data. You can refer to the
+    lua-resty-websocket library
+    (<https://github.com/agentzh/lua-resty-websocket>) for a real world
+    example.
 
     This function was first introduced in the "v0.5.0rc1" release.
 

README.markdown

@@ -2710,6 +2710,8 @@ ngx.req.socket
 --------------
 **syntax:** *tcpsock, err = ngx.req.socket()*
 
+**syntax:** *tcpsock, err = ngx.req.socket(raw)*
+
 **context:** *rewrite_by_lua*, access_by_lua*, content_by_lua**
 
 Returns a read-only cosocket object that wraps the downstream connection. Only [receive](http://wiki.nginx.org/HttpLuaModule#tcpsock:receive) and [receiveuntil](http://wiki.nginx.org/HttpLuaModule#tcpsock:receiveuntil) methods are supported on this object.
@@ -2719,9 +2721,14 @@ In case of error, `nil` will be returned as well as a string describing the erro
 The socket object returned by this method is usually used to read the current request's body in a streaming fashion. Do not turn on the [lua_need_request_body](http://wiki.nginx.org/HttpLuaModule#lua_need_request_body) directive, and do not mix this call with [ngx.req.read_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.read_body) and [ngx.req.discard_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.discard_body).
 
 If any request body data has been pre-read into the Nginx core request header buffer, the resulting cosocket object will take care of this to avoid potential data loss resulting from such pre-reading.
-
 Chunked request bodies are not yet supported in this API.
 
+Since the `v0.9.0` release, this function accepts an optional boolean `raw` argument. When this argument is `true`, this function returns a full duplex cosocket object wrapping around the raw downstream connection socket, upon which you can call the [receive](http://wiki.nginx.org/HttpLuaModule#tcpsock:receive), [receiveuntil](http://wiki.nginx.org/HttpLuaModule#tcpsock:receiveuntil), and [send](http://wiki.nginx.org/HttpLuaModule#tcpsock:send) methods.
+
+When the `raw` argument is `true`, it is required that no pending data from any previous [ngx.say](http://wiki.nginx.org/HttpLuaModule#ngx.say), [ngx.print](http://wiki.nginx.org/HttpLuaModule#ngx.print), or [ngx.send_headers](http://wiki.nginx.org/HttpLuaModule#ngx.send_headers) calls exists. So if you have these downstream output calls previously, you should call [ngx.flush(true)](http://wiki.nginx.org/HttpLuaModule#ngx.flush) before calling `ngx.req.socket(true)` to ensure that there is no pending output data. Another requirement for this case is that the request body must have already been read completely.
+
+You can use the "raw request socket" returned by `ngx.req.socket(true)` to implement fancy protocols like [WebSocket](http://en.wikipedia.org/wiki/WebSocket), or just emit your own raw HTTP response header or body data. You can refer to the [lua-resty-websocket library](https://github.com/agentzh/lua-resty-websocket) for a real world example.
+
 This function was first introduced in the `v0.5.0rc1` release.
 
 ngx.exec

doc/HttpLuaModule.wiki

@@ -2626,6 +2626,8 @@ See also [[#ngx.req.init_body|ngx.req.init_body]].
 == ngx.req.socket ==
 '''syntax:''' ''tcpsock, err = ngx.req.socket()''
 
+'''syntax:''' ''tcpsock, err = ngx.req.socket(raw)''
+
 '''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*''
 
 Returns a read-only cosocket object that wraps the downstream connection. Only [[#tcpsock:receive|receive]] and [[#tcpsock:receiveuntil|receiveuntil]] methods are supported on this object.
@@ -2635,9 +2637,14 @@ In case of error, <code>nil</code> will be returned as well as a string describi
 The socket object returned by this method is usually used to read the current request's body in a streaming fashion. Do not turn on the [[#lua_need_request_body|lua_need_request_body]] directive, and do not mix this call with [[#ngx.req.read_body|ngx.req.read_body]] and [[#ngx.req.discard_body|ngx.req.discard_body]].
 
 If any request body data has been pre-read into the Nginx core request header buffer, the resulting cosocket object will take care of this to avoid potential data loss resulting from such pre-reading.
-
 Chunked request bodies are not yet supported in this API.
 
+Since the <code>v0.9.0</code> release, this function accepts an optional boolean <code>raw</code> argument. When this argument is <code>true</code>, this function returns a full duplex cosocket object wrapping around the raw downstream connection socket, upon which you can call the [[#tcpsock:receive|receive]], [[#tcpsock:receiveuntil|receiveuntil]], and [[#tcpsock:send|send]] methods.
+
+When the <code>raw</code> argument is <code>true</code>, it is required that no pending data from any previous [[#ngx.say|ngx.say]], [[#ngx.print|ngx.print]], or [[#ngx.send_headers|ngx.send_headers]] calls exists. So if you have these downstream output calls previously, you should call [[#ngx.flush|ngx.flush(true)]] before calling <code>ngx.req.socket(true)</code> to ensure that there is no pending output data. Another requirement for this case is that the request body must have already been read completely.
+
+You can use the "raw request socket" returned by <code>ngx.req.socket(true)</code> to implement fancy protocols like [http://en.wikipedia.org/wiki/WebSocket WebSocket], or just emit your own raw HTTP response header or body data. You can refer to the [https://github.com/agentzh/lua-resty-websocket lua-resty-websocket library] for a real world example.
+
 This function was first introduced in the <code>v0.5.0rc1</code> release.
 
 == ngx.exec ==