std.http: curated error sets and custom Headers

[truemedian]

std.http.Client now has a set of curated errors that are higher level than the raw socket errors.

std.http.Headers added, adapted from daurnimator's work on the now orphaned std.http.Headers.

• http/2 compatibility removed as it's not important for http/1

Fixes #15295

std.http.Client

var client = std.http.Client{
    .allocator = gpa,
    // .proxy = .{
    //     .protocol = .plain,
    //     .host = "127.0.0.1",
    //     .port = 8080, // optional, defaults to 80 (plain) or 443 (tls)
    //     .auth = "Basic dXNlcm5hbWU6cGFzc3dvcmQ=", // optional
    // },
};
defer client.deinit();

const uri = std.Uri.parse("https://example.com") catch unreachable;

var h = std.http.Headers{ .allocator = gpa };
defer h.deinit();

try h.append("Content-Type", "text/plain");
// The following headers are sent as defaults if not provided:
// Host: {uri.host}
// User-Agent: zig/{zig_version_string} (std.http)
// Connection: keep-alive
// Accept-Encoding: gzip, deflate, zstd
// TE: gzip, deflate, trailers
//
// and depending on `req.transfer_encoding` either:
// Transfer-Encoding: chunked
// or
// Content-Length: {content_length}
//
// If either of these headers are provided, `req.transfer_encoding` will be set to their value.

var header_buf: [8192]u8 = undefined;
var req = try client.request(.POST, uri, h, .{
    .header_strategy = .{ .static = &header_buf }, // use a buffer for headers
    // .header_strategy = .{ .dynamic =  8 * 1024 }, // or use an allocator (the default, max=16KB)
    // .handle_redirects = true, // optional, defaults to true
    // .max_redirects = 69, // optional, defaults to 3
});
defer req.deinit();

// req.transfer_encoding = .chunked; // don't know how much data you're going to send
req.transfer_encoding = .{ .content_length = 14 }; // this will be checked to ensure you sent exactly 14 bytes

try req.start(); // this sends the request

try req.writeAll("Hello, ");
try req.writeAll("World!\n");
try req.finish();

try req.do(); // this waits for a response

const reader = req.reader();

const body = try reader.readAllAlloc(gpa, 8192 * 1024);
defer gpa.free(body);

std.http.Server

var server = Server.init(gpa, .{ .reuse_address = true });
defer server.deinit();

try server.listen(try net.Address.parseIp("127.0.0.1", 8081));

while (true) {
    var buf: [8192]u8 = undefined;
    const res = try server.accept(.{ .static = &buf });// use a buffer for headers
    // const res = try server.accept(.{ .dynamic = 8192 }); // or use the server's allocator

    handler(res) catch {};
}

...

fn handler(res: *Server.Response) !void {
    while (true) { // handle keepalive connections
        defer res.reset();

        try res.wait(); // this waits for the request

        const body = try res.reader().readAllAlloc(gpa, 4096);
        defer allocator.free(body);

        try res.headers.append("content-type", "text/plain");
        // The following headers are sent as defaults if not provided:
        // Server: zig (std.http)
        // Connection: keep-alive
        //
        // and depending on `res.transfer_encoding` either:
        // Transfer-Encoding: chunked
        // or
        // Content-Length: {content_length}
        //
        // If either of these headers are provided, `res.transfer_encoding` will be set to their value.

        try res.headers.append("connection", "close"); // this example is single threaded, give everyone else a chance to connect

        std.debug.print("{} {s}\n", .{ res.request.method, res.request.target });

        res.transfer_encoding = .{ .content_length = 14 };
        try res.do(); // this sends the response
        try res.writer().writeAll("Hello, World!\n");
        try res.finish();

        if (res.connection.conn.closing) break;
    }
}

[nwtgck]

@truemedian Thanks! Could you give me your opinion on renaming HeaderEntry → Field? In my comprehension of HTTP sematics, field might be more proper concept for that. In the future, trailer definition also may use Field.
https://httpwg.org/specs/rfc9110.html#fields

cons: Most of developers are familiar with "header". So it is not easy to find or understand what it is.

[truemedian]

In my comprehension of HTTP sematics, field might be more proper concept for that.

You'd be right, HeaderEntry is not how HTTP ever describes headers. I'll change that to Field, it's definitely more correct.

[nwtgck]

Thank you for the first comment in the issue. Now I understand why handler has while loop: while (true) { // handle keepalive connections. I guess it will be helpful to handle request in low-level and used for 1xx interim response.

[andrewrk]

Great work.

Now that there are both client and server APIs, can there be some unit tests for them?

[andrewrk]

This @constCast does not belong here.

[truemedian]

I think the reason it gets used here is that the Field might point at non-mutable memory (so value needs to be []const u8), but it also might point to allocator owned memory. This is currently dead code, so for now I'm going to just remove this whole thing, it probably needs to be in Headers anyway.