# "HTTP"
_Path: en/lua/http/http_
> "Handle HTTP requests and build responses. Access request data, route parameters, headers, and body content. Build responses with status codes…"
## Table of Contents
- HTTP
## Content
# HTTP
The `http` module reads the current server-side request and builds its response, including headers, route data, body content, streaming output, and Server-Sent Events.
This is an API reference with partial handler recipes. Names such as `id`, `data`, `token`, and application callbacks come from the surrounding handler. Request accessors generally return `value, error`, and response mutations return `error`; examples that consume a result check those errors.
For server configuration, see [HTTP Server](http/server.md).
## Loading
```lua
local http = require("http")
```
Add `http` to the executable entry's `modules:` list before requiring it. Examples using `uuid`, `fs`, or `time` require those modules separately.
## Accessing the Request
Read the current HTTP request context:
```lua
local req, err = http.request({
timeout = 5000, -- 5 second body read timeout
max_body = 10485760 -- 10MB max body
})
if err then return nil, err end
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `options.timeout` | integer | Body read timeout in ms (default: 300000 / 5 min) |
| `options.max_body` | integer | Max body size in bytes (default: 120MB) |
**Returns:** `Request, error`
## Accessing the Response
Read the current HTTP response context:
```lua
local res, err = http.response()
if err then return nil, err end
```
**Returns:** `Response, error`
### `method`
Return the request's HTTP method.
```lua
local method, method_err = req:method()
if method_err then return nil, method_err end
if method == http.METHOD.GET then
return get_resource(id)
elseif method == http.METHOD.POST then
local data, body_err = req:body_json()
if body_err then return nil, body_err end
return create_resource(data)
elseif method == http.METHOD.PUT then
local data, body_err = req:body_json()
if body_err then return nil, body_err end
return update_resource(id, data)
elseif method == http.METHOD.DELETE then
return delete_resource(id)
end
```
### `path`
Return the request path.
```lua
local path, err = req:path()
if err then return nil, err end
print(path) -- "/api/users/123"
-- Route based on path
if path:match("^/api/") then
return handle_api(req)
end
```
### `query`
Return one query parameter:
```lua
-- GET /search?q=hello&page=2&limit=10
local query, query_err = req:query("q")
if query_err then return nil, query_err end
-- With defaults
local page_text, page_err = req:query("page")
if page_err then return nil, page_err end
local page = tonumber(page_text) or 1
```
### `query_params`
Return all query parameters. Multiple values for one key are joined with commas.
```lua
-- GET /search?tags=lua&tags=go&active=true
local params, err = req:query_params()
if err then return nil, err end
-- {tags = "lua,go", active = "true"}
for key, value in pairs(params) do
print(key .. ": " .. value)
end
```
### `header`
Return one request header by name.
```lua
local uuid = require("uuid")
local auth, auth_err = req:header("Authorization")
if auth_err then return nil, auth_err end
if not auth then
local type_err = res:set_content_type(http.CONTENT.JSON)
if type_err then return nil, type_err end
local status_err = res:set_status(http.STATUS.UNAUTHORIZED)
if status_err then return nil, status_err end
return res:write_json({error = "Missing authorization"})
end
local correlation_id, correlation_err = req:header("X-Correlation-ID")
if correlation_err then return nil, correlation_err end
if not correlation_id then
correlation_id, correlation_err = uuid.v4()
if correlation_err then return nil, correlation_err end
end
```
Lookup is case-insensitive: `req:header("content-type")` and `req:header("Content-Type")` return the same value. A header sent more than once returns its values joined with `", "`. A header that is not present returns `nil`.
### headers
Gets every request header.
```lua
local headers, err = req:headers()
for name, value in pairs(headers) do
print(name .. ": " .. value)
end
```
**Returns:** `table, error`
Keys are canonical header names (`Content-Type`, `X-Correlation-ID`), regardless of the casing the client sent. Repeated headers are joined with `", "`, as in `req:header()`.
### content_type
Return the `Content-Type` header:
```lua
local ct, type_err = req:content_type() -- "application/json; charset=utf-8" or nil
if type_err then return nil, type_err end
```
### `content_length`
Return the `Content-Length` header value:
```lua
local length, length_err = req:content_length() -- number of bytes
if length_err then return nil, length_err end
```
### `host`
Return the `Host` header:
```lua
local host, host_err = req:host() -- "example.com:8080"
if host_err then return nil, host_err end
```
### `param`
Return one route parameter from a path pattern such as `/users/:id`:
```lua
-- Route: /users/:id/posts/:post_id
local id, param_err = req:param("id")
if param_err then return nil, param_err end
local valid = false
if id then
local validate_err
valid, validate_err = uuid.validate(id)
if validate_err then return nil, validate_err end
end
if not valid then
local type_err = res:set_content_type(http.CONTENT.JSON)
if type_err then return nil, type_err end
local status_err = res:set_status(http.STATUS.BAD_REQUEST)
if status_err then return nil, status_err end
return res:write_json({error = "Invalid ID format"})
end
```
### `params`
Return all route parameters:
```lua
-- Route: /orgs/:org/repos/:repo/issues/:issue
local p, err = req:params()
if err then return nil, err end
-- {org = "acme", repo = "widget", issue = "123"}
local issue = get_issue(p.org, p.repo, p.issue)
```
### `body`
Read the full request body as a string:
```lua
local body, err = req:body()
if err then return nil, err end
-- Parse XML manually
local is_xml, type_err = req:is_content_type("application/xml")
if type_err then return nil, type_err end
if is_xml then
local data = parse_xml(body)
end
-- Avoid logging raw request bodies; record only non-sensitive metadata.
logger.debug("Request body read", {length = #body})
```
`body()`, `body_json()`, `stream()`, and `parse_multipart()` consume the same request body. Choose one body-reading path per handler. `body()` and `body_json()` enforce the request object's timeout and size limit; `stream()` is incremental and does not apply those two options.
### `body_json`
Read and parse the request body as JSON:
```lua
local data, err = req:body_json()
if err then
local type_err = res:set_content_type(http.CONTENT.JSON)
if type_err then return nil, type_err end
local status_err = res:set_status(http.STATUS.BAD_REQUEST)
if status_err then return nil, status_err end
return res:write_json({error = "Invalid JSON: " .. err:message()})
end
-- Validate required fields
if not data.name or not data.email then
local type_err = res:set_content_type(http.CONTENT.JSON)
if type_err then return nil, type_err end
local status_err = res:set_status(http.STATUS.BAD_REQUEST)
if status_err then return nil, status_err end
return res:write_json({error = "Missing required fields"})
end
local user = create_user(data)
```
### `has_body`
Check whether the request has a body.
```lua
local has_body, body_state_err = req:has_body()
if body_state_err then return nil, body_state_err end
if has_body then
local data, body_err = req:body_json()
if body_err then return nil, body_err end
process(data)
else
local type_err = res:set_content_type(http.CONTENT.JSON)
if type_err then return nil, type_err end
local status_err = res:set_status(http.STATUS.BAD_REQUEST)
if status_err then return nil, status_err end
return res:write_json({error = "Request body required"})
end
```
`has_body()` returns `true` only when the request has a body object and a positive `Content-Length`. A chunked request or another request with unknown length can return `false`; handlers that permit such bodies should attempt their chosen body reader and handle its error instead.
### `is_content_type`
Check whether the request has the specified content type.
```lua
local is_json, type_check_err = req:is_content_type("application/json")
if type_check_err then return nil, type_check_err end
if not is_json then
local type_err = res:set_content_type(http.CONTENT.JSON)
if type_err then return nil, type_err end
local status_err = res:set_status(415)
if status_err then return nil, status_err end
return res:write_json({error = "Content-Type must be application/json"})
end
```
### `accepts`
Check whether the request accepts the specified content type.
```lua
local accepts_json, json_accept_err = req:accepts("application/json")
if json_accept_err then return nil, json_accept_err end
local accepts_html, html_accept_err = req:accepts("text/html")
if html_accept_err then return nil, html_accept_err end
if accepts_json then
return res:write_json(data)
elseif accepts_html then
local type_err = res:set_content_type("text/html; charset=utf-8")
if type_err then return nil, type_err end
return res:write(render_html(data))
else
local type_err = res:set_content_type(http.CONTENT.JSON)
if type_err then return nil, type_err end
local status_err = res:set_status(http.STATUS.NOT_ACCEPTABLE)
if status_err then return nil, status_err end
return res:write_json({error = "Cannot produce acceptable response"})
end
```
The pinned `accepts()` helper performs exact comma-separated matches plus `*/*`; it does not process media-type parameters, subtype wildcards, or quality weights, and a missing `Accept` header returns `false`. Use application-owned negotiation when those HTTP semantics matter.
### `remote_addr`
Return the client's remote network address.
```lua
local addr, addr_err = req:remote_addr() -- "192.168.1.100:54321"
if addr_err then return nil, addr_err end
-- Extract the host from IPv4 and bracketed IPv6 addresses
local ip = addr:match("^%[([^%]]+)%]:%d+$")
or addr:match("^([^:]+):%d+$")
or addr
-- Rate limiting by IP with an application-provided rate_limiter
if rate_limiter:is_limited(ip) then
local type_err = res:set_content_type(http.CONTENT.JSON)
if type_err then return nil, type_err end
local status_err = res:set_status(http.STATUS.TOO_MANY_REQUESTS)
if status_err then return nil, status_err end
return res:write_json({error = "Too many requests"})
end
```
### `parse_multipart`
Parse multipart form data, including file uploads. The optional `max_memory` argument sets the number of bytes held in memory before data spills to temporary files; the default is 32 MB.
```lua
local uuid = require("uuid")
local form, err = req:parse_multipart() -- or req:parse_multipart(8 * 1024 * 1024)
if err then
local type_err = res:set_content_type(http.CONTENT.JSON)
if type_err then return nil, type_err end
local status_err = res:set_status(http.STATUS.BAD_REQUEST)
if status_err then return nil, status_err end
return res:write_json({error = "Invalid form data"})
end
-- Access form values
local title = form.values.title
local description = form.values.description
-- Access uploaded files
if form.files.avatar then
local file = form.files.avatar[1]
local filename, name_err = file:name() -- untrusted client metadata
if name_err then return nil, name_err end
local size, size_err = file:size()
if size_err then return nil, size_err end
local content_type, header_err = file:header("Content-Type") -- "image/jpeg"
if header_err then return nil, header_err end
-- Read file content
local stream = file:stream()
local parts = {}
while true do
local chunk, err = stream:read(65536)
if err or not chunk then break end
parts[#parts + 1] = chunk
end
stream:close()
local content = table.concat(parts)
local stream, stream_err = file:stream()
if stream_err then return nil, stream_err end
local stored_name, id_err = uuid.v7()
if id_err then
stream:close()
return nil, id_err
end
local _, write_err = uploads:writefile(stored_name, stream, "wx")
local _, close_err = stream:close()
if write_err then return nil, write_err end
if close_err then return nil, close_err end
end
-- Handle multiple files
if form.files.documents then
for _, file in ipairs(form.files.documents) do
process_document(file)
end
end
```
Multipart field values are strings when a field occurs once and arrays when it occurs repeatedly. Treat uploaded filenames and `Content-Type` values as untrusted metadata; generate the storage name and inspect the content independently when its type matters.
The exclusive `wx` write prevents overwriting an existing object. A failed write does not prove that the target belongs to this request, so the failure path must not remove it blindly. Applications that need cleanup after partial writes should stage uploads under an ownership-tracked temporary name and promote them only after the write succeeds.
### `stream`
Read the request body as a stream:
```lua
local stream, stream_err = req:stream()
if stream_err then return nil, stream_err end
-- Process in chunks
local read_err
while true do
local chunk
chunk, read_err = stream:read(65536) -- 64KB chunks
if read_err or not chunk then break end
process_chunk(chunk)
end
local _, close_err = stream:close()
if read_err then return nil, read_err end
if close_err then return nil, close_err end
```
### `set_status`
Set the response status code.
`set_status()` writes the status and commits the response headers immediately. Call `set_header()`, `set_content_type()`, or `set_transfer()` first; later header changes return `errors.INVALID`.
```lua
local status_err = res:set_status(http.STATUS.CREATED)
if status_err then return nil, status_err end
-- Other common choices: 204 No Content, 400 Bad Request,
-- 401 Unauthorized, 403 Forbidden, 404 Not Found, and 500 Internal Error.
```
### `set_header`
Set one response header.
```lua
local request_id_err = res:set_header("X-Request-ID", correlation_id)
if request_id_err then return nil, request_id_err end
local cache_err = res:set_header("Cache-Control", "max-age=3600")
if cache_err then return nil, cache_err end
local rate_err = res:set_header("X-RateLimit-Remaining", tostring(remaining))
if rate_err then return nil, rate_err end
-- CORS headers
local origin_err = res:set_header("Access-Control-Allow-Origin", "*")
if origin_err then return nil, origin_err end
local methods_err = res:set_header("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE")
if methods_err then return nil, methods_err end
local headers_err = res:set_header("Access-Control-Allow-Headers", "Content-Type, Authorization")
if headers_err then return nil, headers_err end
```
### `set_content_type`
Set the response content type.
```lua
local type_err = res:set_content_type(http.CONTENT.JSON)
if type_err then return nil, type_err end
-- Other examples: "text/html; charset=utf-8" or "application/pdf".
```
### `write`
Write to the response body:
```lua
local write_err = res:write("Hello, World!")
if write_err then return nil, write_err end
-- Build response incrementally
for _, fragment in ipairs({
"
",
"Title
",
"Content
",
""
}) do
local fragment_err = res:write(fragment)
if fragment_err then return nil, fragment_err end
end
```
### `write_json`
Encode a value as JSON and write it to the response:
```lua
-- Success response
local write_err = res:write_json({
data = users,
total = count,
page = page
})
if write_err then return nil, write_err end
-- Error response
local type_err = res:set_content_type(http.CONTENT.JSON)
if type_err then return nil, type_err end
local status_err = res:set_status(http.STATUS.BAD_REQUEST)
if status_err then return nil, status_err end
local error_write_err = res:write_json({
error = "Validation failed",
details = {
{field = "email", message = "Invalid format"},
{field = "age", message = "Must be positive"}
}
})
if error_write_err then return nil, error_write_err end
```
`write()`, `write_json()`, `flush()`, and `write_event()` also commit headers. `write_json()` sets `Content-Type: application/json` only when headers have not already been committed.
### `flush`
Flush buffered response data to the client:
-- Stream progress updates
for i = 1, 100 do
local write_err = res:write(string.format("Progress: %d%%\n", i))
if write_err then return nil, write_err end
local flush_err = res:flush()
if flush_err then return nil, flush_err end
local _, sleep_err = time.sleep("100ms")
if sleep_err then return nil, sleep_err end
end
### `set_transfer`
Set the transfer mode for a streaming response:
```lua
-- Chunked transfer
local transfer_err = res:set_transfer(http.TRANSFER.CHUNKED)
if transfer_err then return nil, transfer_err end
for chunk in get_chunks() do
local write_err = res:write(chunk)
if write_err then return nil, write_err end
local flush_err = res:flush()
if flush_err then return nil, flush_err end
end
-- Server-Sent Events
local sse_err = res:set_transfer(http.TRANSFER.SSE)
if sse_err then return nil, sse_err end
```
### `write_event`
Write a Server-Sent Event:
```lua
-- Real-time updates
local transfer_err = res:set_transfer(http.TRANSFER.SSE)
if transfer_err then return nil, transfer_err end
local connected_err = res:write_event({name = "connected", data = {client_id = client_id}})
if connected_err then return nil, connected_err end
for progress in task:progress() do
local event_err = res:write_event({name = "progress", data = {percent = progress}})
if event_err then return nil, event_err end
end
local complete_err = res:write_event({name = "complete", data = {result = result}})
if complete_err then return nil, complete_err end
-- Chat messages
local message_err = res:write_event({name = "message", data = {
from = "alice",
text = "Hello!",
timestamp = time.now():unix()
}})
if message_err then return nil, message_err end
```
### Streams and Server Shutdown
Calling `set_transfer()` or the first `write_event()` makes the response a stream. When the HTTP server starts shutting down, the handler ends at its next yield, loop iteration, or function call. Until then, `write()`, `write_json()`, `write_event()`, and `flush()` return a retryable `errors.CANCELED` error.
The response completes with its committed status, including when no body has been written yet. Ordinary non-streaming requests retain their graceful completion window.
### HTTP Methods
```lua
http.METHOD.GET
http.METHOD.POST
http.METHOD.PUT
http.METHOD.DELETE
http.METHOD.PATCH
http.METHOD.HEAD
http.METHOD.OPTIONS
```
### Status Codes
```lua
-- Success (2xx)
http.STATUS.OK -- 200
http.STATUS.CREATED -- 201
http.STATUS.ACCEPTED -- 202
http.STATUS.NO_CONTENT -- 204
http.STATUS.PARTIAL_CONTENT -- 206
-- Redirect (3xx)
http.STATUS.MOVED_PERMANENTLY -- 301
http.STATUS.FOUND -- 302
http.STATUS.SEE_OTHER -- 303
http.STATUS.NOT_MODIFIED -- 304
http.STATUS.TEMPORARY_REDIRECT -- 307
http.STATUS.PERMANENT_REDIRECT -- 308
-- Client Error (4xx)
http.STATUS.BAD_REQUEST -- 400
http.STATUS.UNAUTHORIZED -- 401
http.STATUS.PAYMENT_REQUIRED -- 402
http.STATUS.FORBIDDEN -- 403
http.STATUS.NOT_FOUND -- 404
http.STATUS.METHOD_NOT_ALLOWED -- 405
http.STATUS.NOT_ACCEPTABLE -- 406
http.STATUS.CONFLICT -- 409
http.STATUS.GONE -- 410
http.STATUS.UNPROCESSABLE -- 422
http.STATUS.TOO_MANY_REQUESTS -- 429
-- Server Error (5xx)
http.STATUS.INTERNAL_ERROR -- 500 (alias: INTERNAL_SERVER_ERROR)
http.STATUS.NOT_IMPLEMENTED -- 501
http.STATUS.BAD_GATEWAY -- 502
http.STATUS.SERVICE_UNAVAILABLE -- 503
http.STATUS.GATEWAY_TIMEOUT -- 504
http.STATUS.VERSION_NOT_SUPPORTED -- 505
```
### Content Types
```lua
http.CONTENT.JSON -- "application/json"
http.CONTENT.FORM -- "application/x-www-form-urlencoded"
http.CONTENT.MULTIPART -- "multipart/form-data"
http.CONTENT.TEXT -- "text/plain"
http.CONTENT.STREAM -- "application/octet-stream"
```
### Transfer Modes
```lua
http.TRANSFER.CHUNKED -- "chunked"
http.TRANSFER.SSE -- "sse"
```
### Legacy Error-Type Constants
The module exports these compatibility strings, but current request and response methods do not return them. Runtime failures use the structured `errors.*` kinds described below.
```lua
http.ERROR.PARSE_FAILED -- Form/multipart parse error
http.ERROR.INVALID_STATE -- Invalid response state
http.ERROR.WRITE_FAILED -- Response write error
http.ERROR.STREAM_ERROR -- Body stream error
```
## Errors
| Condition | Kind | Retryable |
|-----------|------|-----------|
| No HTTP context | `errors.INTERNAL` | no |
| Body too large | `errors.INVALID` | no |
| Read timeout | `errors.INTERNAL` | no |
| Invalid JSON | `errors.INVALID` | no |
| Not multipart | `errors.INVALID` | no |
| Headers already sent | `errors.INVALID` | no |
| Write failed | `errors.INTERNAL` | no |
| Stream ended by server shutdown | `errors.CANCELED` | yes |
See [Error Handling](lua/core/errors.md) for working with errors.
## Navigation
Previous: "Excel Spreadsheets" (lua/data/excel)
Next: "HTTP Client" (lua/http/client)