Summary

Classes

Functions

API Reference

Classes

RequestBodyStream

Properties

_closed: boolean

_sock: any

_buffer: string

_trailers: { [string]: string }?

_mode: "empty" | "length" | "chunked"

_remaining: number

_chunkRemaining: number

_totalRead: number

_maxBodyBytes: number

_onFinish: (((string, { [string]: string }?) → ()))?

RequestBodyStream:_finish

RequestBodyStream:_finish() → ()

RequestBodyStream:_recvChunk

RequestBodyStream:_recvChunk() → string

RequestBodyStream:_recvUntil

RequestBodyStream:_recvUntil(delim: string) → string

RequestBodyStream:_recvExact

RequestBodyStream:_recvExact(n: number) → string

RequestBodyStream:_readChunkHeader

RequestBodyStream:_readChunkHeader() → ()

RequestBodyStream:read

Reads a chunk from a streamed request body.

In streamed request-body mode, handlers receive req.bodyStream, which exposes read, readAll, and close for incremental upload processing.

RequestBodyStream:read(count: number?) → string?

Parameters

count: number?

Maximum number of bytes to read. Defaults to 65536.

Returns

string?

The next body chunk, or nil when the stream ends.

RequestBodyStream:readAll

Reads the rest of a streamed request body into a string.

RequestBodyStream:readAll() → string

Returns

string

The remaining request body.

RequestBodyStream:close

Consumes and closes a streamed request body.

This is useful when a handler wants to abandon the body early but still allow the connection to be reused safely.

RequestBodyStream:close() → ()

ServerRequest

An incoming HTTP request received by an HttpServer.

Header names are lowercased for consistent lookup.

Properties

method: string

path: string

pathname: string

queryString: string

query: QueryTable

httpVersion: string

headers: { [string]: string }

trailers: { [string]: string }

contentType: string?

body: string

form: QueryTable?

multipart: { ParsedMultipartField }?

bodyStream: RequestBodyStream?

Available when streamRequestBodies = true.

remoteAddr: string

remotePort: number

ServerRequest:readBody

Reads and buffers the full body on demand.

ServerRequest:readBody() → string

ServerRequest:readForm

Decodes URL-encoded form data on demand.

ServerRequest:readForm() → QueryTable?

ServerRequest:readMultipart

Decodes multipart form-data on demand.

ServerRequest:readMultipart() → { ParsedMultipartField }?

ServerRequest:readJson

Decodes JSON request bodies on demand.

ServerRequest:readJson() → any?

HttpServer

A single-threaded HTTP (or HTTPS) server.

Create one with createServer, then call HttpServer.listen to start accepting connections. Provide an sslCtx in the options to enable HTTPS.

local server = http.createServer(function(req, res)
    print(req.method, req.path)
    res:send(200, "OK")
end, { port = 8080 })
server:listen()

Properties

_host: string

_port: number

_backlog: number

_clientTimeout: number

_keepAliveTimeout: number

_maxRequestsPerConnection: number?

_maxHeaderBytes: number

_maxBodyBytes: number

_streamRequestBodies: boolean

_callback: ServerCallback

_sock: _socket.Socket?

_running: boolean

_sslCtx: any?

TLS fields (nil for plain HTTP)

HttpServer.new

Creates a new HttpServer with the given request handler.

Call HttpServer.listen on the returned server to start accepting connections.

local server = http.createServer(function(req, res)
    print(req.method, req.path)
    res:send(200, "Hello, world!")
end)
server:listen(function(host, port)
    print("Listening on " .. host .. ":" .. tostring(port))
end)

HttpServer.new(callback: ServerCallback, options: HttpServerOptions?) → HttpServer

Parameters

callback: ServerCallback

The handler invoked for each incoming request.

options: HttpServerOptions?

Server configuration options.

Returns

HttpServer

The new server (not yet listening).

HttpServer:listen

Starts listening for connections and serves requests.

This call blocks until HttpServer.close is called or the process is interrupted. The optional callback is invoked once the socket is bound and ready to accept connections.

HttpServer:listen(callback: (((host: string, port: number) → ()))?) → never

Parameters

callback: (((host: string, port: number) → ()))?

Called with (host, port) when the server is ready.

HttpServer:_readRequest

Parse an incoming HTTP request from a client socket. Returns nil if the connection was closed before a full request arrived.

In the default mode, request bodies are buffered eagerly and exposed through req.body, req.form, and req.multipart. When streamRequestBodies = true, requests instead expose req.bodyStream along with req:readBody(), req:readForm(), req:readMultipart(), and req:readJson() for on-demand buffering/decoding. Chunked request trailers are exposed on req.trailers once the body has been fully consumed.

HttpServer:_readRequest(sock: any, remoteAddr: string, remotePort: number, initialBuffer: string?) → (ServerRequest?, string)

HttpServer:_handleConnection

Handles one accepted client connection.

This may serve multiple requests over the same socket when keep-alive is in use. Unread streamed request bodies are drained automatically before reusing the connection.

HttpServer:_handleConnection(client_sock: any, remoteAddr: string, remotePort: number) → boolean

Parameters

client_sock: any

The accepted client socket.

remoteAddr: string

The peer IP address.

remotePort: number

The peer port.

Returns

boolean

true when the connection was upgraded and the socket ownership has been transferred elsewhere.

HttpServer:close

Stops the server by closing the listening socket.

This unblocks the HttpServer.listen call, allowing the server loop to exit cleanly.

HttpServer:close() → ()

Functions

ServerRequestMethods:readBody

Reads and buffers the full request body on demand.

In default buffered mode this simply returns req.body. When streamed request-body mode is enabled, this drains req.bodyStream and caches the result.

ServerRequestMethods:readBody() → string

Returns

string

The full request body.

ServerRequestMethods:readForm

Decodes a request body as application/x-www-form-urlencoded.

In streamed request-body mode this reads the full body on demand.

ServerRequestMethods:readForm() → QueryTable?

Returns

QueryTable?

The decoded form fields, or nil when the request is not URL-encoded.

ServerRequestMethods:readMultipart

Decodes a request body as multipart/form-data.

In streamed request-body mode this reads the full body on demand.

ServerRequestMethods:readMultipart() → { ParsedMultipartField }?

Returns

{ ParsedMultipartField }?

Parsed multipart fields, or nil when the request is not multipart form-data.

ServerRequestMethods:readJson

Decodes a request body as JSON.

In streamed request-body mode this reads the full body on demand.

ServerRequestMethods:readJson() → any?

Returns

any?

The decoded JSON value, or nil when the request does not declare a JSON content type.

Types

HttpServerOptions

Options for creating an HttpServer.

host: string?

port: number?

backlog: number?

clientTimeout: number?

keepAliveTimeout: number?

maxRequestsPerConnection: number?

maxHeaderBytes: number?

maxBodyBytes: number?

streamRequestBodies: boolean?

When true, request bodies are exposed through req.bodyStream instead of being buffered eagerly.

sslCtx: _ssl.SslContext?