SOAP Services in Barracuda

Barracuda SOAP services are defined and written in Lua, in a simple text format.

These service definitions would normally be embedded in your server, but can be loaded dynamically or uploaded remotely if required, without rebuilding the server.

Barracuda will dynamically generate and publish the appropriate WSDL (Web Service Description Language) document from your installed sevice definitions. This dynamic generation means that the WSDL always reflects the currently installed services : there is no possibility of a mismatched service and WSDL.

Simple service definition

The following is all that is required to define a SOAP service called Info, with an operation called Date that returns the server's date:

soap_services = {
  Info = {
    Date = {
      output = {name = "return", type = "date"},
      call = function() return os.date("!%Y-%m-%d") end,
    },
  }
}

Note the type="date" declaration; Barracuda SOAP supports all XML Schema simple data types, with automatic conversion of double, string, decimal, and integer.

Here is a vbscript program that accesses the service defined above, assuming that Barracuda SOAP is configured to publish SOAP services on localhost/soap :

dim SOAPClient
set SOAPClient = createobject("MSSOAP.SOAPClient")

SOAPClient.mssoapinit("http://localhost/soap/info.wsdl")

wscript.echo "SOAP Server date is :", SOAPClient.Date()

Service Definitions in Detail

Barracuda SOAP services are defined as a Lua table called soap_services. This table defines one or more services; each service can support any number of operations.

An operation is a single remote procedure call (rpc).
Each named element in the soap_services table is a SOAP service definition, and must contain a list of operations supported by this service.
note: SOAP service, operation and parameter names must be valid XML names, as per the W3C XML spec.

Each operation is a table with the following defined members : input, output, call, and lifetime

input (optional)

If specified, input is a table (list) defining any input parameters to be passed to the call function.
Each parameter definition is a table with the following members:

name (mandatory)

a string definining the name of this parameter;

type (optional)

the data type, which defaults to "string". type can be one of :

A string defining an XML schema type, ie "integer",
A string defining an array of simple elements, defined by appending the word "Array" to a simple type, ie "stringArray",
A table defining a structured type.
Structured types are defined as a list (table) of members, each with a name and type element.
They can contain simple types and arrays, but not sub-structures.

For convenience, if only a single input parameter is specified, it need not be wrapped in a list, ie.
input={name="x", type="double"} is equivalent to input={{name="x", type="double"}}

output (optional)

If specified, output is a table (list) defining any parameters returned by the call function.
The structure of output parameters are identical to input, but since most client applications only support a single return value, multiple values are usually returned as a structure or array.

call (mandatory)

The call member is the Lua rpc function.
It will be called with the parameters defined by input, and is expected to return values as defined by output. Failure to return the results specified will result in an error message being sent to the client.
As a special case, if the call function returns nil followed by an error message, the server will return a SOAP error to the caller, with the error message supplied.

lifetime (optional)

a number defining the number of seconds the response remains valid. This value is used for cache control headers.
(The default value for response lifetimes is configured in the server).

Example service definitions

note : two dashes (--) indicates a comment in Lua; strings are enclosed with quotes (" "); tables are enclosed in a pair of braces ({ }); and table entries are seperated by a comma (,). (trailing commas are permitted). For the full Lua syntax, see the Lua documentation

client & server info :

 -- File: soap/.services/date.lua
soap_services = {

  Info = {

    HTTPVersion = {   -- returns the HTTP request version as a string.
      output = {name = "return",type = "string"},
      lifetime = 0, -- never cache
      call = function() return request:version() end,
    },

    Header = { -- returns a string with the value of the named HTTP header.
      input = {name = "name",type = "string"},
      output = {name = "value",type = "string"},
      lifetime = 0, -- never cache
      -- return empty string if no header
      call = function(s) return request:header(s) or "" end,
    },

    Date = { -- returns the current server date, in UTC
      lifetime = 5, -- date is valid for 5 seconds
      output = {name = "return",type = "date"},
      call = function() return os.date("!%Y-%m-%d") end,
    },

   }
}

a simple calculator :

 -- File: soap/.services/math.lua
