Lua/LSP API

Overview

Lua is an embeddable, extensible, extension language and is used in the Barracuda server for writing applications at a higher level than applications designed in C/C++ code. Applications designed in Lua are not limited to web-applications, thus Lua applications can be used as a method of designing your overall (embedded) application.

The Barracuda server and all plugins are designed by Real Time Logic, with the exception of the Lua scripting language. Lua uses the MIT license model and can therefore be used in commercial products.

In the Barracuda Embedded Web Server (BA), Lua code is typically activated by an event generated by C code. The following diagram illustrates the sequence of events:

In the above diagram, C code activates Lua code and the Lua code calls Lua C functions made available to the Lua script. C code that is made available to Lua code is referred to as Lua bindings.

The BA library provides a wealth of functions available to Lua script code. You simply provide the device management functionality for your platform. BA and Lua are designed to be extended and it is therefore easy to add your own device management functions. Making C functions available to Lua -- i.e. creating Lua bindings is described in the Lua book. One can also automate this task by using various tools designed to parse a C/C++ header and automatically create the Lua bindings for the C/C++ code. For example, our Online Lua Binding Generator is a tool that automatically creates Lua bindings from your C header files.

LSP

Lua Server Pages, or LSP for short, provides a simple and fast way of creating dynamically created web pages. LSP is similar to CSP, except that LSP does not need to be pre-compiled. However, LSP can be pre-compiled if desired.

Lua script can be freely intermixed with HTML or XML. LSP tags are XML compliant <?lsp ?>. Code between these tags is executed as Lua code. Expressions are provided by the <?lsp= ?> tag. The result of an expression is emitted as HTML/XML.

The standard LSP tags are recognized by most HTML editing tools and hence these tools can be used for creating dynamic LSP pages.

LSP can be used as an adjunct to CSP. CSP pages can include LSP pages and vice versa.

Like CSP, LSP can be loaded from a compressed directory.
LSP pages are available for any target platforms supported by the Barracuda Web Server.

A standalone executable Lua interpreter and a compiler are also provided. The standalone compiler is useful for testing LSP prior to deployment without the aid of a Web server.

HTTP Directories

Objects implementing directory functionality:

ba.create.dir
ba.create.resrdr
ba.create.dav
ba.create.wfs
ba.create.eh

Lua also provides a mechanism to construct the virtual directory tree used by the Web Server. This directory tree consists of C/C++ HttpDir objects. A directory structure specified with Lua is similar in performance to a C/C++ constructed tree; however, it is faster and easier to construct with Lua. With the ba.create family of functions, HttpDir derived objects such as WebDAV, HttpResRdr, etc., can be created in either preload scripts or LSP pages. The LSP directory function mirrors the Barracuda C/C++ APIs. All directory types provide a set of common methods. See the directory object for more information.

The Command (Request/Response) Environment

Lua has the concept of environments. Environments provide scoping for collections of variables. The standalone Lua interpreter provides one global environment known as _G. The LSP plugin provides the same global environment _G, but LSP also provides a short lived environment called the "request/response environment". This short lived environment is also known as the "command environment" or CMDE for short. Any global variables created in Lua Server Pages (LSP) and/or directory functions will be saved in this short lived command environment. The command environment is also the environment of any included or forwarded pages. Hence variables set in a LSP page will be available to included or forwarded pages.

The diagram to the right, shows the relationship between the command environment, directory functions, LSP pages, the LSP page's private page table, and the LSP page's application table. The command environment is automatically created when the first LSP page or directory function is executed. This environment lives for the lifetime of the request and is automatically terminated when the request completes. Global variables declared in this environment are available to all included and or forwarded pages. The environment is also available to directory functions.

Note: The diagram shows a hypothetical request where a LSP page delegates the request to another LSP page, then to a directory function, and so on. The purpose with this diagram is to show you the relations between objects. One would typically not delegate a request as deep as shown in the diagram to the right.

Directory Function
A directory function is a Lua function installed in one of dir, resrdr, dav, or eh. A directory function implements directory functionality for a dir, but extends and/or changes the behavior of a resrdr, dav, or eh. Directory functions are typically used in advanced web applications.

Thread Mapping and Coroutines

The Lua scripting language is not designed for preemptive context switching, but Lua provides a light weight threading mechanism called coroutines. In Barracuda(BA), Lua event generators are mapped to coroutines, thus each event triggered by BA has its own Lua stack. In BA, multiple events may be active simultaneously even though Lua is nonpreemptive. The BA Lua event generators are typically run by native threads on the C side and each native thread is mapped to a Lua coroutine. When a Lua coroutine is running, the thread may yield to another thread when a BA lua binding is called. For example, an LSP page may be preempted when calling response:write().

The following diagram gives an overview of the event and threading mechanism in BA:

The socket event dispatcher fires events when new data is available on a socket or if a non-blocking socket is ready for writing. The socket event dispatcher delegates client HTTP requests to the server thread pool which activates one of the threads. The thread searches for the resource and if found, executes the resource in a command environment. The resource may, for example, be an LSP page or a Lua directory function.

The socket event dispatcher can also fire events directly to Lua code if the auxiliary socket library is included. The Event Handler events are also run in the context of the dispatcher.

It is important that Lua code running directly in the context of the socket event dispatcher does not block as this will prevent the web-server from serving other requests. In general, Lua code should not block unless run in the context of the Server HTTP Thread Pool or the Lua Thread Library. Events run in the context of the dispatcher or the timer thread can delegate jobs to the Lua Thread Pool.

It is also possible to create user defined events, but this requires extensive knowledge of Lua. Please contact Real Time Logic if you plan on designing user defined events or if you create Lua bindings that may block for a prolonged time.

Introduction to Lua Authentication and Authorization

Authorizing Users

An authorizer object is created as follows:

local function authorizer(username, method, path)
     -- return true or false
 end
local  authorizer = ba.create.authorizer(authorizer)
dir:setauth(authenticator,authorizer)

The authorizer callback function must decide from the username, the HTTP method type, and the requested relative path if the user has access or not. The function returns true if the user has access and false or nothing if the user does not have access.

The authorizers must decide from username, method, and path if a user has access. You may want to authorize based on other criteria, and you have many options when it comes to authorizing user besides using the authorizer objects. Each LSP page can make its own decision or you can override the directory service function and implement a generic authorizer specifically tailored for your application.

The Authenticator Types

The authenticator example above is using HTTP digest authentication, which is the default if the type is not specified. The authenticator type can be specified by setting field "type" in the optional "option table".

local authenticator=ba.create.authenticator(authuser,{ type="basic" })

The following authenticator types can be specified:

"digest" - Use HTTP digest authentication, the default authenticator.
"basic" - Use HTTP basic authentication.
"form" - Use form based authentication. Form based authentication requires a custom response message handler that sends a login form to the user. The HTML form returned by the handler must have the two following input fields: ba_username and ba_password. See creating a custom response message handler for more information.
"sform" - Use form based authentication, but do not allow the password to be sent in clear text. In this mode, the password is only accepted if the connection is using SSL or if the password is cryptographically hashed. Note: the authenticator cannot prevent the password from being sent in clear text unless the response message handler is designed to make sure the user is either using a secure URL or that the password is cryptographically hashed. See the SHA1 cryptographic form example for how to send the password cryptographically hashed or see the force secure connection example for how to make sure the connection is secure.
"dav" - A specialized version of digest and basic authentication designed for WebDAV clients. Not all WebDAV clients can manage digest authentication and the "dav" authenticator gives the client the option of using either basic or digest authentication. The dav authenticator is using its own response message and will not use your custom response message handler if provided. Also see response:setdigest().
"auth" - An all in one authenticator type that implements basic, digest, and form based authentication. The authenticator is designed for server applications that accept a mix of browser based and non browser based clients. For example, a non browser based client typically does not accept form based authentication and requires either digest or basic HTTP authentication.
See also
response:setbasic()
response:setdigest()

The authenticator uses digest or basic authentication if the client is directly specifying the authentication type by setting the "Authorization" header. Command based and HTTP client libraries integrated with applications typically set the "Authorization" header before sending the request. The authenticator also checks if the client sends a Barracuda specific "PrefAuth" HTTP header which should be set to basic or digest.

The authenticator defaults to digest authentication if the type is not specified and the request is for a non text based URL or if the request originates from a JQuery AJAX call.

The authenticator defaults to form based authentication if the authentication is not specified and if the request is for an .html, .lsp, or .csp file.

The "auth" authenticator requires a custom response message handler, which is typically more complex to design than custom response message handlers for the other authenticator types.

Creating a Custom Response Message Handler

A login response message handler is responsible for sending login information and login failed information to a client. The function is not called unless the client requires login information, or if the authenticator failed to authenticate the client, or if the client is denied by the authenticator, or an installed login tracker denied the request.

From the above login sequence, the response handler is called when the user requests a protected resource (1). The response handler requests the user credentials (2) by sending login information to the client. Note: The response handler should send response data but must not set the HTTP authorization header since this header is managed by the the authenticator. The response handler is also called if the username and/or password does not match (3).

The following example shows how to create a login response message handler for form based authentication:

-- Custom Response Message Handler
local function loginresponse(_ENV, authinfo)
   if authinfo.username then response:forward".loginfailed.lsp" end
   response:forward".loginform.lsp"
end
local authenticator=ba.create.authenticator(
   authuser,{type="form", response=loginresponse})

The _ENV variable is the command environment where globals such as the request and response objects are found.

The authinfo is a table with information about the login status. The username is set if the user failed to login. The username is not set when the client requests the login page. Notice that we are not using an "else" statement when forwarding the request to the login form. The "else" statement is not needed since response:forward by default does not return to sender, thus the code below ".loginfailed.lsp" will not execute unless username is not set. The pages ".loginform.lsp" and ".loginfailed.lsp" are regular LSP pages that send HTML login information and error information to the client.

Authentication Examples

The Do It Yorself (DIY) tutorial bundled with the Barracuda Server's combined demo and tutorial includes a number of interactive authentication examples.

Creating a Form Response Message Handler

Form based authentication requires a custom response message handler. The response handler can emit the complete response page, but it is easier to create a response handler that forwards the request to a dedicated LSP page. The following example shows how to create the ".loginform.lsp" page for the form response message handler we showed previously.

<html>
  <body>
    <form method="post">
      Username: <input type="text" name="ba_username"><br>
      Password: <input type="password" name="ba_password"><br>
      <input type="submit" value="Login">
    </form>
  </body>
