HSHTTPServer
TypeAn HTTP server instance created by hs.httpserver.create().
Configure with chainable setter methods, then call start() to begin accepting connections.
The server supports synchronous and async (Promise-returning) request callbacks, optional
static file serving, HTTP Basic authentication, Bonjour advertisement, and TLS via PKCS#12.
Do not instantiate HSHTTPServer directly — use hs.httpserver.create().
Properties
Methods
setPort(port) -> HSHTTPServer
Set the TCP port to listen on. Must be called before `start()`.
Pass 0 to let the OS assign an available port (use `getPort()` after `start()` to discover it).
Declaration
setPort(port) -> HSHTTPServerParameters
| Name | Type | Description |
|---|---|---|
| port | number | TCP port number (0–65535). |
Returns
HSHTTPServer
This server, for chaining.
Example
server.setPort(8080)setInterface(iface) -> HSHTTPServer
Set the network interface to listen on.
Pass `null` to listen on all interfaces (the default). Pass `"localhost"` or `"loopback"`
to restrict to the loopback interface only.
Declaration
setInterface(iface) -> HSHTTPServerParameters
| Name | Type | Description |
|---|---|---|
| iface | string | Interface name or IP address string, or `null` for all interfaces. |
Returns
HSHTTPServer
This server, for chaining.
Example
server.setInterface("localhost") // loopback only
server.setInterface(null) // all interfacessetPassword(password) -> HSHTTPServer
Set a password required for Basic authentication.
When set, every request must supply an `Authorization: Basic` header with any
username and the configured password. Pass `null` to disable authentication.
Declaration
setPassword(password) -> HSHTTPServerParameters
| Name | Type | Description |
|---|---|---|
| password | string | The required password, or `null` to remove authentication. |
Returns
HSHTTPServer
This server, for chaining.
Example
server.setPassword("s3cr3t")setMaxBodySize(size) -> HSHTTPServer
Set the maximum allowed incoming request body size in bytes.
Requests with a body exceeding this limit receive a 413 response. Defaults to 10 MB.
Declaration
setMaxBodySize(size) -> HSHTTPServerParameters
| Name | Type | Description |
|---|---|---|
| size | number | Maximum body size in bytes. |
Returns
HSHTTPServer
This server, for chaining.
Example
server.setMaxBodySize(1024 * 1024) // 1 MBsetName(name) -> HSHTTPServer
Set the Bonjour service name advertised on the local network.
Only used when Bonjour is enabled via `setBonjour(true)`.
Declaration
setName(name) -> HSHTTPServerParameters
| Name | Type | Description |
|---|---|---|
| name | string | The Bonjour service name. |
Returns
HSHTTPServer
This server, for chaining.
Example
server.setName("My Hammerspoon Server")setBonjour(enable) -> HSHTTPServer
Enable or disable Bonjour advertisement of this server on the local network.
Declaration
setBonjour(enable) -> HSHTTPServerParameters
| Name | Type | Description |
|---|---|---|
| enable | boolean | `true` to advertise via Bonjour, `false` to disable (default). |
Returns
HSHTTPServer
This server, for chaining.
Example
server.setBonjour(true)setCallback(callback) -> HSHTTPServer
Set the request handler callback.
If the callback returns `null` or `undefined`, the server falls through to static file serving
(if a document root is set), or responds with 404.
Declaration
setCallback(callback) -> HSHTTPServerParameters
| Name | Type | Description |
|---|---|---|
| callback | function | null | The request handler, or `null` to clear. |
Returns
HSHTTPServer
This server, for chaining.
Example
server.setCallback((method, path, headers, body) => {
return {body: "<h1>Hello!</h1>", status: 200, headers: {"Content-Type": "text/html"}}
})setDocumentRoot(path) -> HSHTTPServer
Set the filesystem path to serve static files from.
When a document root is set, requests not handled by the callback are served as
static files from this directory. Pass `null` to disable static file serving.
Declaration
setDocumentRoot(path) -> HSHTTPServerParameters
| Name | Type | Description |
|---|---|---|
| path | string | Absolute path to a directory, or `null` to disable. |
Returns
HSHTTPServer
This server, for chaining.
Example
server.setDocumentRoot("/Users/me/Sites")setDirectoryIndex(files) -> HSHTTPServer
Set the list of index filenames checked when a directory is requested.
Defaults to `["index.html", "index.htm"]`. Files are checked in order.
Declaration
setDirectoryIndex(files) -> HSHTTPServerParameters
| Name | Type | Description |
|---|---|---|
| files | string[] | Array of filename strings. |
Returns
HSHTTPServer
This server, for chaining.
Example
server.setDirectoryIndex(["index.html", "default.html"])setAllowDirectoryListing(allow) -> HSHTTPServer
Enable or disable directory listing for requests that map to a directory with no index file.
When disabled (the default), directory requests without an index file return 403.
Declaration
setAllowDirectoryListing(allow) -> HSHTTPServerParameters
| Name | Type | Description |
|---|---|---|
| allow | boolean | `true` to serve directory listings, `false` to return 403 (default). |
Returns
HSHTTPServer
This server, for chaining.
Example
server.setAllowDirectoryListing(true)setTLSFromPKCS12(path, password) -> HSHTTPServer
Configure TLS using a PKCS#12 (.p12) identity file.
When TLS is configured, the server accepts HTTPS connections. The `.p12` file must
contain both the certificate and the private key.
Declaration
setTLSFromPKCS12(path, password) -> HSHTTPServerParameters
| Name | Type | Description |
|---|---|---|
| path | string | Absolute path to the `.p12` file. |
| password | string | The password protecting the `.p12` file. |
Returns
HSHTTPServer
This server, for chaining.
Example
server.setTLSFromPKCS12("/path/to/identity.p12", "passphrase").start()start() -> HSHTTPServer
Start the server and begin accepting connections.
The server must be configured before calling `start()`. To restart the server with new
settings, call `stop()` followed by `start()`.
Declaration
start() -> HSHTTPServerReturns
HSHTTPServer
This server, for chaining.
Example
const server = hs.httpserver.create().setPort(8080).setCallback(handler).start()stop() -> HSHTTPServer
Stop the server and close all connections.
Declaration
stop() -> HSHTTPServerReturns
HSHTTPServer
This server, for chaining.
Example
server.stop()destroy() -> None
Destroy this server, releasing all resources.
After calling `destroy()`, the server object should not be used.
Declaration
destroy() -> NoneReturns
None
Example
server.destroy()getPort() -> number
Get the TCP port the server is currently listening on.
Returns 0 if the server is not running.
Declaration
getPort() -> numberReturns
number
The TCP port number.
Example
console.log("Listening on port " + server.getPort())getName() -> string
Get the configured Bonjour service name.
Declaration
getName() -> stringReturns
string
The Bonjour service name.
Example
console.log(server.getName())getInterface() -> string
Get the configured network interface, or `null` if listening on all interfaces.
Declaration
getInterface() -> stringReturns
string
The interface name or IP address string, or `null`.
Example
console.log(server.getInterface())setWebSocketCallback(path, callback) -> HSHTTPServer
Register a WebSocket handler for a URL path.
When a client connects and performs a WebSocket upgrade handshake on `path`, the callback
is invoked with three arguments: `event` (string), `connection` (HSWebSocketConnection),
and `message` (string).
**Events:**
Pass `null` to remove the WebSocket handler for the path.
Declaration
setWebSocketCallback(path, callback) -> HSHTTPServerParameters
| Name | Type | Description |
|---|---|---|
| path | string | The URL path to handle WebSocket connections on (e.g. `"/ws"`). |
| callback | function | null | The event handler, or `null` to remove. |
Returns
HSHTTPServer
This server, for chaining.
Example
server.setWebSocketCallback('/ws', (event, conn, msg) => {
if (event === 'connected') conn.send('Welcome!')
else if (event === 'message') conn.send('Echo: ' + msg)
})