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.secure([shark]) (BAS extension)

Sets the default SharkSSL client configuration used by subsequent socket operations that use this compatibility layer. If omitted, BAS defaults (ba.sharkclient()) are used where applicable.

local socket = require("socket")
-- optional global default for TLS-enabled connects/upgrades
socket.secure(ba.sharkclient())

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.

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.

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.

TLS helpers on socket.tcp() (BAS extensions)

• tcp:upgrade([shark]): Upgrade an existing connection to TLS using SharkSSL.
• tcp:dohandshake([op]): Performs/ensures TLS handshake using op.shark or ba.sharkclient().
• tcp:sslhandshake(): Alias for tcp:dohandshake().
• tcp:certificate(): Returns peer certificate information from the underlying BAS socket.

Socket state/interop helpers (BAS extensions)

• tcp:sock([op]): Get the underlying BAS socket; if op is provided, update stored options.
• tcp:connected(): Returns true if the compatibility object currently wraps an open socket.
• tcp:sockname() / tcp:peername(): Short aliases in addition to getsockname() / getpeername().

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

• mode is accepted for compatibility but not used.
• Timeouts are stored internally in milliseconds for BAS reads/writes.
• gettimeout() returns the stored internal value (milliseconds), not standard LuaSocket-style seconds.
• Calling settimeout() before a connection still stores the timeout, but its return value may differ from standard LuaSocket.

tcp:shutdown() (behavior difference)

BAS compatibility maps shutdown() to close(). Half-close semantics are not provided by this layer.

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 connection methods (BAS extensions)

• smtp:upgrade([shark]): Enables implicit TLS after TCP connect (used for SMTPS).
• smtp:starttls([domain[, shark]]): Sends STARTTLS, upgrades the transport, and re-issues EHLO.
• tp:upgrade([shark]): Transport-layer TLS upgrade hook used by SMTP.

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

• mailt.shark: SharkSSL client configuration to use for TLS.
• mailt.starttls (true/false): If true and the server advertises STARTTLS, upgrade 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, this code path does not force an error; applications that require encrypted transport should validate server capabilities explicitly.
• If no SharkSSL object is explicitly provided, BAS defaults are used (ba.sharkclient()) during TLS upgrade.

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.

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)
}

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.