tracker

18.4 KB

1. // Shared HTTP utilities — compiled into each HTTP plugin at build time
2. // Not a standalone plugin .so, but a Zig module imported by hl:http1, hl:http2, hl:http3
4. const std = @import("std");
5. const api = @import("plugin_api");
6. pub const HlString = api.HlString;
8. pub fn hlStr(s: []const u8) HlString {
9. return .{ .ptr = s.ptr, .len = s.len };
10. }
12. pub fn statusReason(code: u16) []const u8 {
13. return switch (code) {
14. 200 => "OK",
15. 201 => "Created",
16. 204 => "No Content",
17. 301 => "Moved Permanently",
18. 302 => "Found",
19. 304 => "Not Modified",
20. 400 => "Bad Request",
21. 401 => "Unauthorized",
22. 403 => "Forbidden",
23. 404 => "Not Found",
24. 405 => "Method Not Allowed",
25. 409 => "Conflict",
26. 413 => "Payload Too Large",
27. 415 => "Unsupported Media Type",
28. 422 => "Unprocessable Entity",
29. 429 => "Too Many Requests",
30. 500 => "Internal Server Error",
31. 502 => "Bad Gateway",
32. 503 => "Service Unavailable",
33. 504 => "Gateway Timeout",
34. else => "OK",
35. };
36. }
38. /// Decode percent-encoded URL components (%20 → space, etc.)
39. pub fn urlDecode(allocator: anytype, input: []const u8) ![]u8 {
40. var result = try allocator.alloc(u8, input.len);
41. var out: usize = 0;
42. var i: usize = 0;
44. while (i < input.len) {
45. if (input[i] == '%' and i + 2 < input.len) {
46. const hi = hexVal(input[i + 1]) orelse {
47. result[out] = input[i];
48. out += 1;
49. i += 1;
50. continue;
51. };
52. const lo = hexVal(input[i + 2]) orelse {
53. result[out] = input[i];
54. out += 1;
55. i += 1;
56. continue;
57. };
58. result[out] = (@as(u8, hi) << 4) | @as(u8, lo);
59. out += 1;
60. i += 3;
61. } else if (input[i] == '+') {
62. result[out] = ' ';
63. out += 1;
64. i += 1;
65. } else {
66. result[out] = input[i];
67. out += 1;
68. i += 1;
69. }
70. }
72. return result[0..out];
73. }
75. fn hexVal(c: u8) ?u4 {
76. if (c >= '0' and c <= '9') return @intCast(c - '0');
77. if (c >= 'a' and c <= 'f') return @intCast(c - 'a' + 10);
78. if (c >= 'A' and c <= 'F') return @intCast(c - 'A' + 10);
79. return null;
80. }
82. /// Split a query string into key-value pairs.
83. /// Returns allocated slices that must be freed by the caller.
84. pub fn parseQueryString(alloc: anytype, query: []const u8) ![]QueryParam {
85. var params: @import("std").ArrayListUnmanaged(QueryParam) = .empty;
86. var iter = @import("std").mem.splitScalar(u8, query, '&');
87. while (iter.next()) |pair| {
88. if (pair.len == 0) continue;
89. if (@import("std").mem.indexOfScalar(u8, pair, '=')) |eq| {
90. const key = try urlDecode(alloc, pair[0..eq]);
91. const val = try urlDecode(alloc, pair[eq + 1 ..]);
92. try params.append(alloc, .{ .key = key, .value = val });
93. } else {
94. const key = try urlDecode(alloc, pair);
95. try params.append(alloc, .{ .key = key, .value = &[_]u8{} });
96. }
97. }
98. return params.toOwnedSlice(alloc);
99. }
101. pub const QueryParam = struct {
102. key: []u8,
103. value: []u8,
104. };
106. /// Lowercase a header key in-place (HTTP/1.1 headers are case-insensitive)
107. pub fn toLowercase(buf: []u8) void {
108. for (buf) |*ch| {
109. if (ch.* >= 'A' and ch.* <= 'Z') {
110. ch.* = ch.* + 32;
111. }
112. }
113. }
115. // ---------------------------------------------------------------------------
116. // RESPONSE BODY COMPRESSION (creator, 2026-08-15) — a TRANSPORT concern, like
117. // TLS: nobody writes compression in app code; a server honors Accept-Encoding.
118. // ONE implementation here (decision D8's pattern), each plugin adds only its
119. // own framing. gzip via Zig std flate — no external library.
120. // ---------------------------------------------------------------------------
122. /// Below this a gzip header+footer is overhead, not savings (canonical ~860
123. /// from Akamai's measurements; MTU-fitting responses gain nothing).
124. pub const compress_min_len = 860;
126. /// The texty content types worth compressing, decided from the Content-Type
127. /// VALUE. Already-compressed formats (images, fonts, archives) get bigger, not
128. /// smaller. hl:http2 and hl:http3 carry headers as key/value pairs rather than
129. /// h1's raw blob, so this is the half they can ask.
130. pub fn compressibleTypeValue(value: []const u8) bool {
131. const v = std.mem.trim(u8, value, " ");
132. return std.mem.startsWith(u8, v, "text/") or
133. std.mem.startsWith(u8, v, "application/javascript") or
134. std.mem.startsWith(u8, v, "application/json") or
135. std.mem.startsWith(u8, v, "image/svg");
136. }
138. /// The same question asked of h1's assembled custom-header text.
139. pub fn compressibleContentType(headers_blob: []const u8) bool {
140. var it = std.mem.splitSequence(u8, headers_blob, "\r\n");
141. while (it.next()) |line| {
142. if (line.len > 13 and std.ascii.eqlIgnoreCase(line[0..13], "content-type:")) {
143. return compressibleTypeValue(line[13..]);
144. }
145. if (line.len > 17 and std.ascii.eqlIgnoreCase(line[0..17], "content-encoding:")) return false;
146. }
147. // no Content-Type in custom headers → the plugin's default is text/html
148. return true;
149. }
151. /// gzip `body`; null when compression does not pay (or fails — the caller then
152. /// sends the identity bytes, which is always correct).
153. pub fn gzipBody(allocator: std.mem.Allocator, body: []const u8) ?[]u8 {
154. if (body.len < compress_min_len) return null;
155. // Compress.init asserts `output.buffer.len > 8`, and a plain
156. // Allocating.init starts EMPTY — the assert then panics on a worker thread
157. // and kills the server after the first compressed response (found the hard
158. // way 2026-08-15). initCapacity gives the writer its buffer up front.
159. var out: std.Io.Writer.Allocating = std.Io.Writer.Allocating.initCapacity(allocator, 4096) catch return null;
160. defer out.deinit();
161. const window = allocator.alloc(u8, std.compress.flate.max_window_len) catch return null;
162. defer allocator.free(window);
163. // .level_6 — the documented setting; Options carries no defaults.
164. var c = std.compress.flate.Compress.init(&out.writer, window, .gzip, .level_6) catch return null;
165. c.writer.writeAll(body) catch return null;
166. c.finish() catch return null;
167. if (out.writer.buffered().len >= body.len) return null; // grew: send identity
168. return allocator.dupe(u8, out.writer.buffered()) catch null;
169. }
171. // ── The mission-125 BELL: one eventfd per loop source ────────────────────────
172. //
173. // RESTORED 2026-08-29 (mission 257). `hl:fetch` and `hl:smtp` both call these by
174. // name, and both had been UNBUILDABLE since the 2026-08-20 recovery replay
175. // dropped them from this file — nothing noticed, because `native/build.zig` did
176. // not build either plugin. See `native/src/loop_wait.zig` for the contract they
177. // implement: the loop owns one epoll set over every source's `wake_fd`, adds it
178. // LEVEL-triggered, and drains the counter itself right after `epoll_wait`. A
179. // producer therefore only ever has to create the fd and write to it.
180. //
181. // Raw syscalls rather than libc, so a plugin that does not link libc (hl:http1)
182. // can still ring a bell.
184. /// A source's wake fd: a non-blocking eventfd counter. `-1` on failure, which is
185. /// the ABI's "no signal, keep polling" value — a plugin that cannot get an fd
186. /// degrades to the polled path instead of failing to load.
187. pub fn makeWakeFd() i32 {
188. const rc = std.os.linux.eventfd(0, std.os.linux.EFD.NONBLOCK | std.os.linux.EFD.CLOEXEC);
189. if (@as(isize, @bitCast(rc)) < 0) return -1;
190. return @intCast(rc);
191. }
193. /// RING IT. Coalesced, duplicated or early wakes are harmless by design (a bell,
194. /// not a routing key); only a wake that is never sent can be a bug — so producers
195. /// ring generously and never reason about whether the loop "needs" it.
196. pub fn ringWake(fd: i32) void {
197. if (fd < 0) return;
198. const one: u64 = 1;
199. _ = std.os.linux.write(fd, @ptrCast(&one), @sizeOf(u64));
200. }
202. // ================================================================================
203. // WHY A BIND FAILED — IN WORDS, AND WITH THE HOLDER'S NAME (mission 286)
204. // ================================================================================
205. // All three transports used to print the same six words — `bind() failed on port
206. // N` — and drop the errno on the floor. Six words cannot be acted on: a port that
207. // is taken, a port below 1024 without CAP_NET_BIND_SERVICE, and an address that is
208. // not one of this machine's are three different mistakes with three different
209. // fixes, and the kernel had already said which one it was.
210. //
211. // So the errno is named, and when it is EADDRINUSE the holder is looked up the way
212. // an operator would look it up: `/proc/net/{tcp,tcp6,udp,udp6}` for the socket on
213. // that port, then `/proc/<pid>/fd` for whoever owns its inode. It says "a process
214. // this one cannot see" rather than guessing when the holder belongs to another
215. // user — `/proc/<pid>/fd` is unreadable then, and a wrong name is worse than none.
216. //
217. // This costs nothing on the happy path: it runs once, on a boot that is about to
218. // be refused.
220. fn errnoWord(e: u32) []const u8 {
221. return switch (e) {
222. 13 => "EACCES",
223. 22 => "EINVAL",
224. 24 => "EMFILE",
225. 97 => "EAFNOSUPPORT",
226. 98 => "EADDRINUSE",
227. 99 => "EADDRNOTAVAIL",
228. else => "errno",
229. };
230. }
232. fn errnoWhy(e: u32) []const u8 {
233. return switch (e) {
234. 13 => "permission denied — a port below 1024 needs CAP_NET_BIND_SERVICE or root",
235. 22 => "invalid argument — this socket is already bound",
236. 24 => "too many open files — the process fd limit is reached",
237. 97 => "address family not supported",
238. 98 => "the port is already in use",
239. 99 => "that address is not one of this machine's",
240. else => "the kernel refused the bind",
241. };
242. }
244. fn hexNibble(c: u8) ?u8 {
245. return switch (c) {
246. '0'...'9' => c - '0',
247. 'a'...'f' => c - 'a' + 10,
248. 'A'...'F' => c - 'A' + 10,
249. else => null,
250. };
251. }
253. fn hexValue(s: []const u8) ?u64 {
254. if (s.len == 0 or s.len > 16) return null;
255. var v: u64 = 0;
256. for (s) |c| v = (v << 4) | (hexNibble(c) orelse return null);
257. return v;
258. }
260. /// `/proc/net/*`'s local_address column ("0100007F:1F90") as text the operator
261. /// recognises. IPv4 is four little-endian bytes; anything longer is printed as the
262. /// raw hex word rather than mis-rendered as a v6 address it may not be.
263. fn writeProcAddr(out: []u8, hex: []const u8, port: u16) []const u8 {
264. if (hex.len == 8) {
265. const v = hexValue(hex) orelse return "";
266. const b: [4]u8 = .{
267. @truncate(v & 0xff),
268. @truncate((v >> 8) & 0xff),
269. @truncate((v >> 16) & 0xff),
270. @truncate((v >> 24) & 0xff),
271. };
272. return std.fmt.bufPrint(out, "{d}.{d}.{d}.{d}:{d}", .{ b[0], b[1], b[2], b[3], port }) catch "";
273. }
274. return std.fmt.bufPrint(out, "[{s}]:{d}", .{ hex, port }) catch "";
275. }
277. // RAW SYSCALLS, for the same reason the wake bell above uses them: this file is
278. // compiled INTO three plugins, `std.fs` in Zig 0.16 wants an `Io` interface these
279. // plugins do not carry, and `/proc` is read once, at a boot that is failing.
280. const lin = std.os.linux;
282. fn sysOpen(path: [*:0]const u8, dir: bool) ?i32 {
283. const rc = lin.open(path, .{ .ACCMODE = .RDONLY, .CLOEXEC = true, .DIRECTORY = dir }, 0);
284. const fd: i64 = @bitCast(@as(u64, rc));
285. if (fd < 0) return null;
286. return @intCast(fd);
287. }
289. fn sysClose(fd: i32) void {
290. _ = lin.close(fd);
291. }
293. const SocketOnPort = struct { inode: u64, addr_hex: [40]u8, addr_len: usize };
295. /// The socket sitting on `port`, out of the four `/proc/net` tables. For TCP only a
296. /// LISTEN socket (`st == 0A`) can block a bind — mission 285 measured that, squat by
297. /// squat: TIME_WAIT and ESTABLISHED are tolerated because both sides set
298. /// SO_REUSEADDR. UDP has no states worth filtering.
299. fn socketOnPort(port: u16, udp: bool) ?SocketOnPort {
300. const tables: [2][*:0]const u8 = if (udp)
301. .{ "/proc/net/udp", "/proc/net/udp6" }
302. else
303. .{ "/proc/net/tcp", "/proc/net/tcp6" };
304. for (tables) |path| {
305. const fd = sysOpen(path, false) orelse continue;
306. defer sysClose(fd);
307. var chunk: [8192]u8 = undefined;
308. var line: [512]u8 = undefined;
309. var line_len: usize = 0;
310. while (true) {
311. const rc = lin.read(fd, &chunk, chunk.len);
312. const got: i64 = @bitCast(@as(u64, rc));
313. if (got <= 0) break;
314. const n: usize = @intCast(got);
315. for (chunk[0..n]) |ch| {
316. if (ch != '\n') {
317. if (line_len < line.len) {
318. line[line_len] = ch;
319. line_len += 1;
320. }
321. continue;
322. }
323. if (parseProcNetLine(line[0..line_len], port, udp)) |hit| return hit;
324. line_len = 0;
325. }
326. }
327. if (line_len > 0) {
328. if (parseProcNetLine(line[0..line_len], port, udp)) |hit| return hit;
329. }
330. }
331. return null;
332. }
335. /// One `/proc/net/*` row: `sl local rem st tx:rx tr:when retrnsmt uid timeout inode`.
336. fn parseProcNetLine(line: []const u8, port: u16, udp: bool) ?SocketOnPort {
337. var it = std.mem.tokenizeAny(u8, line, " \t");
338. _ = it.next() orelse return null; // sl
339. const local = it.next() orelse return null;
340. _ = it.next() orelse return null; // rem_address
341. const st = it.next() orelse return null;
342. if (!udp and !std.mem.eql(u8, st, "0A")) return null;
343. const colon = std.mem.lastIndexOfScalar(u8, local, ':') orelse return null;
344. const lport = hexValue(local[colon + 1 ..]) orelse return null;
345. if (lport != port) return null;
346. var skipped: usize = 0;
347. while (skipped < 5) : (skipped += 1) _ = it.next() orelse return null;
348. const inode = std.fmt.parseInt(u64, it.next() orelse return null, 10) catch return null;
349. const hex = local[0..colon];
350. var hit = SocketOnPort{ .inode = inode, .addr_hex = undefined, .addr_len = 0 };
351. if (hex.len > hit.addr_hex.len) return null;
352. @memcpy(hit.addr_hex[0..hex.len], hex);
353. hit.addr_len = hex.len;
354. return hit;
355. }
357. /// Whoever has that socket inode open. An unreadable `/proc/<pid>/fd` is SKIPPED,
358. /// not reported as absent: a holder owned by another user is invisible from here,
359. /// and the caller says exactly that instead of naming the wrong process.
360. fn pidHolding(inode: u64, name_out: []u8, name_len: *usize) ?u32 {
361. const proc_fd = sysOpen("/proc", true) orelse return null;
362. defer sysClose(proc_fd);
363. var want: [48]u8 = undefined;
364. const want_link = std.fmt.bufPrint(&want, "socket:[{d}]", .{inode}) catch return null;
365. var ents: [8192]u8 align(8) = undefined;
366. while (true) {
367. const rc = lin.getdents64(proc_fd, &ents, ents.len);
368. const got: i64 = @bitCast(@as(u64, rc));
369. if (got <= 0) return null;
370. var off: usize = 0;
371. while (off < @as(usize, @intCast(got))) {
372. const ent: *align(1) const lin.dirent64 = @ptrCast(&ents[off]);
373. off += ent.reclen;
374. const name_ptr: [*:0]const u8 = @ptrCast(&ent.name);
375. const pid = std.fmt.parseInt(u32, std.mem.span(name_ptr), 10) catch continue;
376. if (fdsHold(pid, want_link)) {
377. name_len.* = readComm(pid, name_out);
378. return pid;
379. }
380. }
381. }
382. }
384. /// Does this pid have that socket open? An unreadable `/proc/<pid>/fd` answers
385. /// false — the process belongs to another user and is simply not visible.
386. fn fdsHold(pid: u32, want_link: []const u8) bool {
387. var path: [64:0]u8 = undefined;
388. const dir_path = std.fmt.bufPrintZ(&path, "/proc/{d}/fd", .{pid}) catch return false;
389. const dir_fd = sysOpen(dir_path, true) orelse return false;
390. defer sysClose(dir_fd);
391. var ents: [4096]u8 align(8) = undefined;
392. while (true) {
393. const rc = lin.getdents64(dir_fd, &ents, ents.len);
394. const got: i64 = @bitCast(@as(u64, rc));
395. if (got <= 0) return false;
396. var off: usize = 0;
397. while (off < @as(usize, @intCast(got))) {
398. const ent: *align(1) const lin.dirent64 = @ptrCast(&ents[off]);
399. off += ent.reclen;
400. const name_ptr: [*:0]const u8 = @ptrCast(&ent.name);
401. var lbuf: [64]u8 = undefined;
402. const lrc = lin.readlinkat(dir_fd, name_ptr, &lbuf, lbuf.len);
403. const llen: i64 = @bitCast(@as(u64, lrc));
404. if (llen <= 0) continue;
405. if (std.mem.eql(u8, lbuf[0..@intCast(llen)], want_link)) return true;
406. }
407. }
408. }
410. fn readComm(pid: u32, out: []u8) usize {
411. var path: [64:0]u8 = undefined;
412. const p = std.fmt.bufPrintZ(&path, "/proc/{d}/comm", .{pid}) catch return 0;
413. const fd = sysOpen(p, false) orelse return 0;
414. defer sysClose(fd);
415. const rc = lin.read(fd, out.ptr, out.len);
416. const got: i64 = @bitCast(@as(u64, rc));
417. if (got <= 0) return 0;
418. var len: usize = @intCast(got);
419. while (len > 0 and (out[len - 1] == '\n' or out[len - 1] == '\r')) len -= 1;
420. return len;
421. }
423. /// The sentence a transport appends to `bind() failed on port N`. It never fails: a
424. /// buffer too small or a `/proc` that will not answer degrades to the part that IS
425. /// known, and the errno alone already says more than the old message did.
426. pub fn bindFailureDetail(out: []u8, rc: usize, port: u16, udp: bool) []const u8 {
427. const signed: i64 = @bitCast(@as(u64, rc));
428. const errno: u32 = if (signed < 0 and signed > -4096) @intCast(-signed) else 0;
429. var w: usize = 0;
430. const head = std.fmt.bufPrint(out[w..], "{s} — {s}", .{ errnoWord(errno), errnoWhy(errno) }) catch return out[0..w];
431. w += head.len;
432. if (errno != 98) return out[0..w];
433. const sock = socketOnPort(port, udp) orelse {
434. const gone = std.fmt.bufPrint(out[w..], "; nothing holds it now — the listener came and went", .{}) catch return out[0..w];
435. return out[0 .. w + gone.len];
436. };
437. var abuf: [80]u8 = undefined;
438. const addr = writeProcAddr(&abuf, sock.addr_hex[0..sock.addr_len], port);
439. var comm: [32]u8 = undefined;
440. var comm_len: usize = 0;
441. if (pidHolding(sock.inode, &comm, &comm_len)) |pid| {
442. const tail = std.fmt.bufPrint(out[w..], "; held by pid {d} ({s}) on {s}", .{ pid, comm[0..comm_len], addr }) catch return out[0..w];
443. return out[0 .. w + tail.len];
444. }
445. const tail = std.fmt.bufPrint(out[w..], "; held on {s} by a process this one cannot see (another user)", .{addr}) catch return out[0..w];
446. return out[0 .. w + tail.len];
447. }