Lua XML-RPC Services

Note: XML-RPC is a legacy technology that predates modern web standards. While it's largely considered outdated today, we include support and documentation for those maintaining or integrating with older systems that still rely on it.

XML-RPC @ Wikipedia

Example:

-- Load the XML-RPC stack
local xmlrpc = require"xmlrpc"

-- Create the XML-RPC service
local xmlService  =  xmlrpc.new("service name", serviceDescription)

The XML-RPC stack parses the received XML into identical Lua objects. The response is handled in a similar manner, the XML-RPC stack automatically translates the response data to XML.

-- Load the XML-RPC stack
local xmlrpc = require"xmlrpc"

-- The "add" XML-RPC service
local function add(a,b)
   return a + b
end

-- The "subtract" XML-RPC service
local function subtract(a,b)
   return a - b
end

-- The Service Description Object used by
-- the XML-RPC constructors
local serviceDescription = {
   math={
      add=subtract,
      subtract=subtract,
   }
}

-- Create the XML-RPC service
local xmlService = xmlrpc.new("XML-RPC service", serviceDescription)

-- The directory callback function.
-- Service XML-RPC at relative path 'xml-rpc'
local function webservice(dir,func,path)
   if path == "xml-rpc" then
      xmlService:execute(request, response)
   else -- No other services
      response:senderror(404)
   end
end

 -- Create directory: "web-service"
dir = ba.create.dir("web-service", webservice)
ba.dirtop():insert(dir) -- Insert into first root directory

In the above example, the math service is made available at the following URL:
XML-RPC clients: http://localhost/web-service/xml-rpc

Binary Data and Time Conversion

The two XML-RPC types dateTime.iso8601 and base64 requires special handling.

dateTime.iso8601

Time can be sent using ISO 8601 encoding. A limitation with the Barracuda XML-RPC stack is that time can only be represented as UNIX time, in other words time cannot be before January 1, 1970.

Receiving:

A dateTime.iso8601 encoded XML-RPC time is automatically converted to a number if the time is within the accepted UNIX time range. A date/time outside of the UNIX time range is returned as a string.

Sending:

The following service function illustrates how to return iso8601 encoded data/time:

local function currentTimeService()
   return xmlrpc.iso8601(os.time())
end

base64

B64 encoding is typically used when sending binary data. A string in Lua may contain any bytes and one can therefore store binary data in Lua strings.

Receiving:

When the XML-RPC stack receives B64 encoded data, the data is automatically converted to a Lua string.

Sending:

When the XML-RPC stack converts the response from a Lua XML-RPC service function to XML, strings are by default converted to the XML-RPC string type. The XML-RPC stack can send a Lua string as B64 encoded data, but you must explicitly tell the XML-RPC stack to do the conversion. The conversion is done by calling xmlrpc.base64

The following two service functions return response data as a XML-RPC string and as XML-RPC base64 encoded data respectively:

local function myService1()
   return "This is a string"
end

local function myService2()
   return xmlrpc.base64("This is a string encoded as B64")
end