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