BAS LuaSocket Compatibility Library

The BAS LuaSocket Compatibility Library provides a LuaSocket-style API on top of the Barracuda App Server (BAS) socket layer. It was primarily created so the LuaSocket SMTP module can run on BAS, including secure SMTP via TLS/STARTTLS, but it is also useful for porting other Lua code written for the standard LuaSocket API.

This compatibility layer is not a byte-for-byte reimplementation of all LuaSocket behavior. It maps LuaSocket-style calls to BAS sockets (ba.socket) and adds BAS-specific TLS hooks (SharkSSL integration). The sections below document only APIs that are new or behave differently than standard LuaSocket.

Scope and Design Notes

• Built on BAS native sockets (ba.socket), not OS sockets directly.
• Adds TLS support via SharkSSL for implicit TLS and STARTTLS.
• Enables many LuaSocket-based client libraries to run on BAS, but compatibility is practical (not identical).

Modules in /socket/

The compatibility library in /socket/ is split into a small set of modules with different roles. They do not all follow the same module-return pattern.

• socket/core.lua: BAS-to-LuaSocket compatibility layer. This module initializes the global compatible table socket (via BAS compatibility support) and adds/overrides methods on that table.
• socket/tp.lua: Shared text protocol transport helpers used by SMTP (command/reply handling, source pumping, TLS transport upgrade hook).
• socket/smtp.lua: SMTP client implementation based on LuaSocket SMTP, with BAS TLS/STARTTLS integration.
• socket/mail.lua: Convenience wrapper for composing/sending text, HTML, and attachment emails via socket.mail.

Module loading note: not all files in /socket/ return a module table. For example, socket/mail.lua defines socket.mail on the global compatible socket table and does not return a table value.

BAS-Specific Additions and Differences (socket/core.lua)

socket.tcp()

Creates an unconnected compatibility wrapper. Call connect to attach a connection, or bind followed by listen to create a native listener.

Parameters

None.

Return values

• table tcp - New wrapper. No native socket is opened by this call.

Throws

Lua allocation errors can propagate.

socket.secure([shark]) (BAS extension)

Sets the SharkSSL configuration used by subsequent connect calls that have no stored options. bind captures this value in its stored options when called. Direct upgrade calls use their explicit configuration or ba.sharkclient().

local socket = require("socket")
-- Default configuration for subsequent connections
socket.secure(ba.sharkclient())

Parameters

• SharkSSL object (optional) shark - Configuration to store. Omitted or nil calls ba.sharkclient(). Existing sockets are not changed.

Return values

None.

Throws

Errors from ba.sharkclient() propagate when creating a default configuration. A supplied value is stored without validation; native operations validate it when used.

socket.gettime()

Returns os.time(), with whole-second resolution.

Parameters

None.

Return values

• integer time - Current Unix time in seconds, without a fractional part.

Throws

Errors from the underlying os.time() call propagate.

socket.sleep(seconds) (behavior difference)

Uses BAS scheduling primitives. When running in a BAS socket context (cosocket), it temporarily disables the current cosocket and re-enables it via a timer; otherwise it falls back to ba.sleep(). This makes sleep behavior BAS event-loop aware.

Parameters

• number seconds - Requested sleep duration in seconds; multiplied by 1000 for the BAS millisecond API. In a cosocket, seconds * 1000 must be an integer from 0 through 4294967295. The caller is responsible for supplying a value that meets this requirement; the wrapper does not round it, and an invalid timer interval throws. Outside a cosocket, the duration must meet the ba.sleep requirements.

Return values

None. Results from the underlying scheduling calls are not returned.

Throws

Invalid duration types and errors from native timer, socket or sleep calls can throw. Calling from an unsupported execution context can throw.

tcp:bind(address, port) + tcp:listen([backlog]) (behavior difference)

bind() stores bind/connect options (including TLS state) and does not immediately create/bind the underlying BAS socket. The actual server bind occurs in listen(). The backlog argument is accepted for compatibility but is not used. The wrapper has no LuaSocket-style accept() method. For server applications, use ba.socket.bind() and its native accept() method. If you already have a listening wrapper, sock() returns its native listener; native accept returns a BAS socket, not a LuaSocket wrapper.

