Standard Library

class HttpResponse

An HTTP response: a status code, headers and a body.

since 0.1.0-alpha.1linuxwindowswasm

Overview

A server handler builds one and returns it. render turns it into the text that goes on the wire, working out Content-Length and Connection itself. A client receives one in its callback, already parsed. For a body that is produced over time, HttpResponse::ofStream makes a streaming response whose body is written through a ChunkedSink.

Examples

Building and rendering a response

HttpResponse res = HttpResponse(404, "nope");
res.withHeader("Content-Type", "text/plain");
console.writeln(res.status);
console.writeln(res.reason());
console.writeln(res.render().replace("\r\n", "|"));

404
Not Found
HTTP/1.1 404 Not Found|Content-Length: 4|Connection: close|Content-Type: text/plain||nope

Constructors

new

new(int s, string b)

Creates a response with a status code and a body, and no headers.

Parameters

s

The status code, such as 200 or 404.

b

The response body.

Examples

HttpResponse res = HttpResponse(200, "hello");
console.writeln(res.status);
console.writeln(res.body);
console.writeln(res.headers.length());

200
hello
0

ofStream

HttpResponse::ofStream(int s, HeaderMap h, (ChunkedSink) => void writer)

Creates a streaming response whose body is written over time.

When the server sends it, the headers go out first with Transfer-Encoding: chunked; any Content-Length, Transfer-Encoding or Connection header you set is replaced by the server's own. Then writer is called with a ChunkedSink. It may write and call end straight away, or return and leave the sink open for a timer or other callback to keep writing and finally call end, as a server-sent event stream does. A HEAD request and the status codes 1xx, 204 and 304 get only the headers and the writer is not called. A request that is not HTTP/1.1 is answered with 505.

A streaming response cannot be turned into text with render.

Parameters

s

The status code.

h

The headers to send.

writer

The function that writes the body through the sink it is given.

Examples

HttpResponse res = HttpResponse::ofStream(200, HeaderMap(), (sink) => {
    sink.write("first part");
    sink.end();
});
console.writeln(res.isStreaming());
console.writeln(res.status);

true
200

See also: ChunkedSink, isStreaming

Fields

body

string body

The response body as text.

headers

HeaderMap headers

The response headers.

keepAlive

bool keepAlive

Whether render announces that the connection stays open for another request. The server sets it for you; the default is false, which sends Connection: close.

reasonText

string reasonText

The reason phrase to send after the status code. When empty, reason() supplies a standard one for common codes.

status

int status

The status code, such as 200 or 404. A response that could not be parsed has status 0.

Methods

isStreaming

isStreaming() -> bool

Tells whether this response was made with HttpResponse::ofStream.

Returns

true for a streaming response, false for an ordinary one.

Examples

HttpResponse plain = HttpResponse(200, "hello");
HttpResponse live = HttpResponse::ofStream(200, HeaderMap(), (sink) => { sink.end(); });
console.writeln(plain.isStreaming());
console.writeln(live.isStreaming());

false
true

parse

parse(string raw) -> void

Fills in the response from a complete response text.

The status code, reason phrase, headers and body are read from raw. A body sent with Transfer-Encoding: chunked is decoded, so body holds the plain text. When the status line cannot be read, status is 0. The HTTP client calls this for you before it runs your callback.

Parameters

raw

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

Examples

Parsing a chunked response

string raw = "HTTP/1.1 200 OK\r\nContent-Type: text/plain\r\nTransfer-Encoding: chunked\r\n\r\n5\r\nhello\r\n0\r\n\r\n";
HttpResponse res = HttpResponse(0, "");
res.parse(raw);
console.writeln(res.status);
console.writeln(res.reason());
console.writeln(res.body);
console.writeln(res.headers.first("content-type"));

200
OK
hello
text/plain

See also: render, ChunkedDecoder

reason

reason() -> string

Returns the reason phrase for the status code.

If reasonText is not empty it is returned. Otherwise the standard phrase is returned for 200, 201, 204, 301, 302, 304, 400, 401, 403, 404, 500 and 505. Any other code gives OK, so set reasonText yourself when you send an unusual code.

Returns

The reason phrase.

Examples

HttpResponse notFound = HttpResponse(404, "");
console.writeln(notFound.reason());
HttpResponse teapot = HttpResponse(418, "");
teapot.reasonText = "I'm a teapot";
console.writeln(teapot.reason());

Not Found
I'm a teapot

render

render() -> string

Formats the response as HTTP/1.1 text, ready to send.

The status line comes first, then Content-Length and Connection, then your other headers, a blank line and the body. Content-Length is worked out from the body and Connection from keepAlive; any header of those names, and any Transfer-Encoding header, is left out so that the computed values are the only ones.

Returns

The complete response text.

Throws

RuntimeException

when the response is a streaming one, which only the server can send.

Examples

HttpResponse res = HttpResponse(200, "hello");
res.withHeader("Content-Type", "text/plain");
res.keepAlive = true;
console.writeln(res.render().replace("\r\n", "|"));

HttpResponse live = HttpResponse::ofStream(200, HeaderMap(), (sink) => { sink.end(); });
try {
    live.render();
} catch (RuntimeException e) {
    console.writeln(e.message);
}

HTTP/1.1 200 OK|Content-Length: 5|Connection: keep-alive|Content-Type: text/plain||hello
render() called on a streaming HttpResponse

See also: parse

withHeader

withHeader(string name, string value) -> HttpResponse

Sets a header, replacing any existing header of the same name, and returns the response.

Parameters

name

The header name.

value

The header value.

Returns

This response, so calls can be chained.

Examples

HttpResponse res = HttpResponse(200, "<p>hi</p>");
res.withHeader("Content-Type", "text/html").withHeader("Cache-Control", "no-store");
res.withHeader("content-type", "text/plain");
console.writeln(res.headers.length());
console.writeln(res.headers.first("Content-Type"));

2
text/plain

See also: set

See also

• HttpRequest — An HTTP request as seen by a server: the request line, the headers and the body.
• HttpServer — A web server that listens on a port and answers each request with a handler function.
• HttpClient — A simple HTTP client that sends one request per connection and delivers the response to a callback.