Something went wrong. Try again.
An HTTP library for Zig 0.17, server and client, HTTP/1.0 through HTTP/3, with the protocol in a module that owns no socket.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
//! A response that arrived, which is what a caller reads.//!//! The mirror of `server.Response` and the same shape seen from the other//! side: a status, fields, and a body whose transfer coding has already been//! taken off. There is no way to ask whether it arrived chunked, for the same//! reason there is no way to ask on the server side -- that is framing, and a//! caller that branches on it is a caller that will behave differently//! against two servers saying the same thing.//!//! **Every slice in a response points into the connection it came from.**//!//! The status line's reason phrase, every field name and every field value//! are slices of the buffer the head was read into, which the connection owns//! and reuses for the next exchange. So a response is valid until the next//! `send` on that connection, or until the connection is deinitialized,//! whichever comes first -- and anything that has to outlive either must be//! copied.//!//! Borrowing rather than copying is the same decision the server side makes//! about a request, and for the same reason: a response head is read once,//! and duplicating every field so that a caller *might* keep one would make//! every caller pay for the few that do.
const std = @import("std");const Io = std.Io;const Allocator = std.mem.Allocator;
const protocol = @import("../protocol.zig");
const Headers = protocol.Headers;const Status = protocol.Status;const Version = protocol.Version;
const Response = @This();
/// The status code as it arrived, which may be one nothing has a name for:/// §15 of RFC 9110 has a recipient understand the class of an unrecognised/// code rather than refuse it.status: u16,/// The version the server answered in, which is not necessarily the one the/// request was sent in.version: Version,/// §4 of RFC 9112: carried because it arrived, and never acted on. "A client/// SHOULD ignore the reason-phrase content."reason: []const u8,headers: Headers,body: Body,/// Whether the request's content went out. Always true unless the request/// asked for `expect_continue` and the server answered with a final response/// before asking for it -- in which case none of it did, and the request can/// be sent again, somewhere else or with different credentials, with the/// content still unread.content_sent: bool = true,
/// The response body, already decoded.pub const Body = struct { reader: *Io.Reader, /// How long the body is, when the message said. Null for a chunked body /// and for one that runs until the connection closes. length: ?u64, /// Whether there is a body at all. A `204`, a `304` and any response to /// `HEAD` have none, whatever their fields claim. present: bool,
pub const empty_reader: *Io.Reader = Io.Reader.ending;
pub const ReadError = Io.Reader.LimitedAllocError;
/// Reads the whole body into memory, refusing to read more than `limit`. /// /// The limit is not optional, and there is no overload without one. A /// body that runs until the connection closes is whatever the server /// decides to send, and a client that reads it into memory until it stops /// is a client any server can exhaust. /// /// A body longer than `limit` is `error.StreamTooLong`. A response with /// no body reads as an empty slice without touching the reader. Either /// way what comes back is the caller's, to free with `gpa`. pub fn readAlloc(b: Body, gpa: Allocator, limit: usize) ReadError![]u8 { if (!b.present) return gpa.alloc(u8, 0); return b.reader.allocRemaining(gpa, .limited(limit)); }
test readAlloc { var reader: Io.Reader = .fixed("hello"); const body: Body = .{ .reader = &reader, .length = 5, .present = true }; const got = try body.readAlloc(std.testing.allocator, 1024); defer std.testing.allocator.free(got); try std.testing.expectEqualStrings("hello", got);
var again: Io.Reader = .fixed("hello"); const long: Body = .{ .reader = &again, .length = 5, .present = true }; try std.testing.expectError(error.StreamTooLong, long.readAlloc(std.testing.allocator, 4)); }};
/// A response with `status`, no fields and no body, for the examples below.fn testResponse(status: u16) Response { return .{ .status = status, .version = .http_1_1, .reason = "", .headers = .empty, .body = .{ .reader = Body.empty_reader, .length = 0, .present = false }, };}
/// The value of the first field with this name, or null. Names are compared/// without regard to case.pub fn header(r: *const Response, name: []const u8) ?[]const u8 { return r.headers.get(name);}
test header { var r = testResponse(200); defer r.headers.deinit(std.testing.allocator); try r.headers.append(std.testing.allocator, "content-type", "text/plain");
try std.testing.expectEqualStrings("text/plain", r.header("Content-Type").?); try std.testing.expect(r.header("location") == null);}
/// The class of the status, which is what §15 of RFC 9110 has a client act/// on when it does not recognise the code itself.pub fn class(r: *const Response) Class { return switch (r.status / 100) { 1 => .informational, 2 => .successful, 3 => .redirection, 4 => .client_error, 5 => .server_error, else => .unknown, };}
test class { try std.testing.expectEqual(Class.redirection, testResponse(301).class()); // §15: an unrecognized code is understood by its class. try std.testing.expectEqual(Class.client_error, testResponse(499).class()); try std.testing.expectEqual(Class.unknown, testResponse(99).class());}
pub const Class = enum { informational, successful, redirection, client_error, server_error, /// §15: a code outside 100..599 names no class. It is carried rather than /// refused, because refusing it would make this library the thing that /// broke rather than the server that sent it. unknown,};
/// Whether the status is one a caller would treat as success: any 2xx.pub fn isOk(r: *const Response) bool { return r.class() == .successful;}
test isOk { try std.testing.expect(testResponse(204).isOk()); try std.testing.expect(!testResponse(404).isOk()); // A redirect is not success until it has been followed. try std.testing.expect(!testResponse(302).isOk());}
const testing = std.testing;
test "the class of a status is what an unrecognised code is acted on by" { // §15 of RFC 9110: "a client MUST understand the class of any status // code, as indicated by the first digit, and treat an unrecognized status // code as being equivalent to the x00 status code of that class". var headers: Headers = .empty; const r: Response = .{ .status = 299, .version = .http_1_1, .reason = "", .headers = headers, .body = .{ .reader = Body.empty_reader, .length = 0, .present = false }, }; try testing.expectEqual(Class.successful, r.class()); try testing.expect(r.isOk());
var teapot = r; teapot.status = 418; try testing.expectEqual(Class.client_error, teapot.class()); try testing.expect(!teapot.isOk());
// Outside every class, carried rather than refused. var nonsense = r; nonsense.status = 799; try testing.expectEqual(Class.unknown, nonsense.class());
headers.deinit(testing.allocator);}