From b17b24430881dcc2d4577de20dbea7d9290fbbdd Mon Sep 17 00:00:00 2001
From: Konstantin Burkalev <KSDaemon@yandex.ru>
Date: Sat, 21 Jun 2014 14:24:10 +0400
Subject: [PATCH] Edit docs for POST processing

---
 README.md                  | 39 +++++++++++++++++++++++++++++++++-----
 build/post-handler.lua     |  5 ++---
 src/wiola/post-handler.lua |  5 ++---
 3 files changed, 38 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index fdb2326..145d528 100644
--- a/README.md
+++ b/README.md
@@ -17,6 +17,7 @@ Table of Contents
 	* [removeConnection](#removeconnectionregid)
 	* [receiveData](#receivedataregid-data)
 	* [getPendingData](#getpendingdataregid)
+	* [processPostData](#processpostdatasid-realm-data)
 * [Copyright and License](#copyright-and-license)
 * [See Also](#see-also)
 
@@ -40,6 +41,8 @@ wiola supports next WAMP roles and features:
 
 Wiola supports JSON and msgpack serializers.
 
+From v0.3.1 Wiola also supports lightweight POST event publishing. See processPostData method and post-handler.lua for details.
+
 [Back to TOC](#table-of-contents)
 
 Usage example
@@ -74,7 +77,7 @@ lua_package_path '/usr/local/lualib/wiola/?.lua;/usr/local/lualib/lua-MessagePac
 
 # Configure a vhost
 server {
-   # example location
+   # example location for websocket WAMP connection
    location /ws/ {
       lua_socket_log_errors off;
       lua_check_client_abort on;
@@ -85,6 +88,14 @@ server {
       content_by_lua_file $document_root/lua/wiola/handler.lua;
    }
 
+   # example location for a lightweight POST event publishing
+   location /wslight/ {
+      lua_socket_log_errors off;
+      lua_check_client_abort on;
+
+      content_by_lua_file $document_root/lua/wiola/post-handler.lua;
+   }
+
 }
 ```
 
@@ -131,7 +142,7 @@ Returns:
 [Back to TOC](#table-of-contents)
 
 removeConnection(regId)
----------------
+------------------------------------------
 
 Removes connection from viola control. Cleans all cached data. Do not neglect this method on connection termination.
 
@@ -144,7 +155,7 @@ Returns: nothing
 [Back to TOC](#table-of-contents)
 
 receiveData(regId, data)
----------------
+------------------------------------------
 
 This method should be called, when new data is received from web socket. This method analyze all incoming messages, set states and prepare response data for clients.
 
@@ -155,11 +166,10 @@ Parameters:
 
 Returns: nothing
 
-
 [Back to TOC](#table-of-contents)
 
 getPendingData(regId)
----------------------------
+------------------------------------------
 
 Checks the store for new data for client.
 
@@ -174,6 +184,25 @@ Returns:
 
  This method is actualy a proxy for redis:lpop() method.
 
+[Back to TOC](#table-of-contents)
+
+processPostData(sid, realm, data)
+------------------------------------------
+
+Process lightweight POST data from client containing a publish message. This method is intended for fast publishing
+an event, for example, in case when WAMP client is a browser application, which makes some changes on backend server,
+so backend is a right place to notify other WAMP subscribers, but making a full WAMP connection is not optimal.
+
+Parameters:
+
+ * **sid** - nginx session connection ID
+ * **realm** - WAMP Realm to operate in
+ * **data** - data, received through POST (JSON-encoded WAMP publish event)
+
+Returns:
+
+ * **response data** (JSON encoded WAMP response message in case of error, or { result = true })
+ * **httpCode** HTTP status code (HTTP_OK/200 in case of success, HTTP_FORBIDDEN/403 in case of error)
 
 [Back to TOC](#table-of-contents)
 
diff --git a/build/post-handler.lua b/build/post-handler.lua
index 6a568f4..56fbcd1 100644
--- a/build/post-handler.lua
+++ b/build/post-handler.lua
@@ -5,21 +5,20 @@
 --
 
 local wampServer = require "wiola"
-local realm = "hga"
+local realm = "testRealm"
 
 local redisOk, redisErr = wampServer.setupRedis("unix:/tmp/redis.sock")
 if not redisOk then
 	return ngx.exit(444)
 end
 
---local req = ngx.var.request_body
 ngx.req.read_body()
 local req = ngx.req.get_body_data()
 
 local res, httpCode = wampServer.processPostData(ngx.var.connection, realm, req)
 
 ngx.status = httpCode
-ngx.say(res)
+ngx.say(res)    -- returns response to client
 
 -- to cause quit the whole request rather than the current phase handler
 ngx.exit(ngx.HTTP_OK)
diff --git a/src/wiola/post-handler.lua b/src/wiola/post-handler.lua
index 878d04b..143a42d 100644
--- a/src/wiola/post-handler.lua
+++ b/src/wiola/post-handler.lua
@@ -5,7 +5,7 @@
 --
 
 local wampServer = require "wiola"
-local realm = "hga"
+local realm = "testRealm"
 
 local redisOk, redisErr = wampServer.setupRedis("unix:/tmp/redis.sock")
 if not redisOk then
@@ -13,14 +13,13 @@ if not redisOk then
 	return ngx.exit(444)
 end
 
---local req = ngx.var.request_body
 ngx.req.read_body()
 local req = ngx.req.get_body_data()
 
 local res, httpCode = wampServer.processPostData(ngx.var.connection, realm, req)
 
 ngx.status = httpCode
-ngx.say(res)
+ngx.say(res)    -- returns response to client
 
 -- to cause quit the whole request rather than the current phase handler
 ngx.exit(ngx.HTTP_OK)