type content_mode[link]

type content_mode = enum {
	AUTO = 0,
	NONE,

};

Configures the Content-Encoding behavior.

If set to NONE, no transport decoding or encoding is performed on the message body, irrespective of the value of the Content-Encoding header. The user must perform any required encoding or decoding themselves in this mode. If set to AUTO, the implementation will examine the Content-Encoding header and encode the message body appropriately.

Most users will want this to be set to AUTO.

TODO: Document server behavior

type header[link]

type header = [](str, str);

List of HTTP headers. TODO: [](str, []str)

type request[link]

type request = struct {
	// HTTP request method, e.g. GET
	method: str,
	// Request target URI.
	//
	// Note that the normal constraints for [[uri::parse]] are not upheld in
	// the case of a request using the origin-form (e.g. /index.html), i.e.
	// the scheme field may be empty.
	target: *uri::uri,
	// List of HTTP request headers.
	header: header,
	// Transport configuration, or null to use the [[client]] default.
	transport: nullable *transport,
	// I/O reader for the request body, or void if there is no body.
	body: (io::handle | void),
};

Stores state related to an HTTP request.

For a request to be processable by an HTTP client, i.e. via do, the method and target must be filled in appropriately. The target must include at least a host, port, and scheme. The default values for other fields are suitable if appropriate for the request you wish to perform.

type response[link]

type response = struct {
	// HTTP protocol version (major, minor)
	version: (uint, uint),
	// The HTTP status for this request as an integer.
	status: uint,
	// The HTTP status reason phrase.
	reason: str,
	// The HTTP headers provided by the server.
	header: header,
	// The response body, if any.
	body: nullable *io::stream,
};

Stores state related to an HTTP response.

type transport[link]

type transport = struct {
	// Desired Transport-Encoding configuration, see [[transport_mode]] for
	// details.
	request_transport: transport_mode,
	response_transport: transport_mode,
	// Desired Content-Encoding configuration, see [[content_mode]] for
	// details.
	request_content: content_mode,
	response_content: content_mode,
};

Describes an HTTP client's transport configuration for a given request.

The default value of this type sets all parameters to "auto".

type transport_mode[link]

type transport_mode = enum {
	AUTO = 0,
	NONE,

};

Configures the Transport-Encoding behavior.

If set to NONE, no transport decoding or encoding is performed on the message body, irrespective of the value of the Transport-Encoding header. The user must perform any required encoding or decoding themselves in this mode. If set to AUTO, the implementation will examine the Transport-Encoding header and encode the message body appropriately.

Most users will want this to be set to auto.

TODO: Document server behavior

type chunked_reader[link]

type chunked_reader = struct {
	vtable: io::stream,
	conn: io::handle,
	buffer: [os::BUFSIZ]u8,
	pending: size,
};

type client[link]

type client = struct {
	default_header: header,
	default_transport: transport,
};

type identity_reader[link]

type identity_reader = struct {
	vtable: io::stream,
	conn: io::handle,
	buffer: [os::BUFSIZ]u8,
	pending: size,
	length: size,
};

type error[link]

type error = !(dial::error | io::error | errors::unsupported | protoerr);

Errors possible while servicing HTTP requests. Note that these errors are for errors related to the processing of the HTTP connection; semantic HTTP errors such as STATUS_NOTFOUND are not handled by this type.

type httperror[link]

type httperror = !uint;

A semantic HTTP error and its status code.

type protoerr[link]

type protoerr = !void;

An HTTP protocol error occurred, indicating that the remote party is not conformant with HTTP semantics.

def DELETE[link]

def DELETE: str;

HTTP "DELETE" method.

def GET[link]

def GET: str;

HTTP "GET" method.

def HEAD[link]

def HEAD: str;

HTTP "HEAD" method.

def POST[link]

def POST: str;

HTTP "POST" method.

def PUT[link]

def PUT: str;

HTTP "PUT" method.

def STATUS_ACCEPTED[link]

def STATUS_ACCEPTED: uint;

HTTP "Accepted" response status (202).

def STATUS_BAD_GATEWAY[link]

def STATUS_BAD_GATEWAY: uint;

HTTP "Bad Gateway" response status (502).

def STATUS_BAD_REQUEST[link]

def STATUS_BAD_REQUEST: uint;

HTTP "Bad Request" response status (400).

def STATUS_CONFLICT[link]

def STATUS_CONFLICT: uint;

HTTP "Conflict" response status (409).

def STATUS_CONTINUE[link]

def STATUS_CONTINUE: uint;

HTTP "Continue" response status (100).

def STATUS_CREATED[link]

def STATUS_CREATED: uint;

HTTP "Created" response status (201).

def STATUS_EXPECTATION_FAILED[link]

def STATUS_EXPECTATION_FAILED: uint;

HTTP "Expectation Failed" response status (417).

