net::http
net::http provides an implementation of an HTTP 1.1 client and server as defined
by RFC 7230 et al.
TODO: Flesh me out
Caveats:
- No attempt is made to validate that the input for client requests or responses
are valid according to the HTTP grammar; such cases will fail when rejected by
the other party.
- Details indicated by RFC 7230 et al as "obsolete" are not implemented
- Max header length including "name: value" is 4KiB
TODO:
Index
Types
type content_mode;
type header;
type request;
type response;
type transport;
type transport_mode;
type chunked_reader;
type client;
type identity_reader;
Errors
type error;
type httperror;
type protoerr;
Constants
const DELETE: str;
const GET: str;
const HEAD: str;
const POST: str;
const PUT: str;
const STATUS_ACCEPTED: uint;
const STATUS_BAD_GATEWAY: uint;
const STATUS_BAD_REQUEST: uint;
const STATUS_CONFLICT: uint;
const STATUS_CONTINUE: uint;
const STATUS_CREATED: uint;
const STATUS_EXPECTATION_FAILED: uint;
const STATUS_FORBIDDEN: uint;
const STATUS_FOUND: uint;
const STATUS_GATEWAY_TIMEOUT: uint;
const STATUS_GONE: uint;
const STATUS_HTTP_VERSION_NOT_SUPPORTED: uint;
const STATUS_INTERNAL_SERVER_ERROR: uint;
const STATUS_LENGTH_REQUIRED: uint;
const STATUS_METHOD_NOT_ALLOWED: uint;
const STATUS_MISDIRECTED_REQUEST: uint;
const STATUS_MOVED_PERMANENTLY: uint;
const STATUS_MULTIPLE_CHOICES: uint;
const STATUS_NONAUTHORITATIVE_INFO: uint;
const STATUS_NOT_ACCEPTABLE: uint;
const STATUS_NOT_FOUND: uint;
const STATUS_NOT_IMPLEMENTED: uint;
const STATUS_NOT_MODIFIED: uint;
const STATUS_NO_CONTENT: uint;
const STATUS_OK: uint;
const STATUS_PARTIAL_CONTENT: uint;
const STATUS_PAYMENT_REQUIRED: uint;
const STATUS_PERMANENT_REDIRECT: uint;
const STATUS_PRECONDITION_FAILED: uint;
const STATUS_PROXY_AUTH_REQUIRED: uint;
const STATUS_REQUESTED_RANGE_NOT_SATISFIABLE: uint;
const STATUS_REQUEST_ENTITY_TOO_LARGE: uint;
const STATUS_REQUEST_TIMEOUT: uint;
const STATUS_REQUEST_URI_TOO_LONG: uint;
const STATUS_RESET_CONTENT: uint;
const STATUS_SEE_OTHER: uint;
const STATUS_SERVICE_UNAVAILABLE: uint;
const STATUS_SWITCHING_PROTOCOLS: uint;
const STATUS_TEAPOT: uint;
const STATUS_TEMPORARY_REDIRECT: uint;
const STATUS_UNAUTHORIZED: uint;
const STATUS_UNPROCESSABLE_ENTITY: uint;
const STATUS_UNSUPPORTED_MEDIA_TYPE: uint;
const STATUS_UPGRADE_REQUIRED: uint;
const STATUS_USE_PROXY: uint;
Functions
fn check(uint) (uint | httperror);
fn client_default_header(*client) *header;
fn client_default_transport(*client) *transport;
fn client_finish(*client) void;
fn do(*client, *request) (response | error);
fn get(*client, *uri::uri) (response | error);
fn head(*client, *uri::uri) (response | error);
fn header_add(*header, str, str) void;
fn header_del(*header, str) void;
fn header_dup(*header) header;
fn header_free(*header) void;
fn header_get(*header, str) str;
fn header_set(*header, str, str) void;
fn newclient(str) client;
fn post(*client, *uri::uri, io::handle) (response | error);
fn put(*client, *uri::uri, io::handle) (response | error);
fn request_finish(*request) void;
fn response_finish(*response) void;
fn status_reason(uint) const str;
fn strerror(error) const str;
fn write_header(io::handle, *header) (size | io::error);
Types
type content_mode
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 = [](str, str);
List of HTTP headers.
TODO: [](str, []str)
type request
type request = struct {
method: str,
target: *uri::uri,
header: header,
transport: nullable *transport,
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
type response = struct {
version: (uint, uint),
status: uint,
reason: str,
header: header,
body: nullable *io::stream,
};
Stores state related to an HTTP response.
type transport
type transport = struct {
request_transport: transport_mode,
response_transport: transport_mode,
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
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
Show undocumented member
type chunked_reader = struct {
vtable: io::stream,
conn: io::handle,
buffer: [os::BUFSIZ]u8,
pending: size,
};
type client
Show undocumented member
type client = struct {
default_header: header,
default_transport: transport,
};
type identity_reader
Show undocumented member
type identity_reader = struct {
vtable: io::stream,
conn: io::handle,
buffer: [os::BUFSIZ]u8,
pending: size,
length: size,
};
Errors
type error
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
type httperror = !uint;
A semantic HTTP error and its status code.
type protoerr
type protoerr = !void;
An HTTP protocol error occurred, indicating that the remote party is not
conformant with HTTP semantics.
Constants
def DELETE
def DELETE: str;
HTTP "DELETE" method.
def GET
def GET: str;
HTTP "GET" method.
def HEAD
def HEAD: str;
HTTP "HEAD" method.
def POST
def POST: str;
HTTP "POST" method.
def PUT
def PUT: str;
HTTP "PUT" method.
def STATUS_ACCEPTED
def STATUS_ACCEPTED: uint;
HTTP "Accepted" response status (202).
def STATUS_BAD_GATEWAY
def STATUS_BAD_GATEWAY: uint;
HTTP "Bad Gateway" response status (502).
def STATUS_BAD_REQUEST
def STATUS_BAD_REQUEST: uint;
HTTP "Bad Request" response status (400).
def STATUS_CONFLICT
def STATUS_CONFLICT: uint;
HTTP "Conflict" response status (409).
def STATUS_CONTINUE
def STATUS_CONTINUE: uint;
HTTP "Continue" response status (100).
def STATUS_CREATED
def STATUS_CREATED: uint;
HTTP "Created" response status (201).
def STATUS_EXPECTATION_FAILED
def STATUS_EXPECTATION_FAILED: uint;
HTTP "Expectation Failed" response status (417).
def STATUS_FORBIDDEN
def STATUS_FORBIDDEN: uint;
HTTP "Forbidden" response status (403).
def STATUS_FOUND
def STATUS_FOUND: uint;
HTTP "Found" response status (302).
def STATUS_GATEWAY_TIMEOUT
def STATUS_GATEWAY_TIMEOUT: uint;
HTTP "Gateway Timeout" response status (504).
def STATUS_GONE
def STATUS_GONE: uint;
HTTP "Gone" response status (410).
def STATUS_HTTP_VERSION_NOT_SUPPORTED
def STATUS_HTTP_VERSION_NOT_SUPPORTED: uint;
HTTP "HTTP Version Not Supported" response status (505).
def STATUS_INTERNAL_SERVER_ERROR
def STATUS_INTERNAL_SERVER_ERROR: uint;
HTTP "Internal Server Error" response status (500).
def STATUS_LENGTH_REQUIRED
def STATUS_LENGTH_REQUIRED: uint;
HTTP "Length Required" response status (411).
def STATUS_METHOD_NOT_ALLOWED
def STATUS_METHOD_NOT_ALLOWED: uint;
HTTP "Method Not Allowed" response status (405).
def STATUS_MISDIRECTED_REQUEST
def STATUS_MISDIRECTED_REQUEST: uint;
HTTP "Misdirected Request" response status (421).
def STATUS_MOVED_PERMANENTLY
def STATUS_MOVED_PERMANENTLY: uint;
HTTP "Moved Permanently" response status (301).
def STATUS_MULTIPLE_CHOICES
def STATUS_MULTIPLE_CHOICES: uint;
HTTP "Multiple Choices" response status (300).
def STATUS_NONAUTHORITATIVE_INFO
def STATUS_NONAUTHORITATIVE_INFO: uint;
HTTP "Non-authoritative Info" response status (203).
def STATUS_NOT_ACCEPTABLE
def STATUS_NOT_ACCEPTABLE: uint;
HTTP "Not Acceptable" response status (406).
def STATUS_NOT_FOUND
def STATUS_NOT_FOUND: uint;
HTTP "Not Found" response status (404).
def STATUS_NOT_IMPLEMENTED
def STATUS_NOT_IMPLEMENTED: uint;
HTTP "Not Implemented" response status (501).
def STATUS_NOT_MODIFIED
def STATUS_NOT_MODIFIED: uint;
HTTP "Not Modified" response status (304).
def STATUS_NO_CONTENT
def STATUS_NO_CONTENT: uint;
HTTP "No Content" response status (204).
def STATUS_OK
def STATUS_OK: uint;
HTTP "OK" response status (200).
def STATUS_PARTIAL_CONTENT
def STATUS_PARTIAL_CONTENT: uint;
HTTP "Partial Content" response status (206).
def STATUS_PAYMENT_REQUIRED
def STATUS_PAYMENT_REQUIRED: uint;
HTTP "Payment Required" response status (402).
def STATUS_PERMANENT_REDIRECT
def STATUS_PERMANENT_REDIRECT: uint;
HTTP "Permanent Redirect" response status (308).
def STATUS_PRECONDITION_FAILED
def STATUS_PRECONDITION_FAILED: uint;
HTTP "Precondition Failed" response status (412).
def STATUS_PROXY_AUTH_REQUIRED
def STATUS_PROXY_AUTH_REQUIRED: uint;
HTTP "Proxy Authentication Required" response status (407).
def STATUS_REQUESTED_RANGE_NOT_SATISFIABLE
def STATUS_REQUESTED_RANGE_NOT_SATISFIABLE: uint;
HTTP "Requested Range Not Satisfiable" response status (416).
def STATUS_REQUEST_ENTITY_TOO_LARGE
def STATUS_REQUEST_ENTITY_TOO_LARGE: uint;
HTTP "Request Entity Too Large" response status (413).
def STATUS_REQUEST_TIMEOUT
def STATUS_REQUEST_TIMEOUT: uint;
HTTP "Request Timeout" response status (408).
def STATUS_REQUEST_URI_TOO_LONG
def STATUS_REQUEST_URI_TOO_LONG: uint;
HTTP "Request URI Too Long" response status (414).
def STATUS_RESET_CONTENT
def STATUS_RESET_CONTENT: uint;
HTTP "Reset Content" response status (205).
def STATUS_SEE_OTHER
def STATUS_SEE_OTHER: uint;
HTTP "See Other" response status (303).
def STATUS_SERVICE_UNAVAILABLE
def STATUS_SERVICE_UNAVAILABLE: uint;
HTTP "Service Unavailable" response status (503).
def STATUS_SWITCHING_PROTOCOLS
def STATUS_SWITCHING_PROTOCOLS: uint;
HTTP "Switching Protocols" response status (101).
def STATUS_TEAPOT
def STATUS_TEAPOT: uint;
HTTP "I'm a Teapot" response status (418).
def STATUS_TEMPORARY_REDIRECT
def STATUS_TEMPORARY_REDIRECT: uint;
HTTP "Temporary Redirect" response status (307).
def STATUS_UNAUTHORIZED
def STATUS_UNAUTHORIZED: uint;
HTTP "Unauthorized" response status (401).
def STATUS_UNPROCESSABLE_ENTITY
def STATUS_UNPROCESSABLE_ENTITY: uint;
HTTP "Unprocessable Entity" response status (422).
def STATUS_UNSUPPORTED_MEDIA_TYPE: uint;
HTTP "Unsupported Media Type" response status (415).
def STATUS_UPGRADE_REQUIRED
def STATUS_UPGRADE_REQUIRED: uint;
HTTP "Upgrade Required" response status (426).
def STATUS_USE_PROXY
def STATUS_USE_PROXY: uint;
HTTP "Use Proxy" response status (305).
Functions
fn check
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(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
fn client_default_transport(client: *client) *transport;
Returns the default transport configuration used by this HTTP client.
fn client_finish
fn client_finish(client: *client) void;
Frees resources associated with an HTTP client.
fn do
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
fn get(client: *client, target: *uri::uri) (response | error);
Performs a synchronous HTTP GET request with the given client.
fn head
fn head(client: *client, target: *uri::uri) (response | error);
Performs a synchronous HTTP HEAD request with the given client.
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(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(head: *header) header;
Duplicates a set of HTTP headers.
fn header_free(head: *header) void;
Frees state associated with an HTTP header.
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(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
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
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
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
fn request_finish(req: *request) void;
Frees state associated with an HTTP request.
fn response_finish
fn response_finish(resp: *response) void;
Frees state associated with an HTTP response.
fn status_reason
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
fn strerror(err: error) const str;
Converts an error to a string.
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.