WebService | SignalWire

WebService serves static files from one or more local directories, each mounted at a URL route prefix. It supports HTTP Basic Auth, extension allowlists and blocklists, file size limits, CORS, directory browsing, and optional SSL/TLS. Use it when an agent needs to serve supporting assets such as audio files, images, or prompts from the same process.

Every route except /health requires HTTP Basic Auth, and start() throws until credentials are configured. Supply them with the basicAuth option, the config file’s security.auth.basic, or the SWML_BASIC_AUTH_USER and SWML_BASIC_AUTH_PASSWORD environment variables.

Constructor

options

WebServiceOptions

Configuration object. Every field is optional. Explicit options override values from the config file.

options.port

numberDefaults to 8002

Port to bind to.

options.directories

Record<string, string>Defaults to {}

Map of URL route prefixes to local directory paths.

options.basicAuth

[string, string]

Basic auth credentials as [username, password]. Falls back to the config file’s security.auth.basic, then to the SWML_BASIC_AUTH_USER and SWML_BASIC_AUTH_PASSWORD environment variables. Every route except /health requires them. If no password is configured from any of these (an empty one doesn’t count), the service refuses every request and start() throws.

options.configFile

string

Path to a JSON config file.

options.enableDirectoryBrowsing

booleanDefaults to false

Serve directory listings and fall back to index.html.

options.allowedExtensions

string[]

Allowlist of file extensions, for example ['.html', '.css']. All extensions are allowed when omitted.

options.blockedExtensions

string[]Defaults to ['.env', '.git', '.gitignore', '.key', '.pem', '.crt', '.pyc', '__pycache__', '.DS_Store', '.swp']

Blocklist of file extensions or names. An entry is also refused as the name of any directory on the path below the mount. Whatever this holds, a path with a component below the mount that starts with a dot, other than .well-known, is never served.

options.maxFileSize

numberDefaults to 104857600

Maximum file size in bytes (100 MB by default).

options.enableCors

booleanDefaults to true

Enable CORS.

options.ssl

SslOptions

SSL/TLS configuration. See SslConfig for the fields.

Properties

port

number

Port the service binds to.

enableDirectoryBrowsing

boolean

Whether directory listings are enabled.

maxFileSize

number

Maximum file size in bytes that will be served.

enableCors

boolean

Whether CORS is enabled.

allowedExtensions

string[] | null

Allowlist of file extensions, or null to allow all (subject to the blocklist).

blockedExtensions

string[]

Blocklist of file extensions and file names.

directories

Record<string, string>

Map of URL route prefixes to local directory paths.

sslConfig

SslConfig

The SslConfig instance used by this service, for inspecting SSL settings after construction. Read-only.

Methods

addDirectory

Add a directory to serve at a URL route prefix.

removeDirectory

Stop serving a directory.

getApp

Get the Hono app for mounting or testing.

start

Start the HTTP or HTTPS service.

stop

Stop the service and release resources.

Example

import { WebService } from '@signalwire/sdk';
const web = new WebService({
  port: 8080,
  directories: { '/audio': './public/audio' },
  basicAuth: ['audio', process.env['AUDIO_PASSWORD'] ?? ''],
  allowedExtensions: ['.mp3', '.wav'],
});
await web.start();
// GET http://host:8080/audio/greeting.mp3