def STATUS_FORBIDDEN[link]

def STATUS_FORBIDDEN: uint;

HTTP "Forbidden" response status (403).

def STATUS_FOUND[link]

def STATUS_FOUND: uint;

HTTP "Found" response status (302).

def STATUS_GATEWAY_TIMEOUT[link]

def STATUS_GATEWAY_TIMEOUT: uint;

HTTP "Gateway Timeout" response status (504).

def STATUS_GONE[link]

def STATUS_GONE: uint;

HTTP "Gone" response status (410).

def STATUS_HTTP_VERSION_NOT_SUPPORTED[link]

def STATUS_HTTP_VERSION_NOT_SUPPORTED: uint;

HTTP "HTTP Version Not Supported" response status (505).

def STATUS_INTERNAL_SERVER_ERROR[link]

def STATUS_INTERNAL_SERVER_ERROR: uint;

HTTP "Internal Server Error" response status (500).

def STATUS_LENGTH_REQUIRED[link]

def STATUS_LENGTH_REQUIRED: uint;

HTTP "Length Required" response status (411).

def STATUS_METHOD_NOT_ALLOWED[link]

def STATUS_METHOD_NOT_ALLOWED: uint;

HTTP "Method Not Allowed" response status (405).

def STATUS_MISDIRECTED_REQUEST[link]

def STATUS_MISDIRECTED_REQUEST: uint;

HTTP "Misdirected Request" response status (421).

def STATUS_MOVED_PERMANENTLY[link]

def STATUS_MOVED_PERMANENTLY: uint;

HTTP "Moved Permanently" response status (301).

def STATUS_MULTIPLE_CHOICES[link]

def STATUS_MULTIPLE_CHOICES: uint;

HTTP "Multiple Choices" response status (300).

def STATUS_NONAUTHORITATIVE_INFO[link]

def STATUS_NONAUTHORITATIVE_INFO: uint;

HTTP "Non-authoritative Info" response status (203).

def STATUS_NOT_ACCEPTABLE[link]

def STATUS_NOT_ACCEPTABLE: uint;

HTTP "Not Acceptable" response status (406).

def STATUS_NOT_FOUND[link]

def STATUS_NOT_FOUND: uint;

HTTP "Not Found" response status (404).

def STATUS_NOT_IMPLEMENTED[link]

def STATUS_NOT_IMPLEMENTED: uint;

HTTP "Not Implemented" response status (501).

def STATUS_NOT_MODIFIED[link]

def STATUS_NOT_MODIFIED: uint;

HTTP "Not Modified" response status (304).

def STATUS_NO_CONTENT[link]

def STATUS_NO_CONTENT: uint;

HTTP "No Content" response status (204).

def STATUS_OK[link]

def STATUS_OK: uint;

HTTP "OK" response status (200).

def STATUS_PARTIAL_CONTENT[link]

def STATUS_PARTIAL_CONTENT: uint;

HTTP "Partial Content" response status (206).

def STATUS_PAYMENT_REQUIRED[link]

def STATUS_PAYMENT_REQUIRED: uint;

HTTP "Payment Required" response status (402).

def STATUS_PERMANENT_REDIRECT[link]

def STATUS_PERMANENT_REDIRECT: uint;

HTTP "Permanent Redirect" response status (308).

def STATUS_PRECONDITION_FAILED[link]

def STATUS_PRECONDITION_FAILED: uint;

HTTP "Precondition Failed" response status (412).

def STATUS_PROXY_AUTH_REQUIRED[link]

def STATUS_PROXY_AUTH_REQUIRED: uint;

HTTP "Proxy Authentication Required" response status (407).

def STATUS_REQUESTED_RANGE_NOT_SATISFIABLE[link]

def STATUS_REQUESTED_RANGE_NOT_SATISFIABLE: uint;

HTTP "Requested Range Not Satisfiable" response status (416).

def STATUS_REQUEST_ENTITY_TOO_LARGE[link]

def STATUS_REQUEST_ENTITY_TOO_LARGE: uint;

HTTP "Request Entity Too Large" response status (413).

def STATUS_REQUEST_TIMEOUT[link]

def STATUS_REQUEST_TIMEOUT: uint;

HTTP "Request Timeout" response status (408).

def STATUS_REQUEST_URI_TOO_LONG[link]

def STATUS_REQUEST_URI_TOO_LONG: uint;

HTTP "Request URI Too Long" response status (414).

def STATUS_RESET_CONTENT[link]

def STATUS_RESET_CONTENT: uint;

HTTP "Reset Content" response status (205).

def STATUS_SEE_OTHER[link]

def STATUS_SEE_OTHER: uint;

HTTP "See Other" response status (303).

def STATUS_SERVICE_UNAVAILABLE[link]

def STATUS_SERVICE_UNAVAILABLE: uint;

HTTP "Service Unavailable" response status (503).

