Merge pull request #1290 in SNORT/snort3 from lua_dev_notes to master

Squashed commit of the following:

commit 295f9e3f3471f0c92b655cc66ccb8023feec1ad9
Author: deramada <deramada@cisco.com>
Date:   Tue Jun 26 08:54:58 2018 -0400

    bad grammer

commit cc6f41f602fe450be66d1e62678e4ba156f59051
Author: deramada <deramada@cisco.com>
Date:   Tue Jun 26 08:42:11 2018 -0400

    fixup! appid: dev notes on lua detectors

commit c1d71ec9ed4d5f4ad9ae24495893ac7d44a34071
Author: deramada <deramada@cisco.com>
Date:   Mon Jun 25 17:01:34 2018 -0400

    appid: dev notes on lua detectors

diff --git a/src/network_inspectors/appid/dev_notes.txt b/src/network_inspectors/appid/dev_notes.txt
index 9fd5b8b30d417d8cd12e9e7c30bc6d0f707aa75f..47fba27e70a35f4f7f2f725d2cf16182a66d8f9b 100644 (file)
--- a/src/network_inspectors/appid/dev_notes.txt
+++ b/src/network_inspectors/appid/dev_notes.txt
@@ -115,7 +115,30 @@ any meta-data that has been extracted.  If more meta-data is expected the detect
 dispatched on subsequent packets until that process completes.  Otherwise the detection process is
 finished.  In either case the list of any other candidate detectors is purged.
 
-<NOTE: add description for Lua based detectors>
-
-
-
+As mentioned before, Lua detectors are client and service detectors written in Lua.
+LuaClientDetector and LuaServiceDetector subclass ClientDetector and ServiceDetector respectively to
+represent client and service Lua detectors.
+
+AppId's Lua API relies on Lua States to interact with Lua detectors. Every thread has an independent state
+and the detectors need to be initialized once per thread/state, whereas the C detectors, are only initialized
+once in the control thread. To mimic this behavior, session information is stored in a LuaStateDescriptor 
+object and is associated with every detector in a thread/state. The Lua detectors are initialized once in the 
+control thread and are shared by all the threads/states.
+
+During initialization and discovery there are multiple callbacks between C and Lua functions. To keep track 
+of the session and detector another layer of abstraction is added. The LuaObject class encapsulates a Lua
+detector and a LuaStateDescriptor object, it is stored in the Lua State and is accessed by C functions
+during Lua callbacks. LuaServiceObject and LuaClientObject subclass LuaObject to represent stateful (session)
+LuaServiceDetectors and LuaClientDetectors.
+
+When a Lua detector is initialized, a unique environment/table is created in the global registry of the
+Lua State and a LuaObject object is created in C. And when a detector is activated, a call is made to
+it's initialization function in Lua code and the corresponding LuaObject object is stored in it's local stack.
+Callbacks to C functions to register ports and patterns are processed only in the control thread and 
+ignored in the packet processing threads. 
+
+During discovery, if a Lua detector is selected based on a port or pattern and "validate" is called, 
+the table corresponding to that detector is pulled from the Lua State and a call is made to the 
+corresponding "validate" function in Lua code. The "validate" function in Lua can in turn make callbacks 
+to C functions and shares its local stack with the C function. These funtions make sure that the call 
+is made only during discovery before executing.