Parameters

• string address - Local interface address, stored as the BAS intf option. See ba.socket.bind for supported values.
• integer port - Local port passed to ba.socket.bind when listen is called.
• number (optional) backlog - Accepted by listen for compatibility; ignored.

Return values

• boolean or nil success - bind returns true after storing options. listen returns true after creating the native socket, or nil if the native bind reports failure.
• string (on listen failure) error - Error returned by ba.socket.bind.

Throws

Invalid objects can throw. bind stores its arguments without validating them; listen requires options set by bind or sock and propagates native argument-validation errors. Native bind failures reported as return values are returned as nil, error.

tcp:connect(address, port) (behavior difference)

In addition to normal host/port usage, address may be an existing BAS socket userdata (detected by an upgrade method). In that case, the compatibility object wraps the existing socket instead of creating a new connection. Starting connect closes any previously wrapped socket and discards unread buffered data, including if the new connection attempt fails.

Parameters

• string or BAS socket userdata address - Remote host name or IP address passed to ba.socket.connect, or an existing BAS socket to wrap.
• integer port - Remote port for a new connection. Ignored when address is an existing socket.

Return values

• boolean or nil success - True after creating or attaching the native socket; nil on a reported native connection failure.
• string (on failure) error - Native connection error.

Throws

Invalid objects, addresses, ports or stored options can throw. Native connection argument and Lua allocation errors propagate. Reported connection failures return nil, error. Argument validation occurs after the previous socket has been closed.

tcp:certificate()

Returns the certificate information retained by the native TLS socket. See socket:certificate() for the named certificate fields and linked parent tables.

Parameters

None.

Return values

• table or nil certificate - Peer certificate information, or nil if unavailable, TLS is absent or no native socket is attached.
• boolean (TLS socket) trustedCA - Whether the retained chain is validated by the configured certificate store. False when no certificate information is available. Does not check host name or certificate dates.
• string (second value instead of trustedCA) error - "sslnotenabled" for a plain socket, or "closed" when no native socket is attached.

Throws

Invalid objects can throw. Lua allocation errors from the native certificate query can propagate. Missing TLS or an unattached socket is reported through return values.

tcp:upgrade([shark])

Upgrades an attached plain socket to TLS. For protocols such as SMTP, complete the protocol's STARTTLS exchange before calling this method.

Parameters

• SharkSSL object (optional) shark - Configuration passed to native upgrade. Omitted or nil uses ba.sharkclient().

Return values

• boolean or nil upgraded - True after a successful upgrade; false when the native socket is already marked closed or already has a TLS context. Nil for a reported upgrade failure or when no socket is attached.
• string or nil (on failure) error - Native upgrade error when upgraded is nil. "closed" when no socket is attached.

Throws

Invalid objects or native upgrade arguments can throw. Errors from default configuration creation and native calls propagate. Reported upgrade failures return nil, error.

tcp:dohandshake([op]) and tcp:sslhandshake()

Returns success for a valid socket that already uses TLS, whether its session was resumed or established with a full handshake. Otherwise, upgrades the plain socket. sslhandshake() calls dohandshake() without options.

Parameters

• table (optional) op - Options for dohandshake. Omitted or nil uses the options stored on the wrapper. Options are used only when upgrading a plain socket.
• SharkSSL object (optional) op.shark - Configuration passed to the native upgrade. If absent from the selected options, uses ba.sharkclient().

Return values

• boolean or nil success - True for an existing TLS connection or successful upgrade. Otherwise returns the native upgrade result. Nil for an unattached or invalid native socket.
• string (on failure) error - "closed" for an unattached or invalid socket; otherwise forwards the native upgrade error.

Throws

Invalid objects or upgrade arguments can throw. Errors from option access, default configuration creation and native socket calls propagate. Reported upgrade failures use return values.

Recognizing an existing TLS connection does not repeat its handshake or certificate checks. Use the native socket's trust-checking API when required by the application.

tcp:sockname() / tcp:getsockname()

Queries the local endpoint through the native BAS socket.

Parameters

None.

Return values

