Standard Library

class HttpRequest

An HTTP request as seen by a server: the request line, the headers and the body.

since 0.1.0-alpha.1linuxwindowswasm

Overview

A request is filled in either from a complete text with parse, or piece by piece with feed as the bytes arrive from the network. HttpServer does the second for you and hands your handler a finished request, so inside a handler you only read its fields. The headers are available once the head has been read; before that headers is not set, so call header only on a request that has been parsed or whose feed has returned true.

Examples

Parsing a request

HttpRequest req = HttpRequest();
req.parse("POST /submit?x=1 HTTP/1.1\r\nHost: example.com\r\nContent-Length: 5\r\n\r\nhello");
console.writeln(req.method);
console.writeln(req.path);
console.writeln(req.body);
console.writeln(req.header("host"));

POST
/submit?x=1
hello
example.com

Fields

body

string body

The request body as text; empty when the request has none.

complete

bool complete

Becomes true when feed has received the whole request, headers and body.

headers

HeaderMap headers

The request headers. Set once the head has been parsed.

method

string method

The request method, such as GET or POST.

path

string path

The request target exactly as sent, including any query string (/search?q=x).

version

string version

The protocol version from the request line, such as HTTP/1.1.

Methods

feed

feed(string chunk) -> bool

Gives the request the next piece of received text, and tells whether the request is now complete.

Pieces may be of any size and may end anywhere. The request is complete once the headers have been read and as many body characters as Content-Length announces have arrived; a request without Content-Length has an empty body. Text that arrives after the request is complete is dropped, because one connection handles one request at a time. Once complete, further calls return true and change nothing.

Parameters

chunk

The next piece of the request, exactly as received.

Returns

true when the whole request has been received, false while more is needed.

Examples

Feeding a request in three pieces

HttpRequest req = HttpRequest();
console.writeln(req.feed("GET /index.html HTTP/1.1\r\nHost: exa"));
console.writeln(req.feed("mple.com\r\nContent-Length: 4\r\n\r\nab"));
console.writeln(req.feed("cd"));
console.writeln(req.path);
console.writeln(req.body);
console.writeln(req.header("Host"));

false
false
true
/index.html
abcd
example.com

See also: parse

header

header(string name) -> string

Returns the value of a request header, or an empty string when the request does not have it.

The name is matched without regard to letter case. If the header appears more than once, the first value is returned; use headers.all(name) to get them all.

Parameters

name

The header name.

Returns

The first value of the header, or "".

Examples

HttpRequest req = HttpRequest();
req.parse("GET / HTTP/1.1\r\nHost: example.com\r\n\r\n");
console.writeln(req.header("HOST"));
string missing = req.header("Accept");
console.writeln(missing.isEmpty());

example.com
true

See also: all

parse

parse(string raw) -> void

Fills in the request from a complete request text.

The text is split at the first blank line. Everything before it is the request line and the headers; everything after it is taken as the body, whatever Content-Length says. A text without a blank line has an empty body. Use feed instead when the bytes arrive in pieces.

Parameters

raw

The whole request, with lines ended by a carriage return and a newline.

Examples

HttpRequest req = HttpRequest();
req.parse("GET /index.html HTTP/1.1\r\nHost: example.com\r\nAccept: text/html\r\n\r\n");
console.writeln(req.method);
console.writeln(req.path);
console.writeln(req.version);
console.writeln(req.headers.length());

GET
/index.html
HTTP/1.1
2

See also: feed

See also

• HttpResponse — An HTTP response: a status code, headers and a body.
• HttpServer — A web server that listens on a port and answers each request with a handler function.