classDocs / http / Server

http.Server

classserversource

Object → http.Server

An HTTP server backed by HolyLib's httpserver.

lua

local server = http.Server()

server:get( "/hello", function( req, res )
    res.content = "hello " .. req.remote_addr
end )

server:start( "0.0.0.0", 8080 )

Handlers can defer the reply:

return a Future, the request finishes when it settles, a failed or cancelled future replies via the error handler;
return false, then call req:finish() (or res:finish()) later.

A deferred request that is dropped without :finish is finished when it is collected. Stopping or restarting the server answers every deferred request with 503.

A running server is kept alive until :stop or :destroy, a stopped one is destroyed when collected.

Constructor

http.Server(name: string?): http.Server

Fields

Name	Type	Description
`name`	`string`	The server name used by `http.Server.findByName`, max length is 63 characters.
`address`	`string`	The bind address from the last `:start`. Read-only.
`port`	`integer`	The listen port from the last `:start`, or `0` before start. Read-only.
`running`	`boolean`	`true` if the server is currently listening, `false` once destroyed. Read-only.
`error_handler`	`http.Server.ErrorHandler \| nil`	Called when a route handler throws or its future fails, `nil` (and the fallback when it throws itself) replies `500 Internal Server Error`.
`tcp_nodelay`	`boolean \| nil`	`true` sets TCP_NODELAY on accepted sockets. `nil` until assigned (HolyLib default).
`read_timeout`	`number \| nil`	The maximum time allowed for a read, in seconds (fractions are microseconds). `nil` until assigned (HolyLib default).
`write_timeout`	`number \| nil`	The maximum time allowed for a write, in seconds (fractions are microseconds). `nil` until assigned (HolyLib default).
`payload_max_length`	`integer \| nil`	The maximum accepted request body length in bytes. `nil` until assigned (HolyLib default).
`keep_alive_timeout`	`integer \| nil`	How long keep-alive connections may stay open, in seconds. `nil` until assigned (HolyLib default).
`keep_alive_max_count`	`integer \| nil`	How many requests a keep-alive connection may serve. `nil` until assigned (HolyLib default).
`thread_sleep`	`integer \| nil`	How long worker threads sleep (ms) while waiting for the main thread to handle a request. `nil` until assigned (HolyLib default).
`available`	`boolean`

Static functions

`findByName`	Finds an existing server by its name property.
`getAll`	Returns every currently existing HolyLib HttpServer wrapped as http.Server objects.

#http.Server.findByName

serversource

function http.Server.findByName(name: string): http.Server | nil

Finds an existing server by its name property.

Returns a dreamwork wrapper around the HolyLib object, or nil if none matched. Wrappers of servers created elsewhere (e.g. before a reload) do not destroy them when collected.

Parameters

Name	Type	Description
`name`	`string`	The server name to look for.

Returns

Type	Name	Description
`http.Server \| nil`	`server`

#http.Server.getAll

serversource

function http.Server.getAll(): http.Server[]

Returns every currently existing HolyLib HttpServer wrapped as http.Server objects.

Wrappers of servers created elsewhere do not destroy them when collected.

Returns

Type	Name	Description
`http.Server[]`	`servers`

Methods

`addProxy`	Trusts proxy_address as a reverse proxy and reads the client IP from header_name.
`delete`	Registers a DELETE handler.
`destroy`	Stops and destroys the underlying HolyLib server, even one found with findByName / getAll.
`get`	Registers a GET handler.
`mount`	Mounts a filesystem folder at the given URL path.
`options`	Registers an OPTIONS handler.
`patch`	Registers a PATCH handler.
`post`	Registers a POST handler.
`prepare`	Queues a prepared response for the next matching request from the given player user_id.
`put`	Registers a PUT handler.
`setThreads`	Configures the worker thread pool size.
`start`	Starts (or restarts) the server on the given address and port.
`stop`	Stops the server if it is running, deferred requests are answered with 503.
`unmount`	Removes every mount previously set for path.

#Server:addProxy

serversource

function http.Server:addProxy(proxy_address: string, header_name: string, use_last_ip?: boolean)

Trusts proxy_address as a reverse proxy and reads the client IP from header_name.

Parameters

Name	Type	Description
`proxy_address`	`string`	The remote address of the trusted proxy.
`header_name`	`string`	Header that carries the real client IP, e.g. `"X-Forwarded-For"`.
`use_last_ip`optional	`boolean`	Prefer the last IP in a comma-separated header. Defaults to `false`.

#Server:delete

serversource

function http.Server:delete(path: string, handler: http.Server.Handler, ip_whitelist?: boolean)