• string or nil address - Numeric local IP address on success; nil on failure.
• integer (on success) port - Local port number.
• boolean (on success) ipv6 - True for IPv6, false for IPv4. BAS returns this flag rather than LuaSocket's address-family string.
• string (second value on failure) error - Native query error, or "closed" if no socket is attached. No third value on failure.

Throws

Invalid objects and native argument errors can throw. Lua allocation errors can propagate. Reported native failures return nil, error.

tcp:peername() / tcp:getpeername()

Queries the remote endpoint through the native BAS socket.

Parameters

None.

Return values

• string or nil address - Numeric remote IP address on success; nil on failure.
• integer (on success) port - Remote port number.
• boolean (on success) ipv6 - True for IPv6, false for IPv4. BAS returns this flag rather than LuaSocket's address-family string.
• string (second value on failure) error - Native query error, or "closed" if no socket is attached. No third value on failure.

Throws

Invalid objects and native argument errors can throw. Lua allocation errors can propagate. Reported native failures return nil, error.

tcp:sock([op])

Returns the native socket and optionally replaces options used by later operations.

Parameters

• table (optional) op - Stored by reference, replacing the previous options. Non-table values are ignored. Does not reconfigure the current native socket.

Return values

• BAS socket userdata or nil socket - Attached native socket, including if closed; nil when none is attached.

Throws

Invalid objects can throw. Options are stored without validation; native operations validate them when used.

tcp:connected()

Checks the native socket validity flag. This is a local state check, not a test of peer reachability. A listening socket can also be valid.

Parameters

None.

Return values

• boolean or nil connected - True when an attached native socket is valid; nil when it is invalid or no socket is attached.
• string (on failure) error - "closed" when connected is nil.

Throws

Invalid objects can throw. Errors from the underlying socket:state() call propagate. A closed or unattached socket returns nil, "closed".

tcp:close()

Closes the underlying BAS socket. The wrapper retains the native socket object; connected() checks its current validity.

Parameters

None.

Return values

• boolean closed - True when the native close runs for the first time; false if already closed or no socket is attached.

Throws

Invalid objects can throw. Errors from the native close call propagate.

tcp:getstats() (stored values only)

Automatic traffic statistics are not supported. Sending and receiving data do not update the stored values, and age is not an elapsed duration.

Parameters

None.

Return values

• number or nil received - Stored receive value. Initialized to zero when connect or listen starts; not updated by reads.
• number or nil sent - Stored send value. Initialized to zero when connect or listen starts; not updated by writes.
• number or nil age - Time returned by os.time() when connect or listen starts, or the value supplied to setstats. Does not increase with elapsed time.

A newly created wrapper returns nil for all three values until connect, listen or setstats initializes them. Values supplied to setstats are returned unchanged.

Throws

No errors are raised for a valid wrapper. Calling the method with an invalid object can throw.

tcp:setstats([received[,sent[,age]]]) (stored values only)

Replaces the three values returned by getstats. This does not enable automatic accounting.

Parameters

• number or nil (optional) received - Replacement receive value. Omitted or nil clears the stored value.
• number or nil (optional) sent - Replacement send value. Omitted or nil clears the stored value.
• number or nil (optional) age - Replacement age value. Omitted or nil clears the stored value.

Return values

• integer success - Always 1 for a valid wrapper.

Throws

Calling the method with an invalid object can throw. The implementation stores values without validating their types or ranges.

tcp:settimeout(value[,mode]) and tcp:gettimeout()

Stores a timeout for subsequent receive calls. This value does not configure connect or send. mode is accepted but ignored; there is no separate total-operation timeout.

Parameters

• number or nil (optional) value - Receive timeout in seconds. Positive values are multiplied by 1000 and passed to native reads. Omitted, nil, false, zero or negative values clear the stored timeout; zero does not request polling. Native read timeout limits apply when receive calls read.
• string (optional) mode - Compatibility argument to settimeout; ignored.

gettimeout takes no arguments.

Return values

• boolean success - settimeout returns true after storing or clearing the timeout, including before connect and after close.
• number milliseconds - gettimeout returns the stored value in milliseconds, or math.maxinteger when no timeout is stored. This return value is not in seconds.

Throws

