http - HTTP Client/Server

The http module provides HTTP client and server functionality.

Interface

type Method = [`GET, `POST, `PUT, `DELETE, `PATCH, `HEAD, `OPTIONS];

type Response = {
    body: string,
    headers: Array<(string, string)>,
    status: u16,
    url: string
};

type BinResponse = {
    body: bytes,
    headers: Array<(string, string)>,
    status: u16,
    url: string
};

/// A request to a server: `body` is the body as text, null when it is
/// empty or not UTF-8; `raw` is the body as sent.
type Request = {
    body: [string, null],
    headers: Array<(string, string)>,
    method: string,
    path: string,
    query: [string, null],
    raw: bytes
};

type Client;
type Server;

/// Create a configured HTTP client.
val client: fn(
    ?#timeout: [duration, null],
    ?#default_headers: Array<(string, string)>,
    ?#redirect_limit: u32,
    ?#ca_cert: [bytes, null],
    trigger: Any
) -> Result<Client, `HTTPError(string)>;

/// Get or create a shared default HTTP client.
val default_client: fn(trigger: Any) -> Result<Client, `HTTPError(string)>;

/// Make an HTTP request and return a text response.
val request: fn(
    ?#method: Method,
    ?#headers: Array<(string, string)>,
    ?#body: [string, null],
    ?#timeout: [duration, null],
    client: Client,
    url: string
) -> Result<Response, `HTTPError(string)>;

/// Make an HTTP request and return a binary response.
val request_bin: fn(
    ?#method: Method,
    ?#headers: Array<(string, string)>,
    ?#body: [bytes, null],
    ?#timeout: [duration, null],
    client: Client,
    url: string
) -> Result<BinResponse, `HTTPError(string)>;

/// Convenience: GET request with text response.
val get: fn(client: Client, url: string) -> Result<Response, `HTTPError(string)>;

/// Convenience: GET request with binary response.
val get_bin: fn(client: Client, url: string) -> Result<BinResponse, `HTTPError(string)>;

/// Return the bound address of a running server.
val server_addr: fn(server: Server) -> string;

/// Start an HTTP server. Each request runs an instance of `#handler` of
/// its own, concurrently with the others, and is answered by that
/// instance's first value; one that raises, or that the server drops (it
/// sleeps or is deleted), is answered 500. A request its instance never
/// answers is held, with its connection and its share of
/// `#max_connections`, until the client gives up. A body over `#max_body`
/// bytes (16 MiB by default) is answered 413 without reaching the handler.
/// A connection has 30 s to send a request's headers, idle between
/// requests included, and 60 s for its body.
val serve: fn(
    #addr: string,
    ?#cert: [bytes, null],
    ?#key: [bytes, null],
    ?#max_connections: i64,
    ?#max_body: i64,
    #handler: fn(req: Request) -> Response throws 'e
) -> Result<Server, `HTTPError(string)> throws 'e;

mod rest;

http::rest

Convenience functions for JSON REST APIs with optional bearer token authentication.

use super::{Client, Method, Response, request};

/// GET with JSON Accept header and optional bearer auth.
val get: fn(
    ?#bearer: [string, null],
    ?#headers: Array<(string, string)>,
    client: Client,
    url: string
) -> Result<Response, `HTTPError(string)>;

/// POST with JSON Content-Type/Accept headers and optional bearer auth.
val post: fn(
    ?#bearer: [string, null],
    ?#headers: Array<(string, string)>,
    #body: string,
    client: Client,
    url: string
) -> Result<Response, `HTTPError(string)>;

/// PUT with JSON Content-Type/Accept headers and optional bearer auth.
val put: fn(
    ?#bearer: [string, null],
    ?#headers: Array<(string, string)>,
    #body: string,
    client: Client,
    url: string,
) -> Result<Response, `HTTPError(string)>;

/// DELETE with JSON Accept header and optional bearer auth.
val delete: fn(
    ?#bearer: [string, null],
    ?#headers: Array<(string, string)>,
    client: Client,
    url: string
) -> Result<Response, `HTTPError(string)>;

/// PATCH with JSON Content-Type/Accept headers and optional bearer auth.
val patch: fn(
    ?#bearer: [string, null],
    ?#headers: Array<(string, string)>,
    #body: string,
    client: Client,
    url: string,
) -> Result<Response, `HTTPError(string)>;