// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT //! When a server is willing to compress a response, and what it costs. //! //! The negotiation and the codec are `protocol.coding`'s and know nothing //! about servers. What is here is the policy: which representations are worth //! coding, how small is too small to bother, and how hard to try. None of it //! is decided by this library beyond a default a caller can replace. const std = @import("std"); const Reader = std.Io.Reader; const protocol = @import("../protocol.zig"); const coding = protocol.coding; const token = protocol.token; /// Media types worth compressing, as the default `Config.types`. /// /// Text, in the wide sense: §8.3.1 of RFC 9110's `text/*` covers plain, HTML, /// CSS and the rest, and the structured syntax suffixes of RFC 6839 pull in /// everything spelled `+json` or `+xml` without having to name it — /// `application/ld+json`, `application/problem+json`, /// `application/atom+xml`. What is left is the handful that are text and do /// not say so in their name. /// /// Deliberately not a list of what to *avoid*. A default that compresses /// everything except a list of known-incompressible types is a default that /// wastes processor time on the next format nobody has added to the list yet; /// one that compresses only what it recognises is wrong in the direction of /// doing nothing. pub const default_types = [_][]const u8{ "text/*", "application/json", "application/xml", "application/javascript", "application/yaml", "application/toml", "application/graphql", "application/wasm", "image/svg+xml", }; /// What this server will do about `Accept-Encoding`. pub const Config = struct { /// Codings this server can apply, in its own order of preference. A /// client's weights are read first — §12.5.3 of RFC 9110 gives it a say — /// and this order breaks the ties. codings: []const coding.Coding = &.{.gzip}, /// Media types worth compressing. Matched by exact name, by a `type/*` /// wildcard, and by RFC 6839's `+json` and `+xml` suffixes. /// /// Replace it rather than edit it: this is a slice a caller owns, and the /// default is `default_types`. types: []const []const u8 = &default_types, /// Below this many octets, send the representation as it is. /// /// Compression has a floor: a gzip member carries eighteen octets of /// header and footer before any of the content, and a few hundred octets /// of prose rarely saves enough to pay for the field it adds, the `Vary` /// it forces on every cache in the path, and the framing it gives up — /// a coded body's length is not known until it has been produced, so a /// response that could have declared `Content-Length` must be chunked /// instead. /// /// Only applied when the length is known. A handler that says `.unknown` /// has not told anybody how much is coming, so there is nothing to /// compare — see `wants`. min_length: usize = 4096, /// How hard to try. §8.4.1.3's coding says nothing about effort, so this /// is entirely a question of what the processor time is worth. level: coding.Compressor.Options = .default, }; /// Whether `content_type` is one of `types`. /// /// The type is matched without its parameters: §8.3.1 makes /// `text/plain; charset=utf-8` a `text/plain` representation, and a list that /// had to name every charset would match nothing. pub fn compressibleType(types: []const []const u8, content_type: ?[]const u8) bool { const full = content_type orelse return false; // Everything up to the first `;`, trimmed: the type and subtype alone. const semi = std.mem.indexOfScalar(u8, full, ';') orelse full.len; const media = token.trimOws(full[0..semi]); if (media.len == 0) return false; const slash = std.mem.indexOfScalar(u8, media, '/') orelse return false; const top = media[0..slash]; const sub = media[slash + 1 ..]; for (types) |pattern| { if (token.eqlIgnoreCase(pattern, media)) return true; // `type/*`, which is the whole of why `text/*` is one entry. if (std.mem.endsWith(u8, pattern, "/*")) { const pattern_top = pattern[0 .. pattern.len - 2]; if (token.eqlIgnoreCase(pattern_top, top)) return true; } // RFC 6839's structured syntax suffixes: a type whose subtype ends // `+json` is JSON, whatever else its name says, and a policy that // had to list `application/ld+json` and `application/problem+json` // and the next one would be a policy that misses the next one. if (token.eqlIgnoreCase(pattern, "application/json") and std.mem.endsWith(u8, sub, "+json")) return true; if (token.eqlIgnoreCase(pattern, "application/xml") and std.mem.endsWith(u8, sub, "+xml")) return true; } return false; } /// Whether a representation is negotiable at all — that is, whether what this /// server sends for it depends on `Accept-Encoding`. /// /// Separate from `wants` because it is the question `Vary` answers, and the /// two answers differ: a compressible representation below `min_length` is /// negotiable and is not going to be compressed *this time*. A cache told /// only about the times it was compressed would serve a coded body to a /// client that cannot read one. pub fn negotiable(config: Config, content_type: ?[]const u8) bool { return config.codings.len > 0 and compressibleType(config.types, content_type); } /// Which coding to apply, or null for none. pub fn wants( config: Config, accept_encoding: ?[]const u8, content_type: ?[]const u8, length: protocol.Length, ) ?coding.Coding { if (!negotiable(config, content_type)) return null; switch (length) { // Nothing to code, and §8.4's coding of nothing is still nothing. .none => return null, .exact => |n| if (n < config.min_length) return null, // The handler has not said how much is coming, so `min_length` has // nothing to compare against. Compressing is the better guess: // `.unknown` is the streaming case, which is where the large // responses are, and a handler that knows its body is tiny can say // so and be left alone. .unknown => {}, } // Only what this library can actually apply. §8.4.1 registers codings this // library can read and not write -- zstd is one -- and offering one of // those would be promising a representation nobody here can produce. var offerable: [8]coding.Coding = undefined; var n: usize = 0; for (config.codings) |c| { if (!c.canEncode() or n == offerable.len) continue; offerable[n] = c; n += 1; } const chosen = coding.selectEncoding(accept_encoding, offerable[0..n]) orelse return null; // §8.4.1.1: identity is a coding that does nothing, so there is nothing // to apply and nothing to say about it. return if (chosen == .identity) null else chosen; } /// What this server will undo on a request body before a handler sees it. /// /// A request body is chosen by whoever sent it, so this is the one direction /// of this feature where the input to a decoder is entirely hostile, and it is /// why this is null by default. `coding.UndoError` says what that has cost /// before: on Zig 0.16.0, twenty-five octets of gzip panicked the process. pub const RequestDecoding = struct { /// Codings to undo. A coding that is not here is left alone: the body /// reaches the handler as it arrived, coded, with the `Content-Encoding` /// field still on the request saying so. /// /// gzip alone by default, and zstd deliberately not. `Coding.canDecode` /// admits it and `coding.zstd_window_len` is why it is not switched on /// here without being asked for: §3.1.1.1.2 of RFC 8878 lets the *sender* /// choose the window, so a decoder accepts up to eight megabytes per /// stream and a server decoding request bodies pays that for every /// concurrent one. A client fetching one page at a time can have it for /// nothing; a server should decide. codings: []const coding.Coding = &.{.gzip}, }; /// What a decoded body is, for a caller to put back into a `Request.Body`. /// /// The pieces rather than the struct, so that this file does not have to /// import `Request` — which imports this one's neighbours and would make the /// direction of the dependency a question rather than a fact. pub const Decoded = struct { reader: *Reader, length: protocol.Length, }; /// Undoes a content coding on a request body, if this server was asked to. /// /// Unlike the response side, all three drivers give a request body as a /// reader — HTTP/2's is fed by an `Io.Queue` and HTTP/3's by its stream, but /// both are readers — so one wrapping serves every version and the body is /// still streamed rather than gathered. That is the opposite of what the /// clients had to do for responses, and the difference is which end owns the /// buffering. /// /// `arena` must outlive the request, because what comes back points into it. pub fn decodeRequest( arena: std.mem.Allocator, config: RequestDecoding, content_encoding: ?[]const u8, reader: *Reader, length: protocol.Length, ) error{OutOfMemory}!Decoded { const plain: Decoded = .{ .reader = reader, .length = length }; if (length == .none) return plain; const was = switch (coding.applied(content_encoding)) { // §8.4 again: a coding this server was not asked to undo, or one it // cannot, is the handler's representation to keep or refuse. Leaving // the `Content-Encoding` field in place is what lets it tell. .identity, .unsupported => return plain, .one => |c| c, }; var asked = false; for (config.codings) |want| { if (want == was) asked = true; } if (!asked) return plain; const window = try arena.alloc(u8, coding.decodeBufferLen(was)); const d = try arena.create(coding.Decoder); d.* = coding.Decoder.init(was, reader, window) catch return plain; return .{ .reader = d.reader(), // §8.6: `Content-Length` counted the coded octets, and the handler is // about to read the decoded ones. There is no number to give it, and // the one on the wire would make it stop short of the end of every // compressed body it ever read. .length = .unknown, }; } const testing = std.testing; test compressibleType { const types = &default_types; try testing.expect(compressibleType(types, "text/plain")); try testing.expect(compressibleType(types, "text/plain; charset=utf-8")); try testing.expect(compressibleType(types, "text/html;charset=utf-8")); try testing.expect(compressibleType(types, "TEXT/CSS")); try testing.expect(compressibleType(types, "application/json")); try testing.expect(compressibleType(types, "image/svg+xml")); // RFC 6839's suffixes, which is what makes the list short. try testing.expect(compressibleType(types, "application/ld+json")); try testing.expect(compressibleType(types, "application/problem+json")); try testing.expect(compressibleType(types, "application/atom+xml")); // Already compressed, or not text at all. try testing.expect(!compressibleType(types, "image/jpeg")); try testing.expect(!compressibleType(types, "application/zip")); try testing.expect(!compressibleType(types, "video/mp4")); try testing.expect(!compressibleType(types, "application/octet-stream")); // Nothing said, which is not the same as text. try testing.expect(!compressibleType(types, null)); try testing.expect(!compressibleType(types, "")); try testing.expect(!compressibleType(types, "nonsense")); // A caller's own list replaces it entirely. try testing.expect(compressibleType(&.{"application/octet-stream"}, "application/octet-stream")); try testing.expect(!compressibleType(&.{"application/octet-stream"}, "text/plain")); } test wants { const config: Config = .{}; const plain = "text/plain"; // The ordinary case. try testing.expectEqual(@as(?coding.Coding, .gzip), wants(config, "gzip", plain, .{ .exact = 8192 })); // Too small to pay for itself. try testing.expectEqual(@as(?coding.Coding, null), wants(config, "gzip", plain, .{ .exact = 100 })); // Exactly the floor is worth it; below it is not. try testing.expectEqual(@as(?coding.Coding, .gzip), wants(config, "gzip", plain, .{ .exact = 4096 })); try testing.expectEqual(@as(?coding.Coding, null), wants(config, "gzip", plain, .{ .exact = 4095 })); // A length nobody declared is the streaming case, and is compressed. try testing.expectEqual(@as(?coding.Coding, .gzip), wants(config, "gzip", plain, .unknown)); // No body at all. try testing.expectEqual(@as(?coding.Coding, null), wants(config, "gzip", plain, .none)); // The client's say. §12.5.3's `q=0` is a refusal, which is the whole // reason this goes through `selectEncoding` rather than a substring test. try testing.expectEqual(@as(?coding.Coding, null), wants(config, "gzip;q=0", plain, .{ .exact = 8192 })); try testing.expectEqual(@as(?coding.Coding, null), wants(config, null, plain, .{ .exact = 8192 })); try testing.expectEqual(@as(?coding.Coding, null), wants(config, "br", plain, .{ .exact = 8192 })); // Not a type worth coding. try testing.expectEqual(@as(?coding.Coding, null), wants(config, "gzip", "image/png", .{ .exact = 8192 })); // And the difference `Vary` turns on: the small one is still negotiable, // because what this server sends for it does depend on what was asked // for -- it just happens not to differ today. try testing.expect(negotiable(config, plain)); try testing.expect(!negotiable(config, "image/png")); try testing.expect(!negotiable(.{ .codings = &.{} }, plain)); } test negotiable { const config: Config = .{}; // Too small to compress this time, and still a response that has to say // `Vary: Accept-Encoding`, because a larger one for the same resource // would have been compressed. try testing.expect(wants(config, "gzip", "text/html", .{ .exact = 10 }) == null); try testing.expect(negotiable(config, "text/html")); // A type this server never codes does not vary at all. try testing.expect(!negotiable(config, "image/png")); } test decodeRequest { var arena_state: std.heap.ArenaAllocator = .init(testing.allocator); defer arena_state.deinit(); const arena = arena_state.allocator(); // What a client sent: "hello", gzipped. var coded_buf: [64]u8 = undefined; var coded: std.Io.Writer = .fixed(&coded_buf); var window: [coding.window_len]u8 = undefined; var c = try coding.gzipCompressor(&coded, &window, .default); try c.writer.writeAll("hello"); try c.finish(); var wire: Reader = .fixed(coded.buffered()); const body = try decodeRequest(arena, .{}, "gzip", &wire, .{ .exact = coded.buffered().len }); // The coded length is no use to a handler reading decoded octets. try testing.expectEqual(protocol.Length.unknown, body.length); try testing.expectEqualStrings("hello", try body.reader.allocRemaining(arena, .limited(64))); // A coding this server was not asked to undo is left as it arrived. var other: Reader = .fixed("hello"); const left = try decodeRequest(arena, .{ .codings = &.{} }, "gzip", &other, .{ .exact = 5 }); try testing.expect(left.reader == &other); }