Invalid objects and values that cannot be compared or multiplied can throw. settimeout does not validate the native timeout range; errors from unsupported timeout values can occur on receive. gettimeout does not raise errors for a valid wrapper.

tcp:receive([pattern[,prefix]]): line reads

Reads a line when pattern is omitted, "l" or "*l". Removes the final newline and an immediately preceding carriage return. This section describes line reads; numeric and all-data patterns are separate forms.

Parameters

• string (optional) pattern - "l" or "*l" for a line; omitted or nil defaults to "l".
• string (optional) prefix - Text prepended to the returned line or partial data.

Return values

• string or nil line - Complete line, including prefix if supplied; nil if reading stops before a newline.
• string (on failure) error - "timeout" for a read timeout; other reported native read failures map to "closed". An unconnected wrapper also returns "closed".
• string (on failure) partial - Prefix followed by bytes received before the failure. May be empty. These bytes are consumed; they are not retained for the next receive call.

Throws

Invalid objects or argument types can throw. Native socket API-usage errors and Lua allocation errors can propagate. Reported read failures return nil, error, partial.

tcp:receive(pattern[,prefix]): all-data reads

Reads until the connection closes. A timeout returns an error and the data collected so far; it does not indicate a complete read.

Parameters

• string pattern - "a" or "*a" to read all data.
• string (optional) prefix - Text prepended to the returned data or partial data.

Return values

• string or nil data - Collected data, including prefix if supplied, when a non-timeout read failure ends the read, normally because the peer closed the connection. Returns nil on timeout, or if no data or prefix was collected.
• string (on failure) error - "timeout" on timeout; "closed" when no data was collected and another native read failure was reported, or the wrapper is unconnected.
• string (on timeout or unconnected wrapper) partial - Prefix followed by collected bytes, including unread buffered data. May be empty. These bytes are consumed and are not retained for the next call. Pass partial as the next call's prefix to continue collecting data.

Throws

Invalid objects or argument types can throw. Native socket API-usage errors and Lua allocation errors can propagate. A reported timeout returns nil, "timeout", partial.

tcp:receive(count[,prefix]): fixed-length reads

Reads enough bytes to reach count, including the supplied prefix. For example, receive(5, "ab") reads three more bytes. Bytes received beyond the requested count remain buffered for the next call.

Parameters

• number count - Requested total byte count. Must be finite, nonnegative and whole. Numeric strings representing such counts are also accepted. Zero is valid.
• string (optional) prefix - Previously collected bytes; defaults to an empty string. Counts toward count. If its length already reaches or exceeds count, returns the entire prefix without reading more bytes from a connected socket.

Return values

• string or nil data - Prefix followed by enough new bytes to reach count, or the entire prefix if it already satisfies count. Returns nil if reading fails before completion.
• string (on failure) error - "timeout" for a read timeout; other reported native read failures map to "closed". An unconnected wrapper returns "closed".
• string (on failure) partial - Prefix followed by bytes collected before failure. May be empty. These bytes are consumed. To retry, pass partial as prefix with the original count.

Throws

For an attached socket, a negative, fractional or non-finite count throws before reading or changing buffered data. Invalid objects, unsupported patterns or invalid prefix types can also throw. An unattached wrapper returns nil, "closed", prefix before inspecting the pattern. Native socket API-usage errors and Lua allocation errors can propagate. Reported read failures return nil, error, partial.

tcp:send(data[,i[,j]]) (behavior differences)

Sends the selected data through the underlying BAS socket. Returns a boolean success value, not LuaSocket's last-byte index. An empty selection succeeds without sending bytes.

Parameters

• string or table data - Data to send. A table is concatenated into a string; nested tables one level deep are concatenated and replaced by strings in the supplied table. Other values use the native write conversion rules.
• integer (optional) i - First byte index; defaults to 1. Negative indices count from the end, as in string.sub.
• integer (optional) j - Last byte index; defaults to -1, the final byte. Applies to the concatenated string when data is a table.

Return values

• boolean or nil success - True if the native write succeeds or accepts the data for asynchronous sending, including an empty selection. Nil if the write fails or no native socket is attached.
• string, integer or nil (on failure) error - Native write error string, or queued-byte count when the asynchronous queue is full. "closed" when no native socket is attached. No partial byte index is returned.

