From 1b7a0a80eeafdc9e5b38019471485f7f4aed8383 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= <markus.makela@mariadb.com>
Date: Wed, 14 Dec 2016 15:10:31 +0200
Subject: [PATCH] Add luafilter documentation

The luafilter documentation describes the mechanics of how MaxScale will
call the lua scripts.
---
 Documentation/Documentation-Contents.md |  1 +
 Documentation/Filters/Luafilter.md      | 75 +++++++++++++++++++++++++
 2 files changed, 76 insertions(+)
 create mode 100644 Documentation/Filters/Luafilter.md

diff --git a/Documentation/Documentation-Contents.md b/Documentation/Documentation-Contents.md
index 594d870a5..91a008cb9 100644
--- a/Documentation/Documentation-Contents.md
+++ b/Documentation/Documentation-Contents.md
@@ -86,6 +86,7 @@ Here are detailed documents about the filters MariaDB MaxScale offers. They cont
  - [Database Firewall Filter](Filters/Database-Firewall-Filter.md)
  - [RabbitMQ Filter](Filters/RabbitMQ-Filter.md)
  - [Named Server Filter](Filters/Named-Server-Filter.md)
+ - [Luafilter](Filters/Luafilter.md)
  - [Gatekeeper - Adaptive Firewall](Filters/Gatekeeper.md)
 
 ## Monitors
diff --git a/Documentation/Filters/Luafilter.md b/Documentation/Filters/Luafilter.md
new file mode 100644
index 000000000..956592a74
--- /dev/null
+++ b/Documentation/Filters/Luafilter.md
@@ -0,0 +1,75 @@
+# Lua Filter
+
+The luafilter is a filter that calls a set of functions in a Lua script. The
+filter is currently a part of the experimental module set.
+
+Read the [Lua language documentation](https://www.lua.org/docs.html) for
+information on how to write Lua scripts.
+
+## Filter Parameters
+
+The luafilter has two parameters. They control which scripts will be called by
+the filter. Both parameters are optional but at least one should be defined. If
+both `global_script` and `session_script` are defined, the entry points in both
+scripts will be called.
+
+### `global_script`
+
+The global Lua script. The parameter value is a path to a readable Lua script
+which will be executed.
+
+This script will always be called with the same global Lua state and it can be
+used to build a global view of the whole service.
+
+### `session_script`
+
+The session level Lua script. The parameter value is a path to a readable Lua
+script which will be executed once for each session.
+
+Each session will have its own Lua state meaning that each session can have a
+unique Lua environment. Use this script to do session specific tasks.
+
+## Lua Script Calling Convention
+
+The entry points for the Lua script expect the following signatures:
+
+  - `nil createInstance()` - global script only, called when MaxScale is started
+
+    - The global script will be loaded in this function and executed once on a
+      global level before calling the createInstance function in the Lua script.
+
+  - `nil newSession()` - new session is created
+
+    - This function first loads the session script and executes in on a global
+      level.  After this, the newSession function in the Lua scripts is called.
+      There is a single C function exported as a global variable for the session
+      script named id_gen. The id_gen function returns an integer that is unique
+      for this service only. This function is only accessible to the session
+      level scripts.
+
+  - `nil closeSession()` - session is closed
+
+    - The `closeSession` function in the Lua scripts will be called.
+
+  - `(nil | bool | string) routeQuery(string)` - query is being routed
+  
+    - The Luafilter calls the `routeQuery` functions of both the session and the
+      global script.  The query is passed as a string parameter to the
+      routeQuery Lua function and the return values of the session specific
+      function, if any were returned, are interpreted. If the first value is
+      bool, it is interpreted as a decision whether to route the query or to
+      send an error packet to the client.  If it is a string, the current query
+      is replaced with the return value and the query will be routed. If nil is
+      returned, the query is routed normally.
+
+  - `nil clientReply()` - reply to a query is being routed
+
+    - This function calls the `clientReply` function of the Lua scripts.
+
+  - `string diagnostic()` - global script only, print diagnostic information
+
+    - This will call the matching `diagnostics` entry point in the Lua script. If
+      the Lua function returns a string, it will be printed to the client.
+
+These functions, if found in the script, will be called whenever a call to the
+matching entry point is made.