</html>

The above HTML form includes the two required form fields ba_username and ba_password. Pressing the submit button sends the login information in clear text to the server. It is for this reason that one should use a secure (SSL) connection when using form based authentication. See the " force secure connection" example for more information.

Using form based authentication safely without using SSL

The form authenticator supports cryptographic hashing and implements an authentication scheme similar to digest authentication, which allows user identity to be established securely without having to send a password in plaintext over the network. The form authenticator adds two additional fields to the authinfo table that can be used by the response handler when creating the login form.

The following examples show how to create a form response message handler and a LSP login form that supports cryptographic hashing.

Form response message handler:

We must make a modification to the the form response message handler we showed previously such that the response handler supports our new form login page.

local function loginresponse(_ENV, au)
   authinfo=au -- Set authinfo in the global command environment
   if authinfo.username then response:forward".loginfailed.lsp" end
   response:forward".loginform.lsp"
end

The code above is similar to our previous example, except for that we make the variable authinfo available in the command environment. We can use authinfo in the the new ".loginform.lsp" page by making authinfo global in the command environment.

Form login page:

The new ".loginform.lsp" page includes two JavaScript files and two new form fields. We have also changed the "submit" button to a standard html button. Changing the submit button to a standard button makes it impossible to submit the form if JavaScript is disabled, thus preventing the password from being sent in clear text.

<html>
  <head>
    <script src="/rtl/jquery.js"></script>
    <script src="/rtl/sha1.js"></script>
  </head>
  <body>
    <form method="post">
      Username: <input type="text" name="ba_username"><br>
      Password: <input type="password" name="ba_password" autocomplete="off"><br>
      <input type="hidden" name="ba_seed" value="<?lsp = authinfo.seed ?>">
      <input type="hidden" name="ba_seedkey" value="<?lsp = authinfo.seedkey ?>">
      <input type="button" id="ba_loginbut" value="Login">
    </form>
  </body>
</html>

Notice how we dynamically create the two form fields ba_seed and ba_seedkey by using LSP and the values in the authinfo Lua table. The global authinfo table was made available to the LSP page by the response handler above. The form does not include any JavaScript code. The JavaScript code in "sha1.js" is intelligent and auto discovers the HTML form with the fields ba_password, ba_seed, and the button with id="ba_loginbut". These fields are required by the JavaScript code, which automatically calculates a SHA-1 hash from the password and the seed value. The seedkey is required by the authenticator in the server when the form is submitted. The user will not be able to login if any of these fields are missing.

The two JavaScript files are found in the Barracuda SDK /WebResources/ directory. The two pre-compiled servers that come with the SDK includes these two files in the integrated ZIP file and makes them available in the /rtl/ directory. The JavaScript file sha1.js requires jquery.js

Many browsers give the user the option of saving the username and password in the browser. The JavaScript code run when pressing the login button replaces the password entered by the user by the SHA1 hash before submitting the page, thus making it impossible for the user to save the password. This feature increases security but degrades the user experience. If you want the user to be able to save the password, make the following changes to the HTML form:

    <form method="post">
      Username: <input type="text" name="ba_username"><br>
      Password: <input type="password" id="ba_password2"><br>
      <input type="hidden" name="ba_password">
      <input type="hidden" name="ba_seed" value="<?lsp=authinfo.seed?>">
      <input type="hidden" name="ba_seedkey" value="<?lsp=authinfo.seedkey?>">
      <input type="button" id="ba_loginbut" value="Login">
    </form>

The ba_password is now changed to a hidden variable and the password field is using the id="ba_password2". Notice that we are using an id and not a name attribute for ba_bassword2. Form fields without a name are not submitting to the server, which is what we want -- i.e. we want to prevent the password from being sent in clear text. The JavaScript code in sha1.js is designed to look for this combination. The hash is created from ba_password2 + seed and inserted into ba_password. The above construction allows the user to save the password in some browsers.

Force Secure Connection

Basic and form based authentication is unsafe unless the login information is sent over a secure connection. The following example makes sure the client is using a secure connection:

-- Create a secure URL from  URI (path)
-- cmd is the request and response object.
local function getSecureUrl(cmd)
   local host = cmd:header"host"
   -- Use host header if sent by client, otherwise use IP addr
   if host then
      host = string.gsub(host,":%d+","") -- Strip port number, if any
   else
      host = cmd:sockname()
  end
  -- Create the secure URL
  local url = "https://"..host
  return cmd:encoderedirecturl(url..cmd:uri(), true)
end

-- The username/password callback function.
-- Notice how we use the optional _ENV command environment.
local function getpassword(username, _ENV)
   if not request:issecure() then
      -- Deny login: send redirect request
      response:sendredirect(getSecureUrl(request))
      -- sendredirect does not return to caller.
   end
   if username == "admin" then return "admin" end
end
-- Create the username database from our getpassword func.
local authuser=ba.create.authuser(getpassword)

-- The login response message handler
local function loginresponse(_ENV, authinfo)
   if not request:issecure() then
      -- Remove Authorization header set by basic or digest authenticator
      response:setheader("Authorization",nil)
      -- sendredirect does not return
      response:sendredirect(getSecureUrl(request))
   end
   -- The connection is secure if we get this far.
   if authinfo.username then response:forward".loginfailed.lsp" end
   response:forward".loginform.lsp"
end

local authenticator=ba.create.authenticator(authuser,{response=loginresponse})
dir=ba.create.dir()
dir:insert()
dir:setauth(authenticator)

The login response message handler checks if the URL is secure, and if it is not, sends a redirect request to the client. Removing the "Authorization" header set by the authenticator is necessary if using Digest or Basic authorization since we do not want the client to send the credentials before using a secure connection.

A client normally starts by requesting a secure resource without providing the user's credentials (1), but a non browser client such as a HTTP client library may directly send the credentials (3). The password is sent in clear text and an eavesdropper could intercept the password. We cannot prevent this on the server, but we can change the getpassword() function to ignore the login request and force the connection to a secure connection. The response is not normally committed in a getpassword() function, but the authenticators are designed such that they assume the getpassword() function sent a "denied" request if the response is committed. Method response:sendredirect commits the response.

Note: The modified getpassword() function with the secure redirect is not needed if using the shtml authenticator since the secure form authenticator denies all non secure requests and delegates the request directly to the response message handler.

External Lua Links

Barracuda Lua APIs

Each LSP page is provided with some predefined variables and objects; namely, request, response, cookie, session and page.

request object

The request object is a global variable in the command environment and is available to directory functions and LSP pages. The request object provides information sent by the client to the server.

request example

<html>
<!-- request example usage -->
<?lsp
  -- has the page been modified in the last 2 minutes
  print("<h2>request methods</h2>");
  print("<pre>");
  request:checktime(response, os.time() - 120)
  print("request:checktime(response,os.time() - 120)");
  print("request:user() ", request:user())
  print("request:cookie'z9ZAqJtI'", request:cookie"z9ZAqJtI")
  print("request:header'User-Agent'", request:header"User-Agent")
  print("\nAll request headers")
  for k,v in next, request:header() do print(k,'=',v) end
  print("\nrequest:method() ", request:method())
  print("request:uri() ", request:uri())
  local t =request:data()
  print("request:data() ", request:data())
  for k,v in next, t do print("\t",k,'=',v) end

  print("\nrequest:session() ", request:session(true))
  if request:session() then
    print("session id", request:session():id(),"\n")
  end
  print("request:version() ", request:version())
  print("</pre>")
?>
</html>

The request object has the following methods:

request:abort()

This method, which aborts the execution, is the same as response:abort().

request:allow({methods, ...,} [, usedefaults])

The allow() method checks if the HTTP request method is one of the HTTP methods specified in the parameter list. The function will cause the script to terminate if the request method is not one the allowed methods and the status code is set to 405 (method not allowed).
If the request method is allowed then allow() returns true.
allow() also terminates the script when the request method is only 'OPTIONS'.
By default the methods OPTIONS and HEAD are added automatically to an allowed option list, setting the second parameter to false prevents these defaults from being automatically added.
This function is typically used at the start of a LSP or directory function.

Example,

  -- only allow GET and POST for this page
  request:allow{"GET", "POST"} -- Auto abort script if not GET or POST

  -- valid request; let's continue
  print"hello world"

request:certificate()

Returns the peer's certificate chain as a table if the connection is secure and the peer sent a certificate. A second return value is set to true if the certificate is valid i.e. if validated by the certificate store.
Note: this function requires that the auxiliary API sharkssl is installed.

request:checktime(time)

Handles the "If-Modified-Since" request header.
The time parameter is effectively what you wish to be the last modified time of the LSP. If the parameter time is newer or the same as the request "If-Modified-Since" time, then the function returns true.
The function sends a "304 Not modified" response to the client and terminates the script if the parameter time is older than the request "If-Modified-Since".

Example,

   -- switch off the default cache headers
   response:setheader"Cache-control"
   response:setheader"Pragma"

  -- check the modified time (anything up to a day old)
  if not request:checktime(os.time() - (60*60*24)) then return end

  -- lets provide the updated page
  print"hello world"

request:user()

Returns the name, application name, and authentication type of an authenticated user for this request, if one exists for the request. If there is no authenticated user, the function returns: false,name -- where name is the application name.
Possible values of the authentication type are; 'form', 'basic' and 'digest'.

request:logout([all])

Logout the request user and terminates the session. The optional parameter 'all' defaults to false. Set 'all' to true if you want to terminate all of the user's active sessions. A user may be logged in using more than one client. One must typically set all=true when changing password since all clients must be terminated or the clients may get a 403 response. If there is no authenticated user, then false is returned.

request:cookie(cookie name)

Returns the named cookie object.

request:env()

returns the command environment.

request:header([header name])

Returns a string with the value of the named HTTP header. If no parameter is provided, then a table containing all request header name/value pairs is returned.

request:domain()

Returns the host header without any port number. Typically used with name-based virtual hosting. The returned value is always lowercase. Returns the client's IP address if the client did not provide the host header.

request:method()

Returns the name of the request method. e.g. GET, POST, etc.

request:data([name ...])

