Standard Library

std.http

Blocking HTTP client helpers for tool-style scripts.

Exported functions

pub def new_request(method: String, url_text: String) -> Request

Create a request with empty headers/body and no timeout override.

pub def new_request_with(method: String, url_text: String, headers: Dict[String, String], body: String, timeout_ms: Int) -> Request

Create a request with explicit headers, body, and timeout.

Examples

use http from "std.http"

const request = http.new_request_with(
  "GET", "https://example.com/", {"accept": "text/html"}, "", 5000
)
@println(request.timeout_ms) # 5000

pub def with_query(req: Request, params: Dict[String, String]) -> Request

Append query parameters to a request URL.

Examples

use http from "std.http"

const request = http.new_request("GET", "https://example.com/search")
const search = http.with_query(request, {"q": "tea"})
@println(search.url) # https://example.com/search?q=tea

pub def send(req: Request) -> Response

Send an HTTP request synchronously.

Examples

use http from "std.http"

const request = http.new_request_with(
  "GET", "https://example.com/", {"accept": "text/html"}, "", 5000
)
const response = http.check(http.send(request))
@println(response.body)

pub def get(url_text: String) -> Response

Send a GET request.

Examples

use http from "std.http"

const response = http.get("https://example.com/")
@println(response.status)
if response.ok
  @println(response.body)
end

pub def get_with(url_text: String, headers: Dict[String, String]) -> Response

Send a GET request with headers.

pub def post(url_text: String, body: String) -> Response

Send a POST request with a text body.

pub def post_with(url_text: String, headers: Dict[String, String], body: String) -> Response

Send a POST request with headers and a text body.

pub def put(url_text: String, body: String) -> Response

Send a PUT request with a text body.

pub def patch(url_text: String, body: String) -> Response

Send a PATCH request with a text body.

pub def delete(url_text: String) -> Response

Send a DELETE request.

pub def post_json[T](url_text: String, value: T) -> Response

Send a JSON POST request.

Examples

use http from "std.http"

# Requires a local API accepting POST /messages.
const response = http.post_json("http://127.0.0.1:8080/messages", {"text": "Hello, Tea!"})
@println(http.check(response).status)

pub def decode_json[T](response: Response) -> T ! json.DecodeError

Decode a JSON response body.

Examples

use http from "std.http"

# Requires a local API returning a JSON object of strings.
const response = http.check(http.get("http://127.0.0.1:8080/config"))
const config: Dict[String, String] = http.decode_json[Dict[String, String]](response)
@println(config["name"])

pub def header(response: Response, name: String) -> String?

Return a response header by name when present.

Examples

use http from "std.http"

const response = http.get("https://example.com/")
const content_type = http.header(response, "Content-Type")
@println(content_type ?? "No content type provided")

pub def header_or(response: Response, name: String, fallback: String) -> String

Return a response header by name or a fallback value.

pub def body_text(response: Response) -> String

Return the text body of a response.

pub def body_bytes(response: Response) -> List[Int]

Return the raw body bytes of a response.

pub def check(response: Response) -> Response

Fail when the response status is not successful.

Examples

use http from "std.http"

const response = http.check(http.get("https://example.com/"))
@println(response.body) # Reached only for a successful response

pub def download(url_text: String, file_path: String) -> Response ! fs.FsError

Download a URL to a file path and return the response.

use http from "std.http" const request = http.new_request("GET", "https://example.com/search") const search = http.with_query(request, {"q": "tea"}) @println(search.url) # https://example.com/search?q=tea

use http from "std.http" const request = http.new_request_with( "GET", "https://example.com/", {"accept": "text/html"}, "", 5000 ) const response = http.check(http.send(request)) @println(response.body)

use http from "std.http" # Requires a local API accepting POST /messages. const response = http.post_json("http://127.0.0.1:8080/messages", {"text": "Hello, Tea!"}) @println(http.check(response).status)

use http from "std.http" # Requires a local API returning a JSON object of strings. const response = http.check(http.get("http://127.0.0.1:8080/config")) const config: Dict[String, String] = http.decode_json[Dict[String, String]](response) @println(config["name"])