Throws

Invalid objects, invalid table contents and native write argument errors can throw. Data conversion errors and Lua allocation errors can propagate. Reported native write failures use return values. See ba.socket for native send and queue behavior.

tcp:shutdown() (behavior difference)

BAS compatibility maps shutdown() to close(). Half-close semantics are not provided by this layer. An unattached wrapper returns nil, "closed".

Parameters

None. Additional arguments are ignored.

Return values

• boolean or nil closed - Native close result: true on first close, false if already closed. Nil when no socket is attached.
• string (when closed is nil) error - "closed" when no socket is attached.

Throws

Invalid objects can throw. Errors from native close propagate.

SMTP/TLS Extensions (socket/smtp.lua and socket/tp.lua)

The SMTP code is based on LuaSocket SMTP, but BAS adds TLS integration so it can operate with modern SMTP servers that require encryption.

smtp:upgrade([shark])

Upgrades the SMTP transport to TLS before reading the server greeting, for implicit TLS.

Parameters

• SharkSSL object (optional) shark - Client configuration; omitted or nil uses ba.sharkclient().

Return values

None on success.

Throws

This low-level method closes the transport and raises a reported upgrade failure through its cleanup handler. Other native or argument errors can propagate. The high-level socket.smtp.send catches errors inside its protected sending operation and returns nil, error.

smtp:starttls([domain[,shark]])

Sends STARTTLS, checks the reply, upgrades the transport and sends EHLO again.

Parameters

• string (optional) domain - EHLO domain; omitted or nil uses the module's DOMAIN value.
• SharkSSL object (optional) shark - Client configuration; omitted or nil uses ba.sharkclient().

Return values

• string reply - Server reply to EHLO after the upgrade, including advertised extensions.

Throws

This low-level method closes the transport and raises reported command, reply or upgrade failures through its cleanup handler. Other native or argument errors can propagate. The high-level socket.smtp.send returns protected failures as nil, error.

tp:upgrade([shark])

Forwards a TLS upgrade to the protocol transport's socket.

Parameters

• SharkSSL object (optional) shark - Client configuration; omitted or nil uses ba.sharkclient().

Return values

• boolean or nil upgraded - Underlying upgrade result; false can indicate an already closed socket or existing TLS context.
• string (on failure) error - Error forwarded by the underlying upgrade.

Throws

Invalid objects, configuration errors and exceptions from the socket upgrade can propagate. Reported upgrade failures use return values; this forwarding method does not itself close the transport.

socket.smtp.send(mailt) extra fields (BAS extensions)

• mailt.shark: SharkSSL client configuration to use for TLS.
• mailt.starttls (true/false): If true, require STARTTLS during the SMTP handshake.

Behavior:

• If mailt.shark is set and mailt.starttls is not set, SMTP uses implicit TLS (typically SMTPS/465) before EHLO.
• If mailt.starttls = true, SMTP upgrades after the initial EHLO when the server supports STARTTLS.
• If mailt.starttls = true but the server does not advertise STARTTLS, send closes the connection and returns nil, "STARTTLS not supported". A rejected STARTTLS command or failed TLS upgrade also closes the connection and returns nil, error before authentication or message submission. Implicit TLS upgrade failures use the same cleanup and error handling.
• If no SharkSSL object is explicitly provided, BAS defaults are used (ba.sharkclient()) during TLS upgrade.

Parameters

• table mailt - Required LuaSocket SMTP message and connection settings.
• string mailt.from - Required SMTP envelope sender, normally enclosed in angle brackets. The null reverse path "<>" is allowed. This check verifies presence, not address syntax.
• string or table mailt.rcpt - Required SMTP envelope recipient, or a sequence of recipient strings. This check verifies presence, not address syntax or table contents.
• SharkSSL object (optional) mailt.shark - TLS configuration. Enables implicit TLS when starttls is not set; otherwise used for the requested upgrade.
• boolean (optional) mailt.starttls - True requires STARTTLS before authentication or message submission. Omitted or false does not request STARTTLS.

Return values

• integer or nil success - 1 after message submission, QUIT and transport close; nil if sending fails. Submission does not confirm delivery to the recipient.
• string (on reported transport/protocol failure) error - Failure detail, including "STARTTLS not supported" or the error from the command or upgrade.

