http
stableMake HTTP requests over TCP and work with HTTP messages, URLs, headers, and query strings.
use plugin http::{get, post, put, …} Functions (20)
- get Perform an HTTP GET request
- post Perform an HTTP POST request
- put Perform an HTTP PUT request
- patch Perform an HTTP PATCH request
- delete Perform an HTTP DELETE request
- head Perform an HTTP HEAD request
- request Perform a generic HTTP request
- build_request Build a raw HTTP request string
- build_response Build a raw HTTP response string
- parse_request_line Parse an HTTP request line
- parse_status_line Parse an HTTP status line
- parse_headers Parse raw HTTP headers into a table
- parse_url Parse a URL into its components
- build_query_string Build a URL-encoded query string
- parse_query_string Parse a query string into a table
- content_type_for Get MIME type for a file extension
- status_text Get reason phrase for an HTTP status code
- url_encode Percent-encode a string
- url_decode Percent-decode a string
- build_url Build a full URL from base, path, and params
Overview
http is a dependency-free networking toolkit built directly on raw TCP sockets.
It does two related jobs: it acts as a small HTTP client (get, post, put,
patch, delete, head, request) that opens a connection, sends a request, and
returns the response as a plain {status, headers, body} table, and it provides a
set of stateless message helpers for building and parsing HTTP request/response
strings, URLs, headers, and query strings. There are no handles or sessions to
manage — every function takes ordinary values and returns ordinary tables or
strings, so responses are just data you can index into and pass around.
Use it when you need to talk to an HTTP service, assemble or dissect HTTP messages
by hand, or work with URLs and query strings. Note that requests run over plain TCP:
https:// URLs are parsed and connected to, but no TLS handshake is performed, so
in practice the client speaks cleartext HTTP.
Common patterns
Make a request and branch on the status with its reason phrase:
use plugin http::{get, status_text}
let resp = get("http://httpbin.org/get")
let code = resp["status"]
print("{code} {status_text(code)}")
if code == 200 {
print(resp["body"])
}
Build a URL from parts, encoding query parameters, then fetch it:
use plugin http::{build_url, get}
let url = build_url("http://httpbin.org", "/get", #{"q": "hello world", "page": "2"})
print("requesting: {url}")
let resp = get(url)
print(resp["status"])
Post a JSON body and read a header back off the response table:
use plugin http::{post, content_type_for}
let resp = post("http://httpbin.org/post", '{"name":"Alice"}', content_type_for("json"))
print(resp["status"])
print(resp["headers"]["Content-Type"])
Perform an HTTP GET request
Sends an HTTP GET request to the given URL and returns a {status, headers, body} table. Supports HTTP and HTTPS (plain TCP; no TLS on HTTPS).
use plugin http::{get}
let resp = get("http://httpbin.org/get")
print("Status: {resp["status"]}")
print(resp["body"])
The response headers field is itself a string-keyed table you can index into:
use plugin http::{get}
let resp = get("http://httpbin.org/get")
print("served by: {resp["headers"]["Server"]}")
Perform an HTTP POST request
Sends an HTTP POST request with the given body and Content-Type header. Returns {status, headers, body}.
use plugin http::{post}
let resp = post("http://httpbin.org/post", '{"name":"Alice"}', "application/json")
print(resp["status"])
Submit a form-encoded body by pairing it with build_query_string:
use plugin http::{post, build_query_string, content_type_for}
let form = build_query_string(#{"user": "alice", "msg": "hi there"})
let resp = post("http://httpbin.org/post", form, content_type_for("form"))
print(resp["status"])
Perform an HTTP PUT request
Sends an HTTP PUT request. Useful for replacing a resource at a given URL.
use plugin http::{put}
let resp = put("http://api.example.com/items/1", '{"done":true}', "application/json")
print(resp["status"])
Perform an HTTP PATCH request
Sends an HTTP PATCH request for partial updates to a resource.
use plugin http::{patch}
let resp = patch("http://api.example.com/users/42", '{"email":"[email protected]"}', "application/json")
print(resp["status"])
Perform an HTTP DELETE request
Sends an HTTP DELETE request and returns {status, headers, body}.
use plugin http::{delete}
let resp = delete("http://api.example.com/items/1")
print(resp["status"])
Perform an HTTP HEAD request
Sends an HTTP HEAD request and returns {status, headers} without a body.
use plugin http::{head}
let resp = head("http://example.com")
print(resp["status"])
Perform a generic HTTP request
Sends an HTTP request with any method, custom headers table, and optional body. Returns {status, headers, body}.
use plugin http::{request}
let resp = request("GET", "http://httpbin.org/headers", #{"X-Custom": "hello"}, "")
print(resp["status"])
Use it for methods the convenience helpers don't cover, or to send an authenticated body request with full control over the headers:
use plugin http::{request}
let headers = #{"Authorization": "Bearer abc123", "Content-Type": "application/json"}
let resp = request("PUT", "http://api.example.com/items/1", headers, '{"done":true}')
print(resp["status"])
Build a raw HTTP request string
Constructs a raw HTTP/1.1 request string. Useful when implementing custom protocol handling.
use plugin http::{build_request}
let raw = build_request("GET", "http://example.com/path", #{"Accept": "text/html"}, "")
print(raw)
Build a raw HTTP response string
Constructs a raw HTTP/1.1 response string. Useful for testing or building a simple server.
use plugin http::{build_response}
let raw = build_response(200, "OK", #{"Content-Type": "text/plain"}, "Hello!")
print(raw)
Parse an HTTP request line
Parses an HTTP request line (e.g. "GET /path HTTP/1.1") into {method, path, version}.
use plugin http::{parse_request_line}
let parts = parse_request_line("POST /submit HTTP/1.1")
print(parts["method"])
print(parts["path"])
Parse an HTTP status line
Parses an HTTP status line (e.g. "HTTP/1.1 200 OK") into {version, status, reason}.
use plugin http::{parse_status_line}
let parts = parse_status_line("HTTP/1.1 404 Not Found")
print(parts["status"])
print(parts["reason"])
Parse raw HTTP headers into a table
Parses a block of raw HTTP headers (newline-separated Name: Value lines) into a string-keyed table.
use plugin http::{parse_headers}
let raw = "Content-Type: application/json\r\nX-Request-Id: abc123"
let headers = parse_headers(raw)
print(headers["Content-Type"])
Parse a URL into its components
Splits a URL into its components: {scheme, host, port, path, query, fragment}.
use plugin http::{parse_url}
let parts = parse_url("https://example.com:8080/search?q=hello#results")
print(parts["host"])
print(parts["path"])
print(parts["query"])
Feed the query component straight into parse_query_string to read the params:
use plugin http::{parse_url, parse_query_string}
let parts = parse_url("http://example.com/search?q=cats&page=2")
let params = parse_query_string(parts["query"])
print(params["q"])
print("port: {parts["port"]}")
Build a URL-encoded query string
Encodes a table of key-value pairs into a percent-encoded URL query string. Integer, number, and boolean values are stringified automatically, so you do not have to convert them yourself.
use plugin http::{build_query_string}
let qs = build_query_string(#{"q": "hello world", "page": "2"})
print(qs)
Mixed value types are coerced to strings during encoding:
use plugin http::{build_query_string}
let qs = build_query_string(#{"page": 2, "limit": 50, "active": true})
print(qs)
Parse a query string into a table
Parses a URL query string (with or without leading ?) into a table of decoded key-value pairs.
use plugin http::{parse_query_string}
let params = parse_query_string("q=hello+world&page=2")
print(params["q"])
print(params["page"])
Get MIME type for a file extension
Returns the MIME type string for a file extension. Falls back to application/octet-stream for unknown extensions.
)%0Aprint(content_type_for(%22.png%22))%0Aprint(content_type_for(%22wasm%22))){kind=link}
use plugin http::{content_type_for}
print(content_type_for("json"))
print(content_type_for(".png"))
print(content_type_for("wasm"))
Get reason phrase for an HTTP status code
Returns the standard HTTP reason phrase for a status code, or "Unknown" for unrecognized codes.
use plugin http::{status_text}
print(status_text(200))
print(status_text(404))
print(status_text(503))
Percent-encode a string
Percent-encodes a string for safe inclusion in a URL component. Unreserved characters (A-Z, a-z, 0-9, -, _, ., ~) are left unchanged.
use plugin http::{url_encode}
let encoded = url_encode("hello world & more")
print(encoded)
Percent-decode a string
Decodes a percent-encoded URL component string. + is decoded to a space.
use plugin http::{url_decode}
let decoded = url_decode("hello%20world%20%26%20more")
print(decoded)
Build a full URL from base, path, and params
Combines a base URL, a path, and an optional query params table into a complete URL string.
use plugin http::{build_url}
let url = build_url("https://api.example.com", "/search", #{"q": "cats", "limit": "10"})
print(url)
The query params table is optional — omit it to just join a base and path, with the leading/trailing slashes normalized for you:
use plugin http::{build_url}
print(build_url("http://example.com/", "users"))