Module eco.http.server

HTTP/HTTPS server.

This module implements a simple HTTP/1.1 server (with optional TLS when options.cert and options.key are provided).

The main entry point is listen, which accepts connections and invokes a user handler with a connection object and a request table.

Functions

listen ([ipaddr], port[, options], handler) Listen and serve HTTP requests.

Class connection

connection:remote_addr () Get peer address.
connection:add_header (name, value) Add/override a response header.
connection:set_status (code[, status]) Set response status code.
connection:send_error (code[, status[, content]]) Send an error response.
connection:redirect (code, location) Redirect to another location.
connection:send_file (path[, count[, offset]]) Send a file as chunked response body.
connection:flush () Flush pending response data.
connection:read_body ([count[, timeout]]) Read request body data.
connection:read_formdata (req[, timeout]) Incrementally parse multipart/form-data.
connection:discard_body () Discard remaining request body bytes.
connection:serve_file (req) Serve a static file from options.docroot.


Functions

listen ([ipaddr], port[, options], handler)
Listen and serve HTTP requests.

This function creates a listening socket and enters an accept loop.

The handler is called as handler(con, req) for each request. Returning false from the handler closes the connection.

req is a plain table with common fields:

  • method, raw_path, path
  • major_version, minor_version
  • headers (lowercased keys)
  • query (table) and query_string
  • form (table) used by connection:read_formdata

options commonly used:

  • docroot (string) document root (default .).
  • index (string) index file name (default index.html).
  • http_keepalive (number) keepalive timeout seconds (default 30).
  • gzip (boolean) serve .gz when available.
  • TLS: set cert and key to enable TLS via eco.ssl.listen.

Other fields are passed to eco.socket.listen_tcp / eco.ssl.listen.

Parameters:

  • ipaddr string Listen address. (optional)
  • port int Listen port.
  • options table Server options. (optional)
  • handler function Request handler.

Returns:

  1. nil On failure.
  2. string Error message.

Class connection

UBus connection returned by ubus.connect.

This object manages an ubus connection and dispatches events/call replies in a background coroutine.

connection:remote_addr ()
Get peer address.

Returns:

    table Peer address table (e.g. { ipaddr=..., port=... }).
connection:add_header (name, value)
Add/override a response header.

Must be called before the response head is sent.

Parameters:

connection:set_status (code[, status])
Set response status code.

Must be called before the response head is sent.

Parameters:

  • code int Status code.
  • status string Reason phrase. (optional)

Returns:

    boolean true
connection:send_error (code[, status[, content]])
Send an error response.

If content is omitted, sends an empty body.

Parameters:

  • code int Status code.
  • status string Reason phrase. (optional)
  • content string Response body. (optional)

Returns:

    boolean true
connection:redirect (code, location)
Redirect to another location.

Parameters:

  • code int Redirect status code (3xx).
  • location string Location header value.

Returns:

    boolean true
connection:send_file (path[, count[, offset]])
Send a file as chunked response body.

This is a helper for serving static files and uses chunked encoding.

Parameters:

  • path string File path.
  • count int Bytes to send. (optional)
  • offset int Start offset. (optional)

Returns:

    boolean true On success.

Or

  1. nil On failure.
  2. string Error message.
connection:flush ()
Flush pending response data.

Returns:

    boolean true On success.

Or

  1. nil On failure.
  2. string Error message.
connection:read_body ([count[, timeout]])
Read request body data.

Reads up to count bytes from the request body. Returns an empty string when the body is fully consumed.

Parameters:

  • count int Bytes to read (defaults to remaining). (optional)
  • timeout number Timeout in seconds. (optional)

Returns:

    string data

Or

  1. nil On error.
  2. string Error message.
connection:read_formdata (req[, timeout])

Incrementally parse multipart/form-data.

This helper parses multipart formdata from the request body and returns events:

  • "header", { name, value }
  • "body", { data, done } where done indicates end of part
  • "end" when finished

Parameters:

  • req table Request table passed to handler.
  • timeout number Timeout in seconds. (optional)

Returns:

  1. string event
  2. table data

Or

  1. nil On failure.
  2. string Error message.
connection:discard_body ()
Discard remaining request body bytes.

Returns:

    boolean true On success.

Or

  1. nil On failure.
  2. string Error message.
connection:serve_file (req)
Serve a static file from options.docroot.

This helper implements basic file serving with etag and if-modified-since handling.

Parameters:

  • req table Request table.

Returns:

    boolean true When handled (including errors written).

Or

    nil When handler should close the connection.
generated by LDoc 1.5.0 Last updated 2026-04-09 14:48:22