def STATUS_SWITCHING_PROTOCOLS[link]

def STATUS_SWITCHING_PROTOCOLS: uint;

HTTP "Switching Protocols" response status (101).

def STATUS_TEAPOT[link]

def STATUS_TEAPOT: uint;

HTTP "I'm a Teapot" response status (418).

def STATUS_TEMPORARY_REDIRECT[link]

def STATUS_TEMPORARY_REDIRECT: uint;

HTTP "Temporary Redirect" response status (307).

def STATUS_UNAUTHORIZED[link]

def STATUS_UNAUTHORIZED: uint;

HTTP "Unauthorized" response status (401).

def STATUS_UNPROCESSABLE_ENTITY[link]

def STATUS_UNPROCESSABLE_ENTITY: uint;

HTTP "Unprocessable Entity" response status (422).

def STATUS_UNSUPPORTED_MEDIA_TYPE[link]

def STATUS_UNSUPPORTED_MEDIA_TYPE: uint;

HTTP "Unsupported Media Type" response status (415).

def STATUS_UPGRADE_REQUIRED[link]

def STATUS_UPGRADE_REQUIRED: uint;

HTTP "Upgrade Required" response status (426).

def STATUS_USE_PROXY[link]

def STATUS_USE_PROXY: uint;

HTTP "Use Proxy" response status (305).

fn check[link]

fn check(status: uint) (uint | httperror);

Checks if an HTTP status code is semantically considered an error, returning httperror if so, or otherwise returning the original status code.

fn client_default_header[link]

fn client_default_header(client: *client) *header;

Returns the default headers used by this HTTP client, so that the user can examine or modify the net::http defaults (such as User-Agent or Accept-Encoding), or add their own.

fn client_default_transport[link]

fn client_default_transport(client: *client) *transport;

Returns the default transport configuration used by this HTTP client.

fn client_finish[link]

fn client_finish(client: *client) void;

Frees resources associated with an HTTP client.

fn do[link]

fn do(client: *client, req: *request) (response | error);

Performs an HTTP request with the given client. The request is performed synchronously; this function blocks until the server has returned the response status and all HTTP headers associated with the response.

fn get[link]

fn get(client: *client, target: *uri::uri) (response | error);

Performs a synchronous HTTP GET request with the given client.

fn head[link]

fn head(client: *client, target: *uri::uri) (response | error);

Performs a synchronous HTTP HEAD request with the given client.

fn header_add[link]

fn header_add(head: *header, name: str, val: str) void;

Adds a given HTTP header, which may be added more than once. The name should be canonicalized by the caller.

fn header_del[link]

fn header_del(head: *header, name: str) void;

Removes an HTTP header from a list of header. If multiple headers match the given name, all matching headers are removed.

fn header_dup[link]

fn header_dup(head: *header) header;

Duplicates a set of HTTP headers.

fn header_free[link]

fn header_free(head: *header) void;

Frees state associated with an HTTP header.

fn header_get[link]

fn header_get(head: *header, name: str) str;

Retrieves a value, or values, from a header. An empty string indicates the absence of a header.

fn header_set[link]

fn header_set(head: *header, name: str, val: str) void;

Sets the value of a given HTTP header, removing any previous values. The name should be canonicalized by the caller.

fn newclient[link]

fn newclient(ua: str) client;

Creates a new HTTP client with the provided User-Agent string.

The HTTP client implements a number of sane defaults, which may be tuned. The set of default headers is configured with client_default_header, and the default transport behavior with client_default_transport.

TODO: Implement and document the connection pool

The caller must pass the client object to client_finish to free resources associated with this client after use.

fn post[link]

fn post(
	client: *client,
	target: *uri::uri,
	body: io::handle,
) (response | error);

Performs a synchronous HTTP POST request with the given client.

If the provided I/O handle is seekable, the Content-Length header is added automatically. Otherwise, Transfer-Encoding: chunked will be used.

fn put[link]

fn put(
	client: *client,
	target: *uri::uri,
	body: io::handle,
) (response | error);

Performs a synchronous HTTP PUT request with the given client.

If the provided I/O handle is seekable, the Content-Length header is added automatically. Otherwise, Transfer-Encoding: chunked will be used.

fn request_finish[link]

fn request_finish(req: *request) void;

Frees state associated with an HTTP request.

fn response_finish[link]

fn response_finish(resp: *response) void;

Frees state associated with an HTTP response.

fn status_reason[link]

fn status_reason(status: uint) const str;

Converts a standard HTTP status code into the reason text typically associated with this status code (or "Unknown Status" if the status code is not known to net::http).

fn strerror[link]

fn strerror(err: error) const str;

Converts an error to a string.

fn write_header[link]

fn write_header(sink: io::handle, head: *header) (size | io::error);

Writes a list of HTTP headers to the provided I/O handle in the HTTP wire format.