// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // 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); }