Registers a DELETE handler.

Parameters

Name	Type	Description
`path`	`string`	The URL path pattern.
`handler`	`http.Server.Handler`	The route handler.
`ip_whitelist`optional	`boolean`	Restrict to connected players. Defaults to `false`.

#Server:destroy

serversource

function http.Server:destroy()

Stops and destroys the underlying HolyLib server, even one found with findByName / getAll.

Further method calls raise an error.

#Server:get

serversource

function http.Server:get(path: string, handler: http.Server.Handler, ip_whitelist?: boolean)

Registers a GET handler. Path parameters use :name segments (e.g. "/user/:id").

When ip_whitelist is true, only requests from connected players' IPs are handled.

Parameters

Name	Type	Description
`path`	`string`	The URL path pattern.
`handler`	`http.Server.Handler`	The route handler.
`ip_whitelist`optional	`boolean`	Restrict to connected players. Defaults to `false`.

#Server:mount

serversource

function http.Server:mount(path: string, folder: string)

Mounts a filesystem folder at the given URL path.

Parameters

Name	Type	Description
`path`	`string`	The URL path prefix.
`folder`	`string`	The filesystem folder to serve.

#Server:options

serversource

function http.Server:options(path: string, handler: http.Server.Handler, ip_whitelist?: boolean)

Registers an OPTIONS handler.

Parameters

Name	Type	Description
`path`	`string`	The URL path pattern.
`handler`	`http.Server.Handler`	The route handler.
`ip_whitelist`optional	`boolean`	Restrict to connected players. Defaults to `false`.

#Server:patch

serversource

function http.Server:patch(path: string, handler: http.Server.Handler, ip_whitelist?: boolean)

Registers a PATCH handler.

Parameters

Name	Type	Description
`path`	`string`	The URL path pattern.
`handler`	`http.Server.Handler`	The route handler.
`ip_whitelist`optional	`boolean`	Restrict to connected players. Defaults to `false`.

#Server:post

serversource

function http.Server:post(path: string, handler: http.Server.Handler, ip_whitelist?: boolean)

Registers a POST handler.

Parameters

Name	Type	Description
`path`	`string`	The URL path pattern.
`handler`	`http.Server.Handler`	The route handler.
`ip_whitelist`optional	`boolean`	Restrict to connected players. Defaults to `false`.

#Server:prepare

serversource

function http.Server:prepare(user_id: integer, path: string, method: http.RequestMethod | string, required_headers: table<string, string>, handler: fun( response: http.Server.Response ), uses?: integer)

Queues a prepared response for the next matching request from the given player user_id.

handler runs immediately to fill the response, matching requests are then answered on the worker thread without any Lua call. The response is invalid after handler returns.

Parameters

Name	Type	Description
`user_id`	`integer`	The player's UserID (`-1` for non-player / unmatched clients).
`path`	`string`	Exact request path to match.
`method`	`http.RequestMethod \| string`	Exact HTTP method to match.
`required_headers`	`table<string, string>`	Headers that must be present with these values.
`handler`	`fun( response: http.Server.Response )`	Fills the prepared response.
`uses`optional	`integer`	How many times this entry may match. Defaults to `1`.

#Server:put

serversource

function http.Server:put(path: string, handler: http.Server.Handler, ip_whitelist?: boolean)

Registers a PUT handler.

Parameters

Name	Type	Description
`path`	`string`	The URL path pattern.
`handler`	`http.Server.Handler`	The route handler.
`ip_whitelist`optional	`boolean`	Restrict to connected players. Defaults to `false`.

#Server:setThreads

serversource

function http.Server:setThreads(min_threads: integer, max_threads: integer)

Configures the worker thread pool size.

The pool is created on start, a running server restarts on the next frame.

Parameters

Name	Type	Description
`min_threads`	`integer`	Minimum number of worker threads.
`max_threads`	`integer`	Maximum number of worker threads.

#Server:start

serversource

function http.Server:start(address: string, port: integer)

Starts (or restarts) the server on the given address and port.

HolyLib binds on a separate thread, so running may stay false for a moment and a failed bind is not reported.

Route and setting changes on a running server restart it on the next frame.

Parameters

Name	Type	Description
`address`	`string`	Bind address, e.g. `"0.0.0.0"` or `"127.0.0.1"`.
`port`	`integer`	TCP port to listen on.

#Server:stop

serversource

function http.Server:stop()

Stops the server if it is running, deferred requests are answered with 503.

#Server:unmount

serversource

function http.Server:unmount(path: string)

Removes every mount previously set for path.

Parameters

Name	Type	Description
`path`	`string`	The URL path prefix to unmount.