server

local server = require("@lute/net/server")

WARNING

These APIs are still open to future evolution. In new major versions, they may change in backwards incompatible ways.

Summary

Entry	Description
Configuration	Configuration for starting an HTTP server.
Handler	A request handler function: receives a ReceivedRequest and Server, and returns a ServerResponse.
ReceivedRequest	An HTTP request received by the server, containing method, path, body, query params, and headers.
Server	A running HTTP server handle, with hostname, port, and lifecycle methods.
ServerResponse	A response that can be returned from a server handler: a plain string body, or a table with status, body, and headers.
ServerWebSocket	A server-side WebSocket connection handle.
WebSocketHandlers	Event handlers for server-side WebSocket connections.
serve	Starts an HTTP server with the given handler or full configuration. Returns a Server handle.

---

Types

Configuration

Configuration for starting an HTTP server.

type Configuration = {
	hostname: string?,
	port: number?,
	reuseport: boolean?,
	tls: { certfilename: string, keyfilename: string, passphrase: string?, cafilename: string? }?,
	handler: Handler?,
	websocket: WebSocketHandlers?,
}

---

Handler

A request handler function: receives a ReceivedRequest and Server, and returns a ServerResponse.

type Handler = (request: ReceivedRequest, server: Server) -> ServerResponse?

---

ReceivedRequest

An HTTP request received by the server, containing method, path, body, query params, and headers.

type ReceivedRequest = {
	method: string,
	path: string,
	body: string,
	query: { [string]: string },
	headers: { [string]: string },
}

---

Server

A running HTTP server handle, with hostname, port, and lifecycle methods.

type Server = {
	hostname: string,
	port: number,
	close: () -> boolean,
	upgrade: (self: Server, req: ReceivedRequest) -> boolean,
}

---

ServerResponse

A response that can be returned from a server handler: a plain string body, or a table with status, body, and headers.

type ServerResponse = string | {
	status: number?,
	body: string?,
	headers: { [string]: string }?,
}

---

ServerWebSocket

A server-side WebSocket connection handle.

type ServerWebSocket = {
	send: (self: ServerWebSocket, data: string | buffer) -> number,
	close: (self: ServerWebSocket, code: number?, message: string?) -> (),
}

---

WebSocketHandlers

Event handlers for server-side WebSocket connections.

type WebSocketHandlers = {
	open: ((ws: ServerWebSocket) -> ())?,
	message: ((ws: ServerWebSocket, message: string | buffer) -> ())?,
	close: ((ws: ServerWebSocket, code: number, message: string) -> ())?,
	drain: ((ws: ServerWebSocket) -> ())?,
}

---

Functions and Properties

server.serve

Starts an HTTP server with the given handler or full configuration. Returns a Server handle.

(config: Handler | Configuration) -> Server

---