2012-04-13 10:38:12 +00:00
|
|
|
The Lua standalone engine has a message-based protocol for communicating between
|
|
|
|
PHP and Lua.
|
|
|
|
|
|
|
|
Messages start with a 16 byte header. The first 8 bytes are the body length in
|
|
|
|
hexadecimal. The second 8 bytes are (length * 2 - 1) also in hexadecimal.
|
|
|
|
|
|
|
|
For messages passed from PHP to Lua, the body is encoded as a Lua expression.
|
|
|
|
The expression may reference a table in a variable called "chunks", which
|
|
|
|
contains an array of functions.
|
|
|
|
|
2013-03-28 18:29:47 +00:00
|
|
|
Messages passed from Lua to PHP have their body encoded in PHP serialize()
|
|
|
|
format, and then "\\", "\r", and "\n" are replaced with "\\\\", "\\r", and
|
|
|
|
"\\n" to avoid issues with text-mode file handles. They may include instances
|
|
|
|
of function objects which have an "id" member for passing back to Lua as an
|
|
|
|
index in the chunk table.
|
2012-04-13 10:38:12 +00:00
|
|
|
|
|
|
|
The expressions encoded into the message bodies are associative arrays. The "op"
|
|
|
|
member of the array gives the operation to be performed by the message.
|
|
|
|
|
|
|
|
Every request message demands exactly one response message in reply. When a
|
|
|
|
request message is sent, the responder does not need to send the corresponding
|
|
|
|
response message as its next message. It may instead send its own request
|
|
|
|
message. In this way, a stack of pending requests can be accumulated. This
|
|
|
|
mechanism allows re-entrant and recursive calls.
|
|
|
|
|
|
|
|
All numerically-indexed arrays should start from index 1 unless otherwise
|
2013-01-28 21:05:18 +00:00
|
|
|
specified. Note that the number of values in an array may not match what Lua's
|
|
|
|
'#' operator returns if the array contains nils.
|
2012-04-13 10:38:12 +00:00
|
|
|
|
|
|
|
== Request messages sent from PHP to Lua ==
|
|
|
|
|
|
|
|
=== loadString ===
|
|
|
|
|
|
|
|
Load some executable Lua code (a "chunk") and return the resulting function ID.
|
|
|
|
|
|
|
|
Message parameters:
|
|
|
|
* op: "loadString"
|
|
|
|
* text: The string to load
|
|
|
|
* chunkName: The name of the string, for use in error messages
|
|
|
|
|
|
|
|
On success, the response message is:
|
|
|
|
|
|
|
|
* op: "return"
|
2013-01-28 21:05:18 +00:00
|
|
|
* nvalues: 1
|
2012-04-13 10:38:12 +00:00
|
|
|
* values: An array with a single element with the ID in it
|
|
|
|
|
|
|
|
On failure, the response message is:
|
|
|
|
|
|
|
|
* op: "error"
|
|
|
|
* value: The error message
|
|
|
|
|
|
|
|
=== call ===
|
|
|
|
|
|
|
|
Call a Lua function.
|
|
|
|
|
|
|
|
Message parameters:
|
|
|
|
* op: "call"
|
|
|
|
* id: The chunk ID
|
2013-01-28 21:05:18 +00:00
|
|
|
* nargs: Number of arguments, including nils
|
2012-04-13 10:38:12 +00:00
|
|
|
* args: The argument array
|
|
|
|
|
|
|
|
On success, the response message is:
|
|
|
|
|
|
|
|
* op: "return"
|
2013-01-28 21:05:18 +00:00
|
|
|
* nvalues: Number of return values, including nils
|
2012-04-13 10:38:12 +00:00
|
|
|
* values: All return values as an array
|
|
|
|
|
|
|
|
On failure, the response message is:
|
|
|
|
|
|
|
|
* op: "error"
|
|
|
|
* value: The value given to error(), usually an error message
|
2012-04-23 11:36:13 +00:00
|
|
|
* trace: A table giving a backtrace of the stack as it was when error() was
|
|
|
|
called, in a similar format to the one used by debug.getinfo(). Element 1 of
|
|
|
|
the table is the function that called error(), element 2 is the function that
|
|
|
|
called that, and so on.
|
2012-04-13 10:38:12 +00:00
|
|
|
|
|
|
|
=== registerLibrary ===
|
|
|
|
|
|
|
|
Register a set of functions in the sandbox environment.
|
|
|
|
|
|
|
|
Message parameters:
|
|
|
|
* op: "registerLibrary"
|
|
|
|
* name: The global variable name to register. May contain "." characters to
|
|
|
|
specify a global variable subtable.
|
|
|
|
* functions: An associative array mapping function name to ID
|
|
|
|
|
|
|
|
On success, the response message is:
|
|
|
|
|
|
|
|
* op: "return"
|
2013-01-28 21:05:18 +00:00
|
|
|
* nvalues: 0
|
2012-04-13 10:38:12 +00:00
|
|
|
* values: An empty array
|
|
|
|
|
|
|
|
On failure the response message is:
|
|
|
|
|
|
|
|
* op: "error"
|
|
|
|
* value: The error message
|
|
|
|
|
|
|
|
=== getStatus ===
|
|
|
|
|
|
|
|
Get status information about the Lua process.
|
|
|
|
|
|
|
|
Message parameters:
|
|
|
|
* op: "getStatus"
|
|
|
|
|
|
|
|
On success, the response message is:
|
|
|
|
|
|
|
|
* op: "return"
|
2013-01-28 21:05:18 +00:00
|
|
|
* nvalues: 1
|
2012-04-13 10:38:12 +00:00
|
|
|
* values: An array with a single element, which is an associative array mapping
|
|
|
|
status key to value. The status keys are:
|
|
|
|
** pid: The process identifier
|
|
|
|
** time: The amount of user and system time spent by the process, measured in clock ticks
|
|
|
|
** vsize: The virtual memory size in bytes
|
|
|
|
** rss: The resident set size in bytes
|
|
|
|
|
|
|
|
On failure, the response message is:
|
|
|
|
|
|
|
|
* op: "return"
|
2013-01-28 21:05:18 +00:00
|
|
|
* nvalues: 0
|
2012-04-13 10:38:12 +00:00
|
|
|
* values: An empty array
|
|
|
|
|
2013-11-01 00:04:12 +00:00
|
|
|
=== cleanupChunks ===
|
|
|
|
|
|
|
|
Tell Lua to release any chunks no longer referenced by PHP.
|
|
|
|
|
|
|
|
Message parameters:
|
|
|
|
* op: "cleanupChunks"
|
|
|
|
* ids: Table with keys being the chunk IDs still referenced by PHP, and non-falsey values
|
|
|
|
|
|
|
|
The response message is:
|
|
|
|
|
|
|
|
* op: "return"
|
|
|
|
* nvalues: 0
|
|
|
|
* values: An empty array
|
|
|
|
|
Added tests and fixed bugs
* Added unit tests for the two Lua interpreter classes
* Fixed a bug in checkType()
* Have Scribunto_LuaSandboxInterpreter throw an exception on construct
when the extension doesn't exist, to match the standalone behaviour.
* In Scribunto_LuaSandboxInterpreter, removed debugging statements
accidentally left in.
* Convert LuaSandboxTimeoutError to the appropriate common error
message.
* Moved the option munging from the sandbox engine to the interpreter,
so that the interpreter can be unit tested separately.
* Use /bin/sh instead of bash for lua_ulimit.sh, since dash is smaller
and still supports ulimit.
* Use exec to run the lua binary, so that the vsize of the shell doesn't
add to the memory limit.
* Added a quit function to the standalone interpreter. Unused at present.
* Don't add a comma after the last element of a table in a Lua
expression.
* Make the SIGXCPU detection work: proc_open() runs the command via a
shell, which reports signals in the child via the exit status, so
proc_get_status() will never return a valid termsig element.
* In MWServer:call(), fixed a bug causing the return values to be
wrapped in an array.
* Fixed a misunderstanding of what select() does.
* In MWServer:getStatus(), fixed indexes so that vsize will be correct.
Removed RSS, since it wasn't used anyway and turns out to be measured
in multiples of the page size, and I couldn't be bothered trying to
fetch that from getconf. Return the PID and vsize as numbers rather
than strings.
* Added a simple table dump feature to MWServer:debug().
* Fixed brackets in MWServer:tostring().
* Added missing Linux 32-bit binary.
Change-Id: Ibf5f4656b1c0a9f81287d363184c3fe9d2abdafd
2012-04-16 04:41:08 +00:00
|
|
|
=== quit ===
|
|
|
|
|
|
|
|
Request graceful shutdown.
|
|
|
|
|
|
|
|
Message parameters:
|
|
|
|
* op: "quit"
|
|
|
|
|
|
|
|
No return message will be sent.
|
|
|
|
|
2012-04-13 10:38:12 +00:00
|
|
|
== Request messages sent from Lua to PHP ==
|
|
|
|
|
|
|
|
=== call ===
|
|
|
|
|
|
|
|
Call a PHP function.
|
|
|
|
|
|
|
|
Message parameters:
|
|
|
|
* op: "call"
|
|
|
|
* id: The function ID given by registerLibrary
|
2013-01-28 21:05:18 +00:00
|
|
|
* nargs: Number of arguments, including nils
|
2012-04-13 10:38:12 +00:00
|
|
|
* args: An array giving the function arguments
|
|
|
|
|
|
|
|
On success, the response message is:
|
|
|
|
|
|
|
|
* op: "return"
|
2013-01-28 21:05:18 +00:00
|
|
|
* nvalues: Number of return values, including nils
|
2012-04-13 10:38:12 +00:00
|
|
|
* values: All return values as an array
|
|
|
|
|
|
|
|
On failure the response message is:
|
|
|
|
|
|
|
|
* op: "error"
|
|
|
|
* value: The error message
|
|
|
|
|