soap_services = {

  Math = { -- service definition

    Add = { -- operation
      input = {{name = "x", type = "double"},{name = "y", type = "double"}},
      output = {name = "return",type = "double"},
      call = function(x,y) return x+y end
    }

    Subtract = { -- operation
      input = {{name = "x", type = "double"},{name = "y", type = "double"}},
      output = {name = "return",type = "double"},
      call = function(x,y) return x-y end
    }

    Multiply = { -- operation
      input = {{name = "x", type = "double"},{name = "y", type = "double"}},
      output = {name = "return",type = "double"},
      call = function(x,y) return x*y end
    }

    Divide = { -- operation
      input = {{name = "x", type = "double"},{name = "y", type = "double"}},
      output = {name = "return",type = "double"},
      call = function(x,y) return x/y end
    }

    Sum = { -- operation to sum an array of doubles
      input = {name = "t", type = "doubleArray"},
      output = {name = "return",type = "double"},
      call = function(t)
             local tot = 0
             for i,v in ipairs(t) do tot = tot+v end
             return tot
           end
    }

    RandomInt = { -- return random integer in the range 0-n
      input = {name = "range", type = "integer"},
      output = {name = "return",type = "integer"},
      call = function(range) return rnd(0,range) end,
    },

  } -- end of Math service definition
} -- end of soap_services definition

Barracuda Implementation

SOAP is implemented in Barracuda via a directory object, constructed by calling ba.create.soapdir(). The directory object can then be attached to the directory tree like any other Barracuda directory, with the same semantics and address resolution rules.

ba.create.soapdir(name, service-definition-loader, [wsdl lifetime], [rpc lifetime])

parameters

name (string)

The name of the directory, as it appears to the client

service-definition-loader (function)

The SOAP service definition loader is a function that loads the service definition and sets the environment for the loaded service definition.

local function serviceDefinitionLoader()
   -- io is the applications IO
   return function(env)
      local fnsource,err = io:loadfile("math.lua",env)
      if not fnsource then error("failed to load soap services : "..err) end
      return fnsource
   end
end

WSDL timeout (number)

The number of seconds the generated WSDL (web service description) is valid for. This is used to control cache and other HTTP headers in the WSDL response.

RPC timeout (number)

The number of seconds the data returned from an rpc call is valid for. This is used to control cache and other HTTP headers in the rpc response.

For each service defined, Barracuda will publish the a WSDL file at name/service name, and name/service name.wsdl.
The address for soap requests will be at name/service name.rpc.
name is relative to the parent directory object.

sample implementation

To implement the sample services above, create a text file with the service definitions as described above.
Then, in the Barracuda config file, create a SOAP service directory using
ba.create.soapdir("directory name", service-definition-loader), and attach it to the directory tree like any other Barracuda http dir.

ba.create.soapdir() will parse the supplied soap service config file, and create a SOAP service directory.
The SOAP directory will have an an entry for each service defined in the service config file.
In the case of the above sample config, and assuming that the directory name was "soap", Barracuda will publish the a WSDL file at "soap/Math" and "soap/Math.wsdl",
and the address for soap requests will be at "soap/Math.rpc".

note :Barracuda SOAP rpc and wsdl requests are handled the same regardless of case, ie soap/Math and soap/math will return the same reponse.

You can test for the existance of the soap service by pointing a web browser at the WSDL url.

The following complete example loads the above two service definition files "date.lua" and "math.lua", creates two soap directories, and installs the directories in the server:

-- The following code creates the two SOAP services from our documentation: 
-- https://realtimelogic.com/ba/doc/en/lua/soap.html

require"basoap" -- Install ba.create.soapdir

-- The applications I/O: We set the io as local variable since the
-- variable is used as an upvalue by function serviceloader
local io=io 

--Lua SOAP service loader
local function serviceloader(fname)
   -- io is the applications IO
   return function(env) -- Create Closure
      local fnsource,err = io:loadfile(fname,env)
      if not fnsource then error("failed to load soap services : "..err) end
      return fnsource
   end
end

local soapdir=ba.create.dir"soap"
local datedir=ba.create.soapdir("date",serviceloader"soap/.services/date.lua")
local mathdir=ba.create.soapdir("math",serviceloader"soap/.services/math.lua")

-- Install SOAP services in the Barracuda virtual file system
dir:insert(soapdir, true)
soapdir:insert(datedir, true) -- ./soap/date/
soapdir:insert(mathdir, true) -- ./soap/math/

Copyrights

Excel, MSWord, VB Script and .NET are copyright(C) Microsoft Corporation.