When name is not provided returns a table containing any POST or QUERY data sent to the server. The table may be empty if there is no POST or QUERY data.
When one or names are provided the values of these names are returned.
Note this function will not return multiple values. If this is required use datapairs().
Example,

  -- get some values
  custnbr = request:data("custnbr")        -- get the value of custnbr
  name, num = request:data("name", "num")  -- get two values

  -- display posted values
  for name,value in pairs(request:data()) do
    print(name,'=',value)
  end

request:datapairs()

An iterator that will traverse of all name/value pairs that have been sent to the server with POST or GET.
Example,

  -- display all posted values
  for name,value in request:datapairs() do
    print(name,'=',value)
  end

request:rawrdr([blocksize])

See also
request:multipart
ba.create.upload

Returns a function that can be used as an iterator for reading PUT and POST data. You cannot use this function for posted www-url-encoded or multi-part data. The function throws an exception if the following conditions are met:

Request is missing content-length and not chunk encoding.
Request is of type URL encoded data. URL encoded data is handled directly by the server. See request:data or request:datapairs for more information.
Request is of type multipart/form-data. You must use request:multipart

The returned function also takes an optional blocksize as its only parameter. The default blocksize varies depending on the platform. For example, Windows is usually 512 and UNIX is usually 1024.

The iterator returned transparently handles chunk encoded data. A client can either set a content length or send data using chunk encoding.

The following LSP example echoes the uploaded data back to the client:

<?lsp
for data in request:rawrdr() do
   response:write(data)
end
?>

See also
request:rawrdr
ba.create.upload

request:multipart(callbacks[,bufsize][,keepAlive])

Decode multi-part encoded POST data. Calling this function starts a multi byte parser, which calls your callbacks as data is parsed from the data stream.

The parser allocates "bufsize" bytes for temporary storage. The buffer must not be smaller than the content size of the largest input field element of type "text" or textarea. The default value is 8K.

You can optionally set keepAlive to false if you want the web-server to close the connection after the upload is completed and you have sent a response message to the client.

Argument callbacks is a table with callback functions:

formdata(name, value)
beginfile(name, filename, contenttype, transferencoding)
filedata(data)
endmp()
error(emsg)

The functions are optional. The data is simply discarded if the multi byte stream contains data not handled by a callback. The function(s) can terminate the multi byte stream parsing by returning false.

Callback function formdata is called for each input field in the form. For example, the function will be called twice if you have the following form:

<form method="post" enctype="multipart/form-data">
<input type="text" name="Text input" />
<textarea name="Text area" cols="40" rows="3"></textarea>
</form>

Callback functions beginfile and filedata are called if the form contains an input of type "file". For example, the function beginfile will be called twice if you have the following form and the filedata function is called repeatedly to give you data as it trickles in.

<form method="post" enctype="multipart/form-data">
<input type='file' size='40' name='File 1'/>
<input type='file' size='40' name='File 2'/>
</form>

Callback function beginfile(name, filename, contenttype, transferencoding) arguments:

name -	the name as specified in the HTML "input" type.
fileName -	the name and possible path of the file entered by the user. The path separator is platform dependent.
contentType -	the content mime type such as "text/plain". This parameter is NULL if not specified in the multipart data stream.
contentTransferEncoding -	the transfer encoding such as "gzip". This parameter is NULL if not specified in the multipart data stream.

Callback function filedata(data) arguments:

data -

the received chunk.

Callback function endmp() is called at the end of the multi byte stream sent from the client.

Callback function error(emsg) is called if either parsing the multi byte stream failed or the connection closed.

request:uri()

Returns the request URI. e.g. /myrequest.lsp

request:url()

Returns the request URL. e.g. http://localhost/myrequest.lsp. This value is also returned by the tostring(request) function.

request:session([create])