Throws

Throws before opening a connection if mailt.from or mailt.rcpt is missing, nil or false. Invalid access to mailt can also throw before connecting. After these checks, the high-level send function uses socket.protect: errors raised inside its protected body are returned as nil, error. Other argument and callback errors inside that body can therefore be returned, and their error value need not be a string. The low-level SMTP methods use socket.newtry and can raise errors; call them inside socket.protect when using them directly.

socket.smtp.message(mesgt) (behavior difference in this BAS copy)

This BAS-modified version normalizes user-supplied header keys to lowercase when building the message source. Code that depends on LuaSocket's original header key casing behavior should be verified on BAS. The generated MIME-Version header is always 1.0, as specified by RFC 2045.

Parameters

• table mesgt - Message description. Its headers field is replaced by a table with lowercase keys and default headers.
• table (optional) mesgt.headers - Header-name strings mapped to header-value strings.
• string, function or table mesgt.body - Text, a chunk-source function, or a sequence of message tables for a multipart body. A source returns chunk (string), nil at EOF, or nil, error on failure. Multipart tables can include preamble and epilogue strings.
• string (optional) mesgt.date - Default Date header. Omitted uses the current UTC date and time plus zone.
• string (optional) mesgt.zone - Date-header zone suffix when date is generated; defaults to "-0000".
• string (optional) mesgt["x-mailer"] - Default X-Mailer header; omitted uses socket._VERSION. Explicit headers override the default Date and X-Mailer values.

Return values

• function source - Call without arguments to obtain chunk (string), nil at completion, or nil, error. Stop after nil. Message-generation and body-source errors are returned by this function.
• any (second source result on failure) error - Error yielded by the body source or raised during coroutine execution.

Throws

Invalid message or header data, date formatting errors and Lua allocation errors can throw while creating the source. Once created, the source returns coroutine execution errors as nil, error.

local smtp = require("socket.smtp")

smtp.send{
  server   = "smtp.example.com",
  port     = 587,
  user     = "user",
  password = "secret",
  from     = "<me@example.com>",
  rcpt     = "<you@example.com>",
  source   = smtp.message{
    headers = { subject = "Test" },
    body = "Hello from BAS"
  },
  starttls = true,             -- BAS extension
  shark    = ba.sharkclient(), -- BAS extension (optional)
}

File Sources (ltn12.lua)

ltn12.source.file(handle[,io_error])

Creates a chunk source used by data pumps, including file-backed SMTP message bodies and attachments. The source closes the file when a read returns no chunk, whether due to EOF or a reported read error.

Parameters

• file userdata or nil handle - Readable file handle with read and close methods. Nil creates a source that reports an open failure.
• string (optional) io_error - Open-failure message when handle is nil; defaults to "unable to open file".

Return values

• function source - Call with no arguments to read the next chunk. Stop calling after it returns nil.
• string or nil (source result) chunk - Next bytes, or nil when the file read returns no chunk. A reported read error is treated as EOF.
• string or nil (second source result) error - Open-failure message only when handle was nil. With a supplied handle, reported read and close errors are discarded.

Throws

Invalid file objects or method calls can throw when the source runs. Errors thrown by read or close propagate. Error values returned by those methods are discarded. Lua allocation errors can also propagate.

If a consumer stops before the source closes the file, it remains responsible for closing it. Because this helper discards returned read errors, an incomplete file can appear to end normally, including when used for an SMTP attachment. Applications needing error reporting must supply a source that preserves those errors.

High-Level Mail Helper (socket/mail.lua)

socket.mail(config) (BAS extension)

Creates a simplified mail sender wrapper on top of socket.smtp. This helper is BAS-specific and not part of standard LuaSocket. It is intended to make common email sending (text/HTML/attachments) easier. See the BAS SMTP documentation for details.

Parameters

• table config - Connection settings; server is required. See the SMTP reference for the supported fields and mail:send message settings.

Return values

• table mail - Mail object with a send method. Constructor copies configuration fields; it does not open a connection.

Throws

Invalid configuration objects or a missing server field throw. Lua allocation errors can propagate.