Makes a one-shot streamed HTTP request.
The returned response must be fully consumed or explicitly closed.
@eryx/http Module
HTTP/1.1 client and server library.
Built on top of @eryx/_socket and @eryx/_ssl, this module provides
both one-shot convenience functions and lower-level connection and
server classes for HTTP and HTTPS, with cookie jars, pooled sessions,
streaming request and response bodies, multipart/form helpers, and
HTTP/1.1 trailer support.
Client - one-shot request:
local http = require("@eryx/http")
local response = http.get("http://example.com/")
print(response.status, response.reason)
print(response.body)
Client - persistent connection:
local conn = http.HttpConnection.new("example.com", 80)
conn:request("GET", "/")
local resp = conn:getResponse()
conn:close()
Cookies:
local jar = http.CookieJar.new()
http.get("http://example.com/login", { cookies = jar })
-- jar stores Set-Cookie headers; subsequent requests send them back
http.get("http://example.com/dashboard", { cookies = jar })
Multipart form upload:
local body, contentType = http.multipart({
{ name = "field", value = "text" },
{ name = "file", value = data, filename = "pic.png" },
})
http.post("http://example.com/upload", body, {
headers = { ["Content-Type"] = contentType },
})
Session with connection reuse:
local session = http.Session.new({
connectTimeout = 2,
readTimeout = 10,
maxConnectionsPerHost = 4,
})
local resp = session:get("https://example.com/api")
session:close()
Server:
local server = http.HttpServer.new(function(req, res)
res:send(200, "Hello, world!")
end, { port = 8080 })
server:listen(function(host, port)
print("Listening on " .. host .. ":" .. tostring(port))
end)
HTTPS Server:
local ssl = require("@eryx/_ssl")
local ctx = ssl.create_server_context("cert.pem", "key.pem")
local server = http.HttpServer.new(handler, { port = 443, sslCtx = ctx })
server:listen()
Summary
Functions
http.stream(method: string, url: string, options: RequestOptions?) → HttpConnection.HttpResponseStream
http.decodeMultipartBody(response: HttpConnection.HttpResponse) → { multipart.ParsedMultipartField }
API Reference
Functions
http.createApp
http.createApp(options) → ()
http.createMemorySessionStore
http.createMemorySessionStore() → ()
http.createFileSessionStore
http.createFileSessionStore(directory) → ()
http.createSqliteSessionStore
http.createSqliteSessionStore(database, tableName) → ()
http.request
http.stream
http.stream(method: string, url: string, options: RequestOptions?) → HttpConnection.HttpResponseStream
Parameters
The HTTP method (e.g. "GET", "POST").
The full URL including scheme and host.
Request options.
Returns
HttpConnection.HttpResponseStream
The streamed response.
http.get
Convenience wrapper for a GET request.
Parameters
The full URL to request.
Request options.
Returns
HttpConnection.HttpResponse
The parsed response.
http.post
Convenience wrapper for a POST request.
Parameters
The full URL to request.
The request body string.
Additional request options.
Returns
HttpConnection.HttpResponse
The parsed response.
http.put
Convenience wrapper for a PUT request.
Parameters
The full URL to request.
The request body string.
Additional request options.
Returns
HttpConnection.HttpResponse
The parsed response.
http.delete
Convenience wrapper for a DELETE request.
Parameters
The full URL to request.
Request options.
Returns
HttpConnection.HttpResponse
The parsed response.
http.head
Convenience wrapper for a HEAD request.
Returns headers only - the body will be empty.
Parameters
The full URL to request.
Request options.
Returns
HttpConnection.HttpResponse
The parsed response (body is empty).
http.raiseForStatus
Raises an error for HTTP 4xx and 5xx responses.
Parameters
A buffered HTTP response.
Returns
HttpConnection.HttpResponse
The same response when the status is not an error.
http.decodeJsonBody
Decodes a buffered response body as JSON.
Parameters
A buffered HTTP response.
Returns
The decoded JSON value.
http.decodeFormBody
Decodes a buffered response body as application/x-www-form-urlencoded.
Parameters
A buffered HTTP response.
Returns
http.decodeMultipartBody
Decodes a buffered response body as multipart/form-data.
The response must include a content-type header with a boundary
parameter.
http.decodeMultipartBody(response: HttpConnection.HttpResponse) → { multipart.ParsedMultipartField }
Parameters
A buffered HTTP response.
Returns
The decoded multipart fields.
http.parseQuery
Decodes a URL query string or x-www-form-urlencoded body.
http.formEncode
Encodes a table as application/x-www-form-urlencoded.
http.formDecode
Decodes a URL query string or x-www-form-urlencoded body.
http.multipartEncode
Encodes a list of form fields as a multipart/form-data body.
Returns the encoded body string and the Content-Type header
(which includes the boundary). Pass both to a request function:
local body, contentType = http.multipart({
{ name = "username", value = "alice" },
{ name = "avatar", value = fileContents, filename = "photo.png", contentType = "image/png" },
})
local resp = http.post("http://example.com/upload", body, {
headers = { ["Content-Type"] = contentType },
})
Parameters
A list of MultipartField entries.
Returns
http.multipartDecode
Parses a multipart/form-data body into individual fields.
Pass the raw body and either the full Content-Type header value or
just the boundary string.