Returns the current session object associated with this request or, if there is no current session and create is true, returns a new session. If create is false and the request has no valid session, this method returns false. To make sure the session is properly maintained, you must call this method before the response is committed. The default value of create is `false'.

request:version()

Returns the HTTP request version as a string.

request:issecure()

Returns true if a HTTPS connection is being used.

request:peername()

Returns a string of the client name/IP address and the connected port number.

request:sockname()

Returns a string of the server name/IP address and the connected port number.

request:setnodelay(bool)

Disable or enable the Nagle algorithm.

response object

The response object is a global variable in the command environment and is available to directory functions and LSP pages. The response object provides methods that can be used when sending messages to the client. Most of the response methods return nil, error-message, when an error is encountered.

response:abort()

Abort the execution of the LSP page or directory function. This function may also abort across page boundaries if response:forward/redirect and response:include sets the optional "return to caller" false.

response:bytecount()

The number of bytes that have been sent to the client.

response:containsheader(header name)

Searches the internal response header database for a header with the specified name. If the header does not exist, the function returns false.

response:clearkeepalive()

Causes a close of the current connection after the response is sent.

response:createcookie(cookie name)

Creates a cookie with the provided name. The cookie object is returned.

response:downgrade()

Changes the protocol to HTTP/1.0.

response:encoderedirecturl(url [, withdata [, sessionURL]])

Encodes the specified URL into an absolute URL, or if encoding is not needed, returns the URL unchanged.

If the withdata parameter is specified and is true, this method also includes all url-encoded parameters in the request line and in the body if the client sent a POST message.

If the sessionURL parameter is specified in addition to withdata and a session is defined for the client, then this method encodes as above but also includes the Barracuda session ID as &z9ZAqJtI=ID.

response:encodeurl(path)

Translates a path to characters that are safe for use in a URL. For example, the following path "a/../path/with spaces" is translated to: "path/with%20spaces". Note, URL encoded parameters, if any, are not translated.

response:flush()

Forces any content in the response write buffer to be written to the client. A call to this method automatically commits the response, meaning the status code and headers will be written.

response:forward(path [,return2caller])

response:redirect(path[,return2caller])

See also
response:include
directory functions

Forwards a request from this LSP page to another resource (directory function, LSP page, CSP page, HTML file, etc). This method allows one LSP page to do preliminary processing of a request and another resource to generate the response (Request delegation). forward() should be called before the response has been committed to the client (before response body output has been flushed). This method throws an error if the response has already been committed or if the resource is not found. Any data in the response buffer is erased when the request is forwarded.

The forwarded page gets the same the Lua environment as the originating page. See the request environment for more information.

The path is the resource where you want to delegate the request. The path is assumed to be an absolute path value on the server if the string starts with "/". The path is otherwise assumed to be relative to the directory of the current page.

The return2caller is a boolean value that defaults to false. You must set this value to true if you want to return to the calling Lua script after forward has completed.

Redirect:
Method forward is similar to method redirect, with the exception that forward bypasses any form of required authentication and/or authentication.

response:include(path[,return2caller])

See also
response:forward
ba.parselsp
directory functions

Includes the content of a resource (directory function, LSP page, CSP page, HTML file, etc) in the response. In essence, this method enables programmatic server side includes. See the introduction to Request Delegation for more information. The response object has its path elements and parameters remain unchanged from the caller's. The included servlet cannot change the response status code or set headers; any attempt to make a change is ignored.

The included page gets the same the Lua environment as the originating page. See the request environment for more information.

The path is the resource you want to include (embed). The path is assumed to be an absolute path value on the server if the string starts with "/". The path is otherwise assumed to be relative to the directory of the current page.

The return2caller is a boolean value that defaults to true. Setting this variable to false will normally still make the call return to caller unless the included page calls method such as response:sendredirect, or any other method that aborts the request.

response:committed()

Returns a boolean (true/false) indicating if the response has been committed. A committed response has already had its status code and headers sent to the client. You cannot set response headers or response status if the response is committed. The server maintains a response buffer. The size of the response buffer is configured by the C startup code.

response:env()

returns the command environment.

response:initial()

Returns false if this is an include or forward from another directory function or LSP file; that is, the first page called during the request processing. Note, directory functions can optionally decide if the page is a "forwarded" page or not.

response:isforward()

Returns true if this is a forward request from another another directory function or LSP file. The second return value is the count of the number of times that the request has been forwarded. Note, directory functions can optionally decide if the page is a "forwarded" page or not.

response:isinclude()

Returns true if this is an include from another LSP file. The second return value is the count of the number of times that the request has been included.

response:getdata()

Returns the response data or nil if data is committed. Typically used by advanced directory functions.

response:getstatus()

Returns the HTTP status code. Typically used by advanced directory functions.

response:json(table[,table]* [ret2caller])

Encode Lua table(s) as JSON and send the response. The function simplifies sending JSON response data to a client. The function accepts multiple tables. The following example illustrates how this function is implemented when only one table is supplied:

function response:json(table,ret2caller)
   local data=ba.json.encode(table)
   response:reset()
   response:setheader("Content-Type","application/json")
   response:setheader("Cache-Control",
               "no-store, no-cache, must-revalidate, max-age=0")
   response:setcontentlength(#data) 
   response:send(data)
   if(ret2caller) then return true end
   response:abort()
end

response:reset([string])

Clears any data that exists in the buffer as well as the status code and headers. Clears the content of the underlying buffer in the response without clearing headers or status code. The optional string parameter may be "headers" or "buffer", if not supplied both headers and buffers are cleared. If the response has been committed, this method returns false.

response:send(data)

An advanced function that sends data to the client. You must make sure you set the content length before sending data to the client. This function differs from response:write in that data is not sent using chunk transfer encoding and therefore requires a content-length.

response:senderror(code [, message])

Sends an error response as a simple HTML page to the client using the specified status code. An optional message can be sent with the response code. If the response has been committed, this method returns false.

response:sendredirect(url [,302 [,return2caller]])

Sends a temporary redirect response to the client using the specified redirect location URL. A relative URL is automatically converted to an absolute URL during this call.

This function, by default, sends a 302 (temporary redirect). Set second argument to true if you want to send a 301 permanent redirect message.

This function, by default, does not return to the caller. Set the third argument to true if you want to return control to the caller. The default is for the server to automatically roll back the call chain to prevent writing to the response data after the redirect request is sent to the client.

example:

response:sendredirect"../start.html";
 -- Send a permanent redirect request
response:sendredirect("http://realtimelogic.com", true);

response:setbasic(realm)

response:setdigest(realm)

Set the status code and HTTP basic or digest authenticate headers. The methods are typically used in a response message handler, when using the auth type authenticator, to force a client into authenticate using HTTP authentication.

response:setcontentlength(length)

Sets the "Content-Length" header value. If the header had already been set, the new value overwrites the previous one. LSP response data is normally sent chunk encoded and the HTTP header Transfer-Encoding: chunked is automatically set by the Web Server. Calling setcontentlength changes the internal state in the web-server to raw-response-writing and removes the Transfer-Encoding header, if previously set.

response:setcontenttype(type)

Sets the "Content-Type" header. type is a type string. e.g. "text/plain"

response:setdateheader(name, time)

Sets a response header with the given name and date value (time). The date is specified in terms of seconds. If the header had already been set, the new value overwrites the previous one. The response:containsheader() method can be used to test for the presence of a header before setting its value.
name is the name of the header to set (e.g. "Expires").
time the assigned time value in number of seconds elapsed since midnight (00:00:00), January 1, 1970. This is the time format returned by os.time().

response:setdefaultheaders()

Sets the most common header values in LSP files. Sets content type to "text/html" and sets the header "Cache-Control" to "No-Cache". This method is automatically inserted by the LSP page.

response:setheader(name [, value])

Sets a HTTP response header with the given name and value. If the header had already been set, the new value overwrites the previous one. The response:containsheader method can be used to test for the presence of a header before setting its value. If the value is not provided then the named header is removed from the response.
setheader() should be called before the response has been committed to the client, (before response body output has been flushed). If the response already has been committed, this method returns false.

response:setmaxage(seconds)

Sets header "Cache-Control: max-age=seconds". Can, for example, be used by LSP code to override the default headers inserted by the LSP page. See response:setdefaultheaders() for more information.

response:setresponse(function|true|false)

Sets a HTTP response filter that either filters the response data or traps/redirects the response data. The filter works with any resource that uses the standard buffered output functions such as response:write and the C/C++ versions such as HttpResponse::printf. The filter does not function if the response is delegated to a C/C++ resource using the non-buffered function HttpResponse:send. In other words, one cannot delegate the response to a WebDAV, or HttpResRdr. However, one can delegate the response to a LSP enabled HttpResRdr if the requested resource is a LSP page.

response:setresponse(function) Installs a generic filter function
response:setresponse([false]) Enables deflate compression using RFC1951
response:setresponse(true) Enables deflate compression using RFC1950

setresponse() returns an object with two methods:
obj:abort() Revert to the original HTTP response buffer. Returns true on success and false if response data is committed.
obj:finalize(true|false)

obj:finalize(true) sends compressed data to the client if setresponse is in compress mode.
obj:finalize([false]) returns the compressed data if setresponse is in compress mode.
obj:finalize() flushes any remaining data to the callback function if setresponse is in generic filter mode.

See the examples for more information on how to use method finalize().

local function serviceFunc(dir,func,path)
   local ae = request:header("Accept-Encoding")
   -- If requesting a LSP file and the client accepts deflate compression
   if path:find("%.lsp$") and ae and ae:find("deflate") then
      local xrsp = response:setresponse() -- Activate compression
      local found = func(path) -- Run the resource manager's service function
      if found then
         response:setcontenttype("text/html")
         xrsp:finalize(true) -- Send compressed data to client
         -- Above sets Content-Encoding and Content-Length before sending data
         return true -- LSP page (resource) found
      end
      xrsp:finalize() -- Not found, but we must clean up
      return false -- Resource not found
   end
   return func(path) -- Service request without using compression
end

-- Create a LSP application
myApp = ba.create.resrdr("MyDir",serviceFunc,0, myIo)
myApp:lspfilter() -- Enable LSP

In the above example, a directory function is created and inserted into the resource manager's constructor. The directory function is used as a filter. The filter function analyzes the request and enables compression if the client supports deflate compression. The resource manager's service function (func) is passed in as the second argument to the filter service function (serviceFunc). We must call this function which runs the requested LSP page. We cannot enable compression for non LSP resources so we check to see if the request is for a LSP page or not -- i.e. we check if the requested resource ends with .lsp.

Calling xrsp:finalize(true) after the resource manager's service function has rendered the response assembles all data and sends the data to the client. The default for the finalize method is to return the data and not send the data to the client. The following example shows a modified service function that fetches the compressed data and sends the data to the client using response:write.

local function serviceFunc(dir,func,path)
   local ae = request:header("Accept-Encoding")
   -- If requesting a LSP file and the client accepts deflate compression
   if path:find("%.lsp$") and ae and ae:find("deflate") then
      local xrsp = response:setresponse() -- Activate compression
      local found = func(path) -- Run the resource manager's service function
      if found then
         local data=xrsp:finalize() -- Fetch compressed data
         response:setcontenttype("text/html")
         response:setcontentlength(#data)
         response:setheader("Content-Encoding", "deflate")
         response:write(data) -- Write is now the standard socket write
         return true -- LSP page (resource) found
      end
      xrsp:finalize() -- Not found, but we must clean up
      return false -- Resource not found
   end
   return func(path) -- Service request without using compression
end

Fetching the data by calling finalize() instead of directly sending the data by calling finalize(true) is useful in an application that implements caching. A service function may be designed such that it knows how to cache dynamically generated LSP data.

As an example, a cache can be implemented by using a table.

local function serviceFunc(dir,func,path)
   if pageCacheTable[path] then
      sendCachedPage(pageCacheTable[path])
      return true -- found
   end
   -- Not in cache
   .
   .

The most common use of HTTP filters is to compress response data and the above methods are optimized for this functionality. If you have uses other than for compressing the response, a generic filter function can be installed. The following example installs a filter function by calling response:setresponse(myRespFilter).

local function serviceFunc(dir,func,path)
   -- If requesting a LSP page
   if path:find("%.lsp$") then

      -- Create a table for storing response data and a function to collect
      local dataTable={}
      local function myRespFilter(data)
         table.insert(dataTable, data)
      end

       -- Activate response filter
      local xrsp = response:setresponse(myRespFilter)

      local found = func(path) -- Run the resource manager's service function
      xrsp:finalize() -- Cleanup

      if found then
         local data
         local ae = request:header("Accept-Encoding")
         -- If client accepts deflate compression
         if ae and ae:find("deflate") then
            response:setheader("Content-Encoding", "deflate")
            data = ba.deflate(dataTable) -- Compress and assemble response data
         else
            data = table.concat(dataTable) -- Assemble response data
         end
         response:setcontenttype("text/html")
         response:setcontentlength(#data)
         response:write(data) -- Write compressed or non compressed data
         return true -- LSP page (resource) found
      end
      return false -- Resource not found
   end
   return func(path) -- Service request without using compression
end

In the above example, the myRespFilter callback function is called when the internal web-server buffer is full. The number of times the myRespFilter callback function is called is a function of (LSP data size / internal web-server buffer size). At a minimum, the function is called once when finalize() is called. Note that the internal web-server buffer can be configured by C/C++ code at startup.

Response data is inserted into a table, which is assembled into compressed data if the client supports compression or uncompressed data if the client does not support compression.

Other uses

In addition to what is shown in the above examples, the HTTP filter also works on resources either included or delegated -- i.e. response:include and response:forward. The filter works with any resource that is dynamically creating the response data such as CSP resources and CGI resources.

response:setstatus(status)

Sets the status code for this response. This method is used to set the return status code when there is no error (for example, for the status code 304 Not Modified). If there is an error, the senderror() method should be used instead. setstatus() should be called before the response has been committed to the client (before response body output has been flushed). If the response already has been committed, this method returns a non zero value.

response:write(string, ...)

Send data to the client using chunk encoding, the default LSP encoding. Note: the data is added to the response buffer, if not full. The response is automatically committed if the response buffer is full.

example:

<?lsp
  response:write"hello world"

  -- create a convenience function for writing data
  local fmt = string.format
  local function prt(...) response:write(...) end
  local function prtf(...) prt(fmt(...)) end

  prt("as ","many ", "strings as you like<br />")
  prtf("You can format numbers %d<br />", 1234)

?>

response:writesize()

Returns the number of bytes that currently exist in the response write buffer. response:flush() should reset this number to zero.

Deferred Response Object

The deferred response object is a special response object created by some methods -- e.g. upload:response(). The deferred response is typically used by a response that is detached from the original client request. The deferred response object is a Lua wrapper for the "C" class HttpAsynchResp. A deferred response object has limited buffer management and the methods must be called in the following sequence:

defresp:setstatus()
defresp:setheader () or defresp:setcontentlength()
defresp:write() or defresp:send()
defresp:close()

defresp:setstatus(status): Sets the status code for this response. The status defaults to 200 OK.
defresp:setheader(name, value): Sets a HTTP response header with the given name and value.
defresp:write(string, ...): Send data to the client using chunk encoding.
defresp:setcontentlength(integer): Sets the "Content-Length" header value. This method is used in combination with method defresp:send().
defresp:send(string): Send data to the client. You must make sure you set the content length before sending data to the client. This function differs from defresp:write in that data is not sent using chunk transfer encoding and therefore requires a content-length.
defresp:close(): Flush and close the response.
defresp:valid(): Returns true if the response object is valid -- i.e. not closed.

cookie object

A cookie is used for exchanging a small amount of information between a page and a web browser.
A cookie's value can uniquely identify a client, so cookies are commonly used for session management.
A cookie has a name, a single value, and optional attributes such as a comment, path and domain qualifiers, a maximum age, and a version number.

Typical usage:

 cookie = request:cookie"myCookie"
 if not  cookie then  -- If no cookie set for this page
   -- Create a session cookie
   cookie = response:createcookie"myCookie"
   -- Active cookie i.e. send cookie to client
   cookie:activate()
 end
 -- This should never fail
 assert(cookie == request:cookie"myCookie")

cookie:activate(): Activates the cookie.
The cookie will not be sent to the client unless this function is called. You cannot active a cookie if the data is committed. See response:committed() for more information.
cookie:delete(): Deletes a cookie, previously made persistent with function setMaxAge.
cookie:comment([comment]): Gets or sets a comment that describes a cookie's purpose.
cookie:domain([domain]): Gets or sets the domain name set for this cookie.
cookie:maxage([time]): Gets or sets the maximum age of the cookie, specified in seconds. By default, 0 indicates the cookie will persist until browser shutdown.
cookie:name(): Returns the name of the cookie.
cookie:path([uri]): Gets or sets the path on the server to which the browser returns this cookie
cookie:secure([boolean]): Either returns true if the browser is sending cookies only over a secure protocol, or false if the browser can send cookies using any protocol.
If the boolean flag is specified, informs the browser whether the cookie should only be sent using a secure protocol, such as HTTPS or SSL.
cookie:value([value]): Gets or sets the value of the cookie

session object

The session object provides a way to identify a user across more than one page request or visit to a Web site and makes it possible to store information about that user.
The HttpSession container uses this class to create a session between an HTTP client and an HTTP server. The session persists for a specified time period, across more than one connection or page request from the user. A session usually corresponds to one user who may visit a site many times. The server can maintain a session in many ways such as using cookies or rewriting URLs.

This interface allows you to:

View and manipulate information about a session, such as the session identifier, creation time, and last accessed time.
Bind objects to sessions, allowing user information to persist across multiple user connections. These objects can be any Lua object, e.g. tables, strings, numbers.

Variables may be assigned and retrieved from the session object. This is done using normal Lua syntax.

Any attempt to create session variables with names the same as the session methods, will result in an error.
Session variables are destroyed when the session terminates or times out. LSP session variables are not accessable from CSP pages and vice versa.

A user can create a tool that could potentially overflow the session container. The Barracuda authentication system makes sure that a session object is not created before the user is authenticated. It is therefore recommended to create a session object by using the authentication system.

<html>
<!-- example session variable usage -->
<?lsp
  print("<h2>session variables</h2>");
  print("<pre>");
  session = request:session() -- returns nil/false if there is no session
  if session then
    print("we have a session ", session)
    session.counter = (session.counter or 0) + 1 -- count session usage of this page

    session:maxinactiveinterval(60);
    print ("id", session:id());
    print ("creationtime"        ,os.date("%c",session:creationtime()))
    print ("lastaccessedtime"    ,os.date("%c",session:lastaccessedtime()))
    print ("maxinactiveinterval" ,session:maxinactiveinterval())
    print ("usecounter"          ,session:usecounter())

    -- if we have any attributes print them all
    if session:attributes() then
      table.foreach(session:attributes(), print)
    end
  end
  print("</pre>")
?>
</html>

session:id([true]): Returns a unique number or string identifier assigned for this session. See ba.session for more information.
session:creationtime(): Returns the time when this session was created, measured in seconds since midnight January 1, 1970 GMT. This time can be formated with os.date()
session:lastaccessedtime(): Returns the last time the client sent a request associated with this session, as the number of seconds since midnight January 1, 1970 GMT, and marked by the time the container received the request.
This time can be formated with os.date()
session:maxinactiveinterval([interval]): Returns the maximum time interval, in seconds, that the session container will keep this session open between client accesses.
OR specifies the time, in seconds, between client requests before the session container will invalidate this session.
session:peername(): Returns a string of the client name/IP address associated with the session.
session:usecounter(): Gets the session usage counter.
session:terminate(): Unbinds any objects bound to this session object, destroys the session object, and frees the memory for this object. All session variables are destroyed.
session:user(): Returns authenticated user information.
If the session does not belong to an authenticated user, the function returns false. Otherwise, two strings are returned: the name of the user and the authentication type. The authentication type will be one of "basic", "digest", "form", or "default".

session.onterminate

The server calls onterminate when the server destroys the session object and if this attribute is set to a function.

Example:

local s=request:session(true)
function s.onterminate()
   ba.thread.run(function()
                 trace"Do the work here!"
              end)
end

json

A library that supports JSON encoding and decoding.
To enable this library a require "json" must be issued.

ba.json.encode(table[,table][,size]): The function encodes all provided tables to one JSON encoded string. The function is typically used for converting one Lua table. The function can optionally convert multiple tables in a format that is compatible with the stream based JSON parser. Converting large tables in memory constrained devices may fail. The function returns "nil,"mem" if sufficient memory cannot be allocated. The internal buffer grows as needed, when encoding the JSON data. The initial start size is 512 bytes. You can optionally set the start size to a larger value, which is suggested if you plan on converting large Lua tables. Userdata, functions, and threads are set to ba.json.null.
ba.json.decode(string): Takes a JSON encoded string and decodes it into a Lua table. JSON null is set to the ba.json.null value.
On error, nil and an error message is returned. The message is one of 'parse', 'data', 'interface', or 'memory'.
The input string is assumed to be UTF-8 encoded.
The string parameter can contain multiple JSON tables. In this case, multiple Lua tables (or [nil,message] pairs) are returned.
ba.json.encodestr(string): Encodes a string as JSON string.
ba.json.null: A userdata that represents the JSON null value.

ba.json.parser()

Create a stream based JSON parser object. The JSON parser object functions similar to ba.json.encode, but unlike function ba.json.encode which is limited to parsing complete JSON messages, the stream based parser parses data from a stream as the data trickles in.

The JSON parser is ideal for building advanced, asynchronous, message passing protocols on any type of communication channel. The communication can, for example, be between a standalone web server and other programs, or between embedded systems that are interconnected. The JSON parser can easily be used together with the socket library, but you can also use the JSON parser in combination with your own specialized communication channels such as message queues, USB connections, serial connections, etc.

parser:parse(data[,true])

Parse a chunk of data using the JSON parser object. The second argument, if true, instructs the parser to return all assembled JSON objects as one array of objects.

Return values:

true: The parser successfully parsed the data chunk, but the data chunk did not contain a complete JSON object.
true, object1, object2... : The parser successfully parsed the data chunk and assembled at least one object. The JSON parser can return multiple objects if the data chunk contained more than one JSON object. The parser returns multiple values if the second argument to parser:parse() is false or not present.
true, array : The parser successfully parsed the data chunk and assembled at least one object. All assembled objects are stored in the array table. The parser returns one array with the assembled objects if the second argument to parser:parse() is true.
false, errorcode: The parser failed parsing the data chunk. You cannot reuse the JSON parser if the parser aborts the stream parsing. You must start over by creating a new JSON parser object.

Example 1, JSON Server:

The following example shows a potential use case for the JSON parser. A specialized LSP page is designed to extract the active socket connection from the current request and morph the HTTP request into an asynchronous receive channel for JSON data. See the socket API for more information on how to use sockets.

<?lsp

-- Activated when s:event(asyncReceiveCoroutine) is called below
local function asyncReceiveCoroutine(s)
   local parser=ba.json.parser()
   -- variable x: multiple types, or nil on error
   local x,err=true,nil
   while x do -- While no error
      -- Block and wait for data
      x,err=s:read()
      if x then -- x is JSON socket data
         local array 
         x, array = parser:parse(x,true)
         if x then -- If ok
            if array then -- If at least one object
               for _,v in ipairs(array) do
                  -- Dispatch the parsed JSON object 'v'
               end
            end
         else
            -- Parse error
            err=array -- array is now error code
         end
      end
   end
   if err == "closed" then
      print"Socket closed"
   else
      print("Socket or JSON parser error:", err)
   end
   send=nil
   -- Return: exit and close connection
end


response:flush() -- Send HTTP response headers
-- Morph HTTP request into a socket connection
local s = ba.socket.req2sock(request)
-- Enable asynchronous socket receive
s:event(asyncReceiveCoroutine)

?>

The above code is designed to receive data. You can easily extend the code to also send asynchronous JSON data to the client side.

Example 2, JSON Client:

The following example shows a basic client designed using the Barracuda Embedded Web Server HTTP client library.

local c=http.create.basic()
c:request{method="GET",url="URL-TO-SERVER_RESOURCE"}
-- Morph HTTP request into a socket connection
local s=ba.socket.http2sock(c)
local data={txt="hello"} -- The data to send
s:write(ba.json.encode(data)) -- Encode and send

ba

A library that provides a number of Barracuda utility and IO functions.

ba.aesdecode(key, string)

Decodes and decrypts a string encrypted and encoded with function ba.aesencode. The key must be the same as the key you used when encoding the string.

ba.aesencode(key,string)

Encrypts a string using AES encryption and returns the encrypted string as a B64 encoded string.

key: The key can be any string, but is preferably created with function ba.aeskey()
string: The string to be encrypted and converted to B64 encoding.

This function is typically used as a substitute for creating a session object. The LSP page can instead store the session state as a hidden variable in the dynamically created page returned to the browser. The following example illustrates how to encode and decode state information in a hidden variable.

Encoding:

-- Data to be encoded and stored in hidden variable
local stateInfo={x=10,y="Top Secret"}
local data=ba.aesdecode(app.key, ba.json.encode(stateInfo))

Decoding:

-- Data received via hidden variable from client
local stateInfo = ba.json.decode(ba.aesdecode(app.key, request:data"MyHiddenVariable"))

ba.aeskey([len]])

Create a 16 or 32 byte long key that can be used by ba.aesencode() and ba.aesdecode(). The key is typically created at startup in the .preload script and stored in the app table.

len: The key length must be 16 (AES 128 bit) or 32 (AES 256 bit). The default length is set to 16.

ba.b64decode(string)

decodes a BASE64 string.

ba.b64encode(string)

encodes a string as BASE64.

ba.urldecode(string)

Decodes a URL encoded string.

ba.urlencode(string)

URL encodes a string.

ba.clock()

returns the number of milliseconds since system start.

ba.deflate(data [,rfc1950])

Deflates (compresses) a string or a table of strings and returns the compressed data.

data: The data to be compressed, which must be a string or a table of strings. The function works similarly to the Lua function table.concat when this argument is a table. The table is concatenated and compressed.

rfc1950: Optional Boolean argument, which defaults to false. The default action is to deflate data using RFC1951 -- i.e. compress without adding the ZLIB deflate header. The correct deflate method is to use RFC1950, but Internet Explorer does not seem to follow the RFC1950 specification, thus IE fails if a ZLIB header is added. All other browsers also accept RFC1951.

ba.create

A table of functions for creating Barracuda objects:

ba.create.authenticator(authuser[,options])

Creates an authenticator object for a directory. The returned object can be used as the target for dir:setauth()

authuser=object -- An object created with ba.create.authuser or ba.create.jsonuser.

options=table -- A table with the following optional fields:

realm=string -- The name of the authentication realm (used by basic and digest authenticators).

tracker=boolean -- If set to true, the client login tracker will be used if it is available. Defaults to false.

response = function(_ENV, authinfo) -- The optional Response Message Handler.

_ENV

The command environment.

authinfo=table

A table with the following fields:

type=string: type=form|basic|digest
username=string: Name of the user attempting to authenticate.
password=string: The password entered by the user.
maxusers=number: The maxusers variable returned by the authenticate callback function. This variable is negated when the maximum number of logins is reached.
recycle=boolean: true|false.
inactive=boolean: The maximum session inactivity time in seconds.
loginattempts=number: The number of login attempts.
denied=boolean: denied=true|false. Set if the user is denied access by the login tracker -- i.e. if the user is banned.
seed=string: Set if using the form based authenticator. The seed can be used for cryptographic hashing. See Using form based authentication safely without using SSL for more information.
seedkey=string: Set if using the form based authenticator. Field seedkey is an encrypted version of the seed.

Fields username,password,maxusers,recycle,and inactive are only set if the user failed to login or is denied access by the tracker. Fields loginattempts and denied are only set if a user tracker is active.

ba.create.authorizer(function)

Creates an authorize object for a directory. The returned object can be used as the target for dir:setauth(). The only parameter is a function that returns true if the user is authorized for the resource. The user is the users login name. Method is one of the same names as returns by request:method(). Path is the path name relative to the owning directory object.

function(username, method, relpath)

user: The username that is trying to authorize.
method: One of "GET", "POST" etc. See request:method()
relpath: The relative path that access is required.
returns: true|false

ba.create.authuser(function)

Creates an authenticator user database object. The returned object can be used as the target for ba.create.authenticator().

function(username [,_ENV])

username -- The username sent from the client.

_ENV -- The command environment is normally not needed, but can be used in special cases.

The function returns the following parameters in order: username [, maxusers [, recycle, inactive]].

username=string: Return the password if the user is found in the database [and if the user is accepted], otherwise return nil or nothing.
maxusers=number: The maximum number of concurrent login sessions the user is allowed to create. Setting maxusers to 0 will prevent the user from logging in. Note, the Response Message Handler must be designed to respond with a special message if maxusers is zero.
recycle=boolean: Enable recycling of older sessions if the maxusers ceiling is hit. Note, the Response Message Handler must be designed to respond with a special message if this variable (is not returned or is false) and maxusers is hit.
inactive=boolean: The maximum inactive time interval in seconds. If this time elapses without any user activity then the user will be logged out. The default session time is used if no value is returned.

ba.create.jsonuser()

Creates an authenticator user database object that is using a JSON as the user database format. The returned object can be used as the target for ba.create.authenticator().

The created object has the following additional authenticator methods:

jauthenticator:set(userdb)

userdb = table or string -- A Lua table or a JSON encoded string. The Lua table must have the following fields:

 {username1=user1, username2=user2} -- etc.

Where user1 and user2 are tables with the following fields:

{
 pwd='password',
 roles={'role1','rol2','etc'},
 maxUsers=number,
 recycle=boolean,
 inactive=number
}

The fields maxUsers, recycle, and inactive are optional.

jauthenticator:authorizer()

Creates and returns a jauthorizer (JSON authorizer) object. Each JSON user database can be associated with an unlimited number of JSON authorizers. You can, for example, use the same authenticator on multiple directories, but create a unique JSON authorizers for each directory.

The combined JSON authenticator user database and the JSON authorizer provides a ready to use user database and constraint management using JSON as the database format. The JSON user database and the JSON constraints can be saved to a file system. The BarracudaDrive web server is using the JSON authenticator user database and the JSON authorizer for authenticating and authorizing the users. An easy to use web application is designed as a front end to manage the JSON files. Download and install BarracudaDrive if you want more information on how the JSON authenticator user database and the JSON authorizer is used in BarracudaDrive. The help file includes additional information on how to setup users and constraints using the integrated web management application.

The following example sets up an authenticator and authorizer that simulates the same authentication and authorization logic as in the security C code example.

-- Setup the users, Defaults: maxusers=3,recycle=false,inactive=false
local userGuest={pwd='guest',roles={'guest'},maxusers=100}
local userKids={pwd='kids',roles={'guest','family'}}
local userDad={pwd='dad',roles={'guest','family','dad'},recycle=true,inactive=60*60}
local userMom={pwd='mom',roles={'guest','family','mom'},recycle=true,inactive=60*60}

-- Create a JSON user database object and install the user database
local authuser=ba.create.jsonuser()
authuser:set{guest=userGuest,kids=userKids,dad=userDad,mom=userMom}

-- Create a digest authenticator (using default values).
local authenticator=ba.create.authenticator(authuser)

-- Setup the constraints
local constr1={urls={'/*'},methods={'GET'},roles={'guest'}}
local constr2={urls={'/*','/family/*'},methods={'POST'},roles={'mom','dad'}}
local constr3={urls={'/family/*'},methods={'GET'},roles={'family'}}
local constr4={urls={'/family/mom/*','/family/dad/*'},methods={'GET'},roles={'mom','dad'}}
local constr5={urls={'/family/dad/*'},methods={'POST'},roles={'dad'}}
local constr6={urls={'/family/mom/*'},methods={'POST'},roles={'mom'}}
local constr7={urls={'/family/kids/*'},methods={'GET','POST'},roles={'family'}}
-- Note, the constraint names are not used by the authorizer.
local constraints={Guest=constr1,FamilyPost=constr2,FamilyGet=constr3,
   Parents=constr4,Dad=constr5,Mom=constr6,Kids=constr7}

-- Create the authorizer and install the constraints.
local authorizer=authuser:authorizer()
authorizer:set(constraints)

-- Create a directory and set the authenticator and authorizer
local dir=ba.create.dir()
dir:setauth(authenticator,authorizer)
-- Note: you must also reference (anchor) the dir so it is not garbage collected.

ba.create.dav([,name] [,priority], io [,lockdir] [,maxuploads, maxlocks])

I/O interface

The I/O interface provides a common set of functions for working with files stored in various media types such as data stored on a standard file system, ZIP files, and network files. The Lua I/O interface provides an interface to the C side implementation for the IoIntf. The C startup code can initialize and provide any number of I/O interfaces to the Lua code. The I/O interfaces provided by the C startup code is available to the Lua code via ba.openio(ioname). New I/O interfaces can be created by calling ba.mkio(baseio, path).

The DiskIo and the NetIo are delivered as C code and must be compiled, linked, and installed by the C startup code. Exceptions are the Windows and Linux release, which are delivered with the DiskIo precompiled. The wfs and the lspappmgr C source code examples show how to install the I/O interfaces and make the I/O interfaces available to Lua code. See the C side IoIntf introduction for detailed information.

ba.io()

Returns a table with all I/O resources created by the C/C++ startup code. The key is the I/O name and the value is the I/O resource.

for name,io in pairs(ba.io()) do
   print(name, " : ", io:resourcetype())
end

ba.openio(ioname)

Returns a Barracuda I/O object. The I/O object must have been installed by the C startup code.

C/C++ startup code example:

/* Register the DiskIo as "disk" */
balua_iointf(L, "disk",  (IoIntf*)&diskIo);

Lua code example:

--Open the "disk" I/O interface created by the C startup code:
local diskio = ba.openio("disk")

--Open the "net" I/O interface created by the C startup code:
local netio = ba.openio("net")

ba.mkio(baseio, path)

Dynamically create an IO interface object by opening a directory, a URL, or a ZIP file. The path must be relative to the base IO. The IO object returned from this function have the same methods as ba.openio().

-- Create a new DiskIo instance by using the sub directory "apps" as the base directory for the new I/O:
local appsio = ba.mkio(ba.openio("disk"), "apps/")

-- Create a ZipIo by opening a ZIP file in the "disk" (DiskIo) root directory:
local zio = ba.mkio(ba.openio("disk"), "myzip.zip")

-- Create a new NetIo by using the URL http://192.168.1.100/fs/c/apps/ as the base path.
-- Note: Requires that the wfs is running on 192.168.1.100.
local netio = ba.mkio(ba.openio("net"), "http://192.168.1.100/fs/c/apps/")

-- Open the ZIP file c:\myzip.zip on a computer, where the wfs is running, with IP address 192.168.1.100:
local netzipio = ba.mkio(ba.openio("net"), "http://192.168.1.100/fs/c/myzip.zip")

I/O object Methods:

Barracuda I/O objects have the following methods associated with them:

io:open(path[, mode)]

Opens a resource and returns an object that can be used for IO. The optional mode is the same as the file modes used in standard Lua.

The objects returned by open() have the following methods:
fh:close(object): Same as standard Lua.
fh:flush(): Same as standard Lua.
fh:read(option): Same as standard Lua, except that the only options supported are a number of bytes or the "*a" (all of the file). There is no default option.
fh:seek(offset): Same as standard Lua.
fh:write(string, ...): Same as standard Lua.

io:resourcetype()

Returns two strings indicating the type of resource where files exist (e.g. disk) and the type of operating system.

io:type(object)

Returns true if the object is a Barracuda file handle.

io:files(dirname [,true])

Returns an iterator that will iterate over all the files in the named directory. The iterator returns each file name in the directory. If the optional second argument is set to true, the iterator returns: name, isdir, mtime, size.

io:stat(path)

Returns a table of attributes for the named path (file or directory). If the path does not exist then 'nil' is returned. The fields of the table are named as follows:

name - the path name
mtime - last modified time
size - the size of the file (in bytes)
isdir - true if the path is a directory
type - either "directory" or "regular"

io:realpath(path)

Returns the real path (absolute) path name of the provided relative path.

io:mkdir(path)

Creates a new directory.

io:rmdir(path)

Removes a directory.

io:remove(path)

Removes (deletes) a file.

io:rename(oldpath, newpath)

Renames a file or directory.

io:loadfile(path [,_ENV])

Loads a Lua source file. Refer to the Lua base library loadfile() function. If env is provided, sets env as the value of the first upvalue of the created function. The first upvalue will be the _ENV variable. Example: io:dofile("myscript.lua",setmetatable({},{__index=_G})).

io:dofile(path [,env])

Loads and executes a Lua source file. Refer to the Lua base library dofile() function. If env is provided, sets env as the value of the first upvalue of the created function.

Extended methods:

The extended methods provide additional features for the I/O interfaces. Additional features are provided by the I/O interfaces by calling the C/C++ side I/O interface property function. The following Lua bindings are wrappers for calling the underlying C side property function. Calling one of the extended methods on an I/O interface of incorrect type has no effect.

DiskIo:

io:hide(true|false): Some files systems such as DOS based file systems support attributes for hiding files. The hide method sets the file attribute to hidden or clears the attribute. The hide method has no effect on file systems that do not support the "hidden" attribute. UNIX type file systems typically have hidden files starting with a dot. Examples: .config, .myfile.lsp.

ZipIo:

io:setpasswd(password): You can set the password if the ZIP file opened with ba.openio or ba.mkio is password protected. Barracuda only supports AES encrypted ZIP files.
io:reqpasswd(enable): Enable password protection. If enabled, the file being opened must match the password set with io:setpasswd. It is possible to replace an encrypted file inside a ZIP file with a non encrypted file. Enabling password protection makes sure your ZIP file is not compromised.
io:encrypted(path): Returns true if file is AES encrypted. Returns nil if not found.
io:close(): Close a dynamically created ZipIo, i.e. a ZipIo created with function ba.mkio().The ZipIo can no longer be used after you call io:close().

A dynamically created ZipIo keeps the ZIP file open until the garbage collector collects the IO or until you explicitly call method io:close(). This function is designed for operating systems such as Windows and CE that locks open files. The file cannot be deleted from the file system before the file is closed. Explicitly calling method io:close() makes it possible to delete the ZIP file from the file system without having to wait for the garbage collector to collect the dynamically created ZipIo.

NetIo:

The NetIo is similar to a network file system and makes it possible for the server to access resources on another Barracuda server.

io:netconf({options})

Configure a NetIo.

A NetIo is typically created and installed uninitialized by the C/C++ startup code. Method io:netconf() makes it possible to either configure the NetIo installed by the C/C++ startup code or to configure a NetIo clone created with with ba.mkio(). See the NetIo C documentation for more information.

{options}

user=string: Username sent to destination server.
pass=string: Password sent to destination server.
proxy=string: Use a HTTPS or SOCKS5 proxy.
proxyport=number: Proxy port number defaults to 8080 for HTTPS proxy and 1080 for SOCKS5 proxy.
socks=bool: Set to true if you are using a SOCKS5 proxy. The default is to use HTTPS proxy by using HTTP CONNECT.
proxyuser=string: Proxy username
proxypass=string: Proxy password
intf=string: Bind to interface-name/IP-address. The default is to bind to any interface.
ipv6=bool: Force use of IPv6 address translation. Note, the server must have been compiled with IPv6 support.

All attributes are optional and you can call the method multiple times to configure the NetIo. For example, setting user and password multiple times does not affect any of the other attributes set previously.

Note: "User, pass" and "proxyuser, proxypass" should be in pairs. The password is set to the empty string "" if missing.

The NetIo must be configured before calling ba.mkio(ba.openio("net"), URL) if a proxy and/or password are required, since ba.mkio verifies the URL before creating a new NetIo. You can either configure the NetIo installed by the C/C++ code or you can make a copy by calling ba.mkio(ba.openio("net")) -- i.e. without providing a URL. Calling ba.mkio() without providing a URL creates a copy of the original I/O.

Error codes:

The methods in the IO object returns nil and three error codes if calling the method(s) fail.

Error codes returned:

Error Type (short string).
Descriptive error message.
Optional error message that may be returned by the native file system.

The error type can be any of the following:

Error Type	Description
invalidname	Name not accepted by file system
notfound	Not found
exist	Resource exists
enoent	Directory not found
noaccess	Resource locked by file system
notempty	Directory not empty
ioerror	Some kind of I/O error
nospace	No space left on device
mem	No memory for operation
buftoosmall	Buf too small
noimplementation	Not implemented
noaeslib	AES not enabled
notcompressed	ZIP not compressed
ziperror	Unknown ZIP file format
noziplib	ZLIB not installed
aesnosupport	Unknown AES encryption
nopassword	Resource is encrypted, but no password provided
wrongpassword	Wrong password provided
aeswrongauth	Wrong password or file compromised
aescompromised	AES protected file compromised
invalidsocketcon	Invalid socket con
gethostbyname	Gethostbyname failed
bind	Bind failed
socketwritefailed	Socket write failed
socketreadfailed	Socket read failed
malloc	Malloc failed
alreadyinserted	Already inserted
toomuchdata	Too much data
pagenotfound	Page not found
iscommitted	Is committed
invalidparam	Invalid param
mixingwritesend	Mixing write send
toomanyincludes	Too many includes
toomanyforwards	Too many forwards
includeopnotvalid	Include op not valid
cannotresolve	Cannot resolve
cannotconnect	Cannot connect
invalidurl	Invalid URL
invalidresponse	Invalid response

ba.parsedate(string)

Parses the date string and returns the time with epoch of 1970-01-01 00:00:10 GMT.

ba.parselsp(string[,embed])

Parses and returns the Lua Server Page as a Lua chunk. The returned string can for example be loaded by function loadstring().

The default is to parse the LSP page as a standalone page, unless embed is set to true. The LSP page expects the following arguments when compiled as a standalone page: page(_ENV,pathname,io,page,app), where _ENV is the command environment, pathname is typically derived from a directory functions relative path. The arguments io,page, and app are the LSP page's IO object, page table, and application table.

Function parselsp can for example be used as an alternative to response:include(). The following example shows how to use parselsp in one LSP page to include another LSP page.

<?lsp
local fp,err=io:open"mypage.lsp"
if fp then
   local data
   data,err = fp:read"*a"
   fp:close()
   if data then
      -- Convert LSP to Lua
      data,err = ba.parselsp(data)
      if data then
         local func
         -- Compile Lua code
         func,err = loadstring(data)
         if func then
            local ok
            -- Let child use our: _ENV,io,page,app
            ok,err = pcall(func,_ENV,"mypage.lsp",io,page,app)
         end
      end
   end
end
?>

ba.rndseed(seed)

Seeds SharkSSL, ba.aeskey(), and ba.rnd(). Argument seed is a number between 0 and 0xFFFFFFFF. SharkSSL uses a circular buffer for seed values and you improve the randomness if you call this function several times.

-- Seed SharkSSL by connecting to remote seed generator
ba.thread.run(function() -- Run the blocking HTTP request in a separate thread
    -- Create a HTTP object using the low level HTTP library.
   local http=require"httpc".create()
   -- Send request and required parameters
   -- See http://www.random.org for more information
   http:request{
      method="GET",
      url="http://www.random.org/integers/",
      query={
         num=1,
         col=1,
         min=1,
         max=1000000000,
         base=10,
         format="plain",
         rnd="new"
      }
   }
   if http:status() == 200 then
      local rnd=http:read"*a"
      if rnd then
         rnd=tonumber(rnd)
         if rnd then
            -- We received a number
            -- Seed SharkSSL
            ba.rndseed(rnd)
         end
      end
   end
   -- Seed using millisec clock.
   -- The HTTP response time creates a random delay.
   ba.rndseed(ba.clock())
end)

ba.rnd([ [low ,] high])

Generates a random number. If no parameters are given a positive integer between 0 and 0x7fffffff is returned. If one parameter is provided then it represents the upper value of a random integer between 1 and the upper value and if two parameters are provided it represents the lower and upper limits of a random integer.

ba.session(args)

Function ba.session() is an alternative to method request:session(). Method request:session() can only be used within the command environment. Function ba.session() does not have this limitation and can therefore be used from any environment.

Function ba.session() can be used in three modes:

ba.session(session-number)

session-number - number created with method session:id() or from the ID's returned by ba.sessions().

Returns the session object if found.

local s = request:session(true)
local id = s:id() -- Returns a number suitable for local server use
assert(id == ba.session(id):id())

ba.session(session-ref, request [,create])

session-number - a number created with method session:id(true). Notice the difference between calling session:id() and session:id(true), the former returns a number suitable for local server use and the latter returns a string suitable for public use -- i.e. for use by a HTTP client such as a browser.

request - the request object.

create - a boolean value that defaults to false. Setting this variable to true also stores the session permanently in the server for the current requests thus making method request:session() return the same object, if called.

Returns the session object if found.

local s = request:session(true)
local id = s:id(true) -- Returns a string suitable for public use
assert(id == ba.session(id,request):id(true))

ba.session(request, relpath [,create])

Search for the session object by using a session URL. A session URL is a URL that includes the session-reference embedded as the first component in the relpath (relative path). As an example, the Web File Server is managing session URL's by using this function. Barracuda server sessions are normally automatically managed by using session cookies. Using a session URL is a convenient way to manage sessions if the client does not support cookies or does not support any standard authentication mechanism.

request - the request object.

relpath - the relative path is typically provided by a directory function.

Returns: session,relpath where session is the session object and relpath is the original relpath minus the session-reference that was embedded in the original relpath.

The following code fragment is from the Web File Server implementation. The Web File Server code can be found in the Barracuda SDK /WebResources/rtl/.lua/ directory. The code fragment shows the authService directory service function, which is installed if an authenticator is set on the Web File Server and if the session URL is enabled.

local function authService(_ENV,relpath)
   local s
   if not request:user() then
       -- User is not authenticated or no session cookie.
      local p
      -- Does the relative path include a session reference?
      s,p=ba.session(request,relpath,true)
      if s then
         -- Yes, relpath included the session
         s:maxinactiveinterval(sesTmo)
         -- Set the new relative path
         relpath=p
      end
   end
   -- Delegate the request to the standard directory service function
   service(_ENV,relpath,s)
end

ba.sessions()

Returns an array with the session id for all sessions active in the server.

ba.sessions(username)

Returns an array with the session id for all active sessions used by the authenticated user 'username'.

ba.sleep(milliseconds)

Pauses execution of this request or thread for the specified number of milliseconds. This function may yield to other Barracuda threads, consequently the function may pause for longer than the specified period. ba.sleep(0) would simply allow other pending Barracuda threads to execute (i.e. a yield).

ba.seterrh(function)

Install a Lua error handler. The error handler is called if a Lua script should cause an exception. The callback function gets one argument, the error message. Note: All errors are sent to the Barracuda HttpTrace library, thus a Lua error handler is typically not needed during debugging.

An error handler could for example be installed in a deployed system and send the error message by using the SMTP library. Another possibility is to upload the error message to an online database by using the HTTPS client library.

ba.timer()

The timer object makes it possible to create events that are activated at regular intervals. One can also create an event that is activated only one time. The Lua timer is internally using the C/C++ Barracuda timer class.

Creating a timer:

local timer = ba.timer(
  function()
    -- Do something
  end
)

ba.timer() returns an inactive timer object -- that is, the timer is created, but not started. The returned object must be referenced. The Lua garbage collector collects all objects not being referenced. A collected timer object is automatically cancelled.

The timer object returned by ba.timer() has the following methods:

timer:set(millisecs [,bool [,bool]])
Activates an inactive timer object. If the timer is active, the timer is cancelled and then activated. The timer callback function is activated in "millisecs" time unless method "reset" or "cancel" is called before the timer triggers.

The timer will be automatically referenced if the second argument is set to true. The reference will be maintained until the timer is cancelled by calling function set or cancel, or when the timer function stops the timer. The purpose with the reference is to prevent the garbage collector from collecting the timer object when the timer is run as an interval timer. Without the auto reference, a global reference maintained by the Lua code creating the timer would have been required.

The timer function is run immediately if the third argument is set to true. Running the timer function immediately is sometimes useful when running the timer function in interval mode and as a coroutine. The timer function can be used in a similar manner to how one creates a thread -- i.e. the thread function is called which then enters a forever loop.

timer:reset(millisecs)
Resets the timer if the timer is active. Returns true if the timer was active and the timer was successfully reset. Returns nil if the timer was inactive.

timer:cancel()
Cancels the timer if the timer is active. Returns true if the timer was active or nil if the timer was inactive.

The timer callback function:

The timer callback function is run as a "one-shot timer" if the timer callback function does not return a value or if the function returns false. The timer is automatically re-activated with the previous timeout value if the function returns true.

-- One-shot timer example:
function timeout()
  -- do something
end
-- Create a timer. The timer object must be global.
t = ba.timer(timeout)
-- Set the timeout to one second.
t:set(1000)

-- Interval timer that never stops.
function timeout()
  -- do something
  return true
end

-- Create a self referencing interval timer
ba.timer(timeout):set(1000,true)

As an optional feature, the timer callback function can be run as a Lua coroutine. In coroutine mode, the timer callback is run as an interval timer.

The following example illustrates how the timer callback function can be run in coroutine mode. The timer saves the counter variable "i" on the stack. The variable is re-used when the timer function is reactivated. The timer is activated a total of five times before the timer exits.

local function timeout()
   for i=1,5 do
      trace("Interval", i)
      coroutine.yield(true)
   end
   trace("Stop interval")
   coroutine.yield(false)
end

-- Create a self referencing interval timer and start the coroutine immediately.
ba.timer(timeout):set(1000,true,true)

A timer callback function in coroutine mode cannot be re-used when the function calls coroutine.yield(false). However, the function can call timer:cancel(), or timer:reset() to either temporarily cancel an active timer or to change the interval time.

ba.tracker

Authenticator User Database Object

The objects created by ba.create.authuser() and by ba.create.jsonuser() are typically used by the underlying C authenticator code for granting or denying access.

The authenticator user database object has the following method that can be used by Lua:

authuser:getpwd(username): Returns nil if username is not found in the database.; Returns the following if username is found: username [, maxusers [, recycle, inactive]]

Authenticator Object

The authenticator object created by ba.create.authenticator() is typically used by the underlying C code for a directory type when authenticating the user. The authenticator can also be used by Lua directory functions.

All authenticator object types have the following method that can be used by Lua:

authenticator:authenticate(request, path)

Authenticate the client

request=object: The request object from the command environment.
path=string: The path is typically from the directory function's relative path argument.

Example:

local function myDirectoryService(_ENV,relpath)
   if authenticator:authenticate(request, pathpath) then
      response:write"You are authenticated"
   else
      -- The response was sent by the
      -- authenticator's Response Message Handler
   end
   return true -- True means resource found and response is committed
end

Authorizer Object

The authorizer object created by a number of functions such as ba.create.authorizer() is typically used by the underlying C code for a directory type when authorizing the user. The authorizer can also be used by Lua directory functions.

All authorizer object types have the following method that can be used by Lua:

authorizer:authorize(request,method,path)

JSON Authorizer (jauthorizer) Object

The JSON authorizer object, which inherits from the authorizer object, created by method jauthenticator:authorizer() is an optional authorizer that can be used as the target for ba.create.authenticator(), when used together with the jauthenticator that created the jauthorizer.

The jauthorizer object has the following additional authorizer methods:

jauthorizer:set(constraintdb)

jauthorizer:casesensitive([boolean])

The JSON Authorizer is by default case sensitive. Turn off the case sensitive authorizer for case insensitive file systems such as FAT based file systems.

constraintdb = table or string -- A Lua table or a JSON encoded string. The Lua table must have the following fields:

 {constraintname1=constraint1, constraintname2=constraint2} -- etc.

where constraint1 and constraint2 are tables with the following fields:

 {urls={'url1','url2','etc'},methods={'GET','etc'},roles={'role1','etc'}}

The constraint name is not used by the authorizer, but the authorizer requires a table and not an array; thus dummy names must be created for the constraints -- e.g. constraintname1

directory object

Objects implementing directory functionality:

ba.create.dir
ba.create.resrdr
ba.create.dav
ba.create.wfs
ba.create.eh

The HTTP directory object is returned by a number of functions such as the ba.create.xxx functions.

The Lua directory object is a wrapper for the HttpDir "C" class or any class that inherits from HttpDir such as HttpResRdr.

dir:baseuri()

Returns the URI to the location where the directory is installed in the virtual file system. Returns dir:name()+"/" if the directory is not installed in the virtual file system.

dir:insert() -- Insert as root directory

dir:insert(dir [,reference]) -- Insert a child directory

Inserts a directory into the server's virtual file system. See the Virtual File System Introduction and Constructing a Virtual File System Tree for more information. See also dir:insertprolog().

reference -- Reference the child directory in the parent directory. Referencing the child prevents the child from garbage collecting as long as the parent exists.

dir:name()

Returns the name of the directory

dir:p403(path)

Set a 403 denied request handler. The directory forwards the request to the page if an authorizer is installed and the user is denied access by the authorizer. The default for a directory is to send a basic 403 message if a 403 denied request handler is not installed. Parameter 'path' is the path to a page that can be accessed by response:forward.

dir:setauth(authenticator, [authorizer])

Enables authentication and optionally authorization for this directory. The authenticator is created by ba.create.authenticate() and the authorizer is created by ba.create.authorize() or jauthenticator:authorizer(). Returns true on success.

dir:service(request, relpath [,sim-forward])

Calls the service function of this directory. This function delegates the response to the active service function if you call another directory than "self" and the original service function if called from "self".
The request object is required.
The relative path (relpath) parameter is required.
Setting the optional parameter sim-forward, a boolean value, to true, makes the service function simulate a response:forward call without resetting the response buffers. Simulating a response:forward is useful if you need to bypass authentication and/or authorization in. It is also possible to access hidden files when delegating to a resource reader. A hidden file is a file that starts with a dot -- e.g. ".preload".

dir:setfunc(function)

Sets the directory service function.

Apply dir:setfunc() to objects created with:

ba.create.dir
ba.create.resrdr
ba.create.dav
ba.create.eh

A directory function is the directory's service callback function which is activated by the server's virtual file system when searching for resources. All directory types have a default service function implemented in C code. The Lua code can install a new directory function that either replaces the original service function or extends the functionality of the original service function. The original "C" service function can be called from within the Lua service function by calling dir:service().

The directory function must be declared as follows:

  local function myservice(_ENV,relpath)

The _ENV variable is the command environment. The relpath variable is constructed from the URL and is the relative URL path component for the directory branch.

dir:unlink()

Removes the directory from its parent (or the server).

Standard Lua Libraries

All of the standard Lua libraries are implemented with the two exceptions that the io library is only supported when the target platform supports ANSI IO (MAC, Windows, POSIX) and the os library functions are implemented when it is appropriate on the target platform. os.exit() is not implemented on any Barracuda platform.
Platform independence is achieved by using the ba library.

Barracuda global functions

print(string, ...)

When calling function print() from the command environment, print() is a function that sends response data to the client. Function print() is otherwise the standard Lua print() function. To call the standard print() from a command environment, call print() using the global scope variable -- e.g. _G.print().

Function print() differs from response:write() in that print() calls the Lua tostring() function on each parameter that is passed to print(). Function print() is useful for generating diagnostics and small amounts of text on a web page, use response:write() in preference to print().

Note: the global _G.print(), that prints to the console, may not be available in embedded systems. Use trace() as a replacement.

Example:

<?lsp
  print("hello", "world")
?>

The above example would emit "hello\tworld\n".

trace(string, ...)

tracep(priority,string, ...)

Writes the string to the web server trace log. Function trace() is useful for generating diagnostics and print debug information.

Function trace is hard coded to use priority 0, the highest priority level. Function tracep lets you set the priority.

The trace library must be initialized at system start by the C startup code. We suggest incorporating the SimpleDebugger example in your code since the SimpleDebugger makes it possible to view the trace in real time using a browser.

_emit(string)

Function _emit() is available in the command environment and is used by the LSP pages when sending parsed HTML chunks to the client. The LSP parser converts an LSP page and instruments the parsed code with _emit[[data-chunk]] around each parsed chunk.

Standalone Executable Lua Interpreter

A standalone executable Lua interpreter is delivered with the Barracuda Server's SDK. The executable, called blua, is found in the SDK's bin directory.

The executable blua is an enhanced version of the standard standalone executable Lua interpreter and includes many API's from the Barracuda server in addition to the original API's.

The standalone interpreter makes it easy to create standalone applications for sending (secure) E-mail, using the HTTP(S) client libraries, and creating (secure) client and server socket applications in Lua.

The extended executable includes:

All functions in ba.xxx except for functions related to creating and working with server objects such a HTTP directories.
A DiskIo and NetIo I/O Interface objects. The DiskIo is initialized to root i.e. to "/" and the NetIo is uninitialized. The DiskIo is returned when calling ba.openio"disk" and the NetIo is returned when calling ba.openio"net". A new NetIo instance is typically created (cloned) and initialized by calling ba.mkio(). Note: the NetIo client is compatible with the secure file server in the BarracudaDrive application server.
An embedded ZIP file, which includes the Lua resources for SMTP, HTTP, and sockets. For example calling require"socket/mail" loads the SMTP libraries from the embedded ZIP file. You can also open the ZIP IO directly by calling ba.openio"vm".
The Lua SSL/TLS API for our SharkSSL stack, including the certificate management functions.
The SQLite database engine and the Lua SQLite API.
The thread library.
The Linux version of blua includes the forkpty API.

successful -	Boolean set to true if successful login or false on failed login.
name -	The (attempted) login name.
addr -	The user's IP address.
_ENV -	The command environment is normally not needed, but can be useful in special cases.