gitoria

19.6 KB

1. // Shared WebSocket core — RFC 6455 framing, transport-agnostic (decision D8).
2. // Compiled into each HTTP plugin like http_common.zig; NOT a standalone .so.
3. //
4. // Responsibilities:
5. // - Sec-WebSocket-Accept computation (SHA1 + base64 of key + RFC GUID)
6. // - Frame encoding (unmasked, server → client) via a write callback
7. // - Frame decoding + message assembly (client-masked inbound), fragmentation,
8. // ping/pong surfacing, close handshake with codes, UTF-8 validation
9. //
10. // The per-protocol handshakes stay in each plugin: h1 = Upgrade/101 (http1.zig),
11. // h2 = RFC 8441 extended CONNECT (future), h3 = RFC 9220 (future). Everything
12. // after the handshake — the byte stream — goes through this module unchanged.
13. //
14. // Transport neutrality: encoding writes through `WriteFn` callbacks and decoding
15. // consumes raw bytes via `Decoder.feed()`; the module never touches a socket.
17. const std = @import("std");
19. pub const GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
21. /// Write callback: return false on transport failure (peer gone).
22. pub const WriteFn = *const fn (ctx: ?*anyopaque, data: []const u8) bool;
24. pub const Opcode = enum(u4) {
25. continuation = 0x0,
26. text = 0x1,
27. binary = 0x2,
28. close = 0x8,
29. ping = 0x9,
30. pong = 0xA,
31. _,
33. pub fn isControl(self: Opcode) bool {
34. return @intFromEnum(self) >= 0x8;
35. }
36. };
38. // Close codes used by the core
39. pub const CLOSE_NORMAL: u16 = 1000;
40. pub const CLOSE_GOING_AWAY: u16 = 1001;
41. pub const CLOSE_PROTOCOL_ERROR: u16 = 1002;
42. pub const CLOSE_INVALID_PAYLOAD: u16 = 1007;
43. pub const CLOSE_TOO_BIG: u16 = 1009;
44. pub const CLOSE_NO_STATUS: u16 = 1005; // synthesized when close frame has no code — never sent on the wire
46. /// Sec-WebSocket-Accept: base64(SHA1(key ++ GUID)). Output is always 28 chars.
47. pub fn computeAcceptKey(key: []const u8, out: *[28]u8) []const u8 {
48. var sha = std.crypto.hash.Sha1.init(.{});
49. sha.update(key);
50. sha.update(GUID);
51. var digest: [20]u8 = undefined;
52. sha.final(&digest);
53. return std.base64.standard.Encoder.encode(out, &digest);
54. }
56. /// Encode a frame header into `buf` (needs >= 10 bytes). Returns header length.
57. /// Server frames are unmasked (RFC 6455 §5.1).
58. pub fn encodeFrameHeader(buf: *[10]u8, opcode: Opcode, payload_len: usize, fin: bool) usize {
59. buf[0] = (if (fin) @as(u8, 0x80) else 0) | @as(u8, @intFromEnum(opcode));
60. if (payload_len <= 125) {
61. buf[1] = @intCast(payload_len);
62. return 2;
63. } else if (payload_len <= 65535) {
64. buf[1] = 126;
65. std.mem.writeInt(u16, buf[2..4], @intCast(payload_len), .big);
66. return 4;
67. } else {
68. buf[1] = 127;
69. std.mem.writeInt(u64, buf[2..10], payload_len, .big);
70. return 10;
71. }
72. }
74. /// Write one complete unmasked frame through the callback. True on success.
75. pub fn writeFrame(write: WriteFn, ctx: ?*anyopaque, opcode: Opcode, payload: []const u8) bool {
76. var hdr: [10]u8 = undefined;
77. const hlen = encodeFrameHeader(&hdr, opcode, payload.len, true);
78. if (!write(ctx, hdr[0..hlen])) return false;
79. if (payload.len > 0 and !write(ctx, payload)) return false;
80. return true;
81. }
83. /// Write a close frame with a code and optional reason (reason truncated to 123).
84. pub fn writeClose(write: WriteFn, ctx: ?*anyopaque, code: u16, reason: []const u8) bool {
85. var payload: [125]u8 = undefined;
86. std.mem.writeInt(u16, payload[0..2], code, .big);
87. const rlen = @min(reason.len, 123);
88. @memcpy(payload[2 .. 2 + rlen], reason[0..rlen]);
89. return writeFrame(write, ctx, .close, payload[0 .. 2 + rlen]);
90. }
92. /// A decoded inbound event. Payload slices are allocated with the decoder's
93. /// allocator and owned by the CALLER (free after use).
94. pub const Event = union(enum) {
95. text: []u8,
96. binary: []u8,
97. ping: []u8, // payload to echo in the pong
98. pong: []u8,
99. close: Close,
100. /// Protocol violation — caller should send a close frame with this code
101. /// and drop the connection.
102. protocol_error: u16,
104. pub const Close = struct {
105. code: u16, // CLOSE_NO_STATUS when the frame carried no code
106. reason: []u8,
107. };
109. pub fn deinitPayload(self: *Event, alloc: std.mem.Allocator) void {
110. switch (self.*) {
111. .text, .binary, .ping, .pong => |p| alloc.free(p),
112. .close => |cl| alloc.free(cl.reason),
113. .protocol_error => {},
114. }
115. }
116. };
118. fn validCloseCode(code: u16) bool {
119. return switch (code) {
120. 1000...1003, 1007...1011 => true,
121. 3000...4999 => true,
122. else => false,
123. };
124. }
126. /// Streaming frame decoder + message assembler. One per connection.
127. /// feed() raw transport bytes, then loop next() until it returns null.
128. pub const Decoder = struct {
129. alloc: std.mem.Allocator,
130. /// Client frames must be masked (server side). Set false for client use.
131. require_masked: bool = true,
132. max_message_size: usize = 16 * 1024 * 1024,
134. buf: std.ArrayListUnmanaged(u8) = .empty, // raw incoming bytes
135. read_pos: usize = 0,
136. msg: std.ArrayListUnmanaged(u8) = .empty, // fragmented-message assembly
137. msg_opcode: ?Opcode = null,
138. failed: bool = false, // after a protocol error the stream is dead
140. pub fn init(alloc: std.mem.Allocator) Decoder {
141. return .{ .alloc = alloc };
142. }
144. pub fn deinit(self: *Decoder) void {
145. self.buf.deinit(self.alloc);
146. self.msg.deinit(self.alloc);
147. }
149. pub fn feed(self: *Decoder, bytes: []const u8) !void {
150. // Compact consumed prefix before growing
151. if (self.read_pos > 0) {
152. const remaining = self.buf.items.len - self.read_pos;
153. std.mem.copyForwards(u8, self.buf.items[0..remaining], self.buf.items[self.read_pos..]);
154. self.buf.shrinkRetainingCapacity(remaining);
155. self.read_pos = 0;
156. }
157. try self.buf.appendSlice(self.alloc, bytes);
158. }
160. fn fail(self: *Decoder, code: u16) Event {
161. self.failed = true;
162. return .{ .protocol_error = code };
163. }
165. /// Pop the next complete event, or null if more bytes are needed.
166. pub fn next(self: *Decoder) !?Event {
167. if (self.failed) return null;
168. const data = self.buf.items[self.read_pos..];
169. if (data.len < 2) return null;
171. const b0 = data[0];
172. const b1 = data[1];
173. const fin = (b0 & 0x80) != 0;
174. const rsv = b0 & 0x70;
175. const opcode: Opcode = @enumFromInt(@as(u4, @truncate(b0 & 0x0F)));
176. const masked = (b1 & 0x80) != 0;
177. const len7: u8 = b1 & 0x7F;
179. if (rsv != 0) return self.fail(CLOSE_PROTOCOL_ERROR); // no extensions negotiated
180. switch (@intFromEnum(opcode)) {
181. 0x0, 0x1, 0x2, 0x8, 0x9, 0xA => {},
182. else => return self.fail(CLOSE_PROTOCOL_ERROR),
183. }
184. if (self.require_masked and !masked) return self.fail(CLOSE_PROTOCOL_ERROR);
185. if (opcode.isControl() and (!fin or len7 > 125)) return self.fail(CLOSE_PROTOCOL_ERROR);
187. var offset: usize = 2;
188. var payload_len: u64 = len7;
189. if (len7 == 126) {
190. if (data.len < offset + 2) return null;
191. payload_len = std.mem.readInt(u16, data[offset..][0..2], .big);
192. offset += 2;
193. if (payload_len <= 125) return self.fail(CLOSE_PROTOCOL_ERROR); // non-minimal encoding
194. } else if (len7 == 127) {
195. if (data.len < offset + 8) return null;
196. payload_len = std.mem.readInt(u64, data[offset..][0..8], .big);
197. offset += 8;
198. if (payload_len <= 65535) return self.fail(CLOSE_PROTOCOL_ERROR);
199. if (payload_len > (1 << 62)) return self.fail(CLOSE_PROTOCOL_ERROR); // MSB must be 0
200. }
201. if (payload_len > self.max_message_size or
202. self.msg.items.len + payload_len > self.max_message_size)
203. return self.fail(CLOSE_TOO_BIG);
205. var mask: [4]u8 = .{ 0, 0, 0, 0 };
206. if (masked) {
207. if (data.len < offset + 4) return null;
208. mask = data[offset..][0..4].*;
209. offset += 4;
210. }
212. const plen: usize = @intCast(payload_len);
213. if (data.len < offset + plen) return null; // frame incomplete
215. // Unmask into an owned copy
216. const payload = try self.alloc.alloc(u8, plen);
217. errdefer self.alloc.free(payload);
218. for (0..plen) |i| {
219. payload[i] = data[offset + i] ^ mask[i % 4];
220. }
221. self.read_pos += offset + plen;
223. switch (opcode) {
224. .ping => return .{ .ping = payload },
225. .pong => return .{ .pong = payload },
226. .close => {
227. if (plen == 0) return .{ .close = .{ .code = CLOSE_NO_STATUS, .reason = payload } };
228. if (plen == 1) {
229. self.alloc.free(payload);
230. return self.fail(CLOSE_PROTOCOL_ERROR);
231. }
232. const code = std.mem.readInt(u16, payload[0..2], .big);
233. if (!validCloseCode(code)) {
234. self.alloc.free(payload);
235. return self.fail(CLOSE_PROTOCOL_ERROR);
236. }
237. if (!std.unicode.utf8ValidateSlice(payload[2..])) {
238. self.alloc.free(payload);
239. return self.fail(CLOSE_INVALID_PAYLOAD);
240. }
241. const reason = try self.alloc.alloc(u8, plen - 2);
242. @memcpy(reason, payload[2..]);
243. self.alloc.free(payload);
244. return .{ .close = .{ .code = code, .reason = reason } };
245. },
246. .text, .binary => {
247. if (self.msg_opcode != null) {
248. self.alloc.free(payload);
249. return self.fail(CLOSE_PROTOCOL_ERROR); // new data frame while assembling
250. }
251. if (fin) {
252. if (opcode == .text and !std.unicode.utf8ValidateSlice(payload)) {
253. self.alloc.free(payload);
254. return self.fail(CLOSE_INVALID_PAYLOAD);
255. }
256. return if (opcode == .text) .{ .text = payload } else .{ .binary = payload };
257. }
258. // First fragment
259. self.msg_opcode = opcode;
260. try self.msg.appendSlice(self.alloc, payload);
261. self.alloc.free(payload);
262. return self.next(); // more frames may already be buffered
263. },
264. .continuation => {
265. const start_op = self.msg_opcode orelse {
266. self.alloc.free(payload);
267. return self.fail(CLOSE_PROTOCOL_ERROR); // continuation without a message
268. };
269. try self.msg.appendSlice(self.alloc, payload);
270. self.alloc.free(payload);
271. if (!fin) return self.next();
272. // Message complete
273. const full = try self.msg.toOwnedSlice(self.alloc);
274. self.msg_opcode = null;
275. if (start_op == .text and !std.unicode.utf8ValidateSlice(full)) {
276. self.alloc.free(full);
277. return self.fail(CLOSE_INVALID_PAYLOAD);
278. }
279. return if (start_op == .text) .{ .text = full } else .{ .binary = full };
280. },
281. _ => return self.fail(CLOSE_PROTOCOL_ERROR), // unreachable — filtered above
282. }
283. }
284. };
286. // ===========================================================================
287. // Tests
288. // ===========================================================================
290. const t = std.testing;
292. test "computeAcceptKey RFC 6455 sample" {
293. var out: [28]u8 = undefined;
294. const accept = computeAcceptKey("dGhlIHNhbXBsZSBub25jZQ==", &out);
295. try t.expectEqualStrings("s3pPLMBiTxaQ9kYGzzhZRbK+xOo=", accept);
296. }
298. fn maskedFrame(alloc: std.mem.Allocator, fin: bool, opcode: Opcode, payload: []const u8, mask: [4]u8) ![]u8 {
299. var out = std.ArrayListUnmanaged(u8).empty;
300. var hdr: [10]u8 = undefined;
301. const hlen = encodeFrameHeader(&hdr, opcode, payload.len, fin);
302. hdr[1] |= 0x80; // set mask bit
303. try out.appendSlice(alloc, hdr[0..hlen]);
304. try out.appendSlice(alloc, &mask);
305. for (payload, 0..) |b, i| try out.append(alloc, b ^ mask[i % 4]);
306. return out.toOwnedSlice(alloc);
307. }
309. test "decode masked text frame" {
310. var dec = Decoder.init(t.allocator);
311. defer dec.deinit();
312. const frame = try maskedFrame(t.allocator, true, .text, "Hello", .{ 0x37, 0xfa, 0x21, 0x3d });
313. defer t.allocator.free(frame);
314. try dec.feed(frame);
315. var ev = (try dec.next()).?;
316. defer ev.deinitPayload(t.allocator);
317. try t.expectEqualStrings("Hello", ev.text);
318. try t.expectEqual(@as(?Event, null), try dec.next());
319. }
321. test "decode split across feeds" {
322. var dec = Decoder.init(t.allocator);
323. defer dec.deinit();
324. const frame = try maskedFrame(t.allocator, true, .text, "chunked delivery", .{ 1, 2, 3, 4 });
325. defer t.allocator.free(frame);
326. try dec.feed(frame[0..3]);
327. try t.expectEqual(@as(?Event, null), try dec.next());
328. try dec.feed(frame[3..]);
329. var ev = (try dec.next()).?;
330. defer ev.deinitPayload(t.allocator);
331. try t.expectEqualStrings("chunked delivery", ev.text);
332. }
334. test "fragmented message assembly" {
335. var dec = Decoder.init(t.allocator);
336. defer dec.deinit();
337. const f1 = try maskedFrame(t.allocator, false, .text, "Hel", .{ 9, 8, 7, 6 });
338. defer t.allocator.free(f1);
339. const f2 = try maskedFrame(t.allocator, false, .continuation, "lo ", .{ 5, 4, 3, 2 });
340. defer t.allocator.free(f2);
341. const f3 = try maskedFrame(t.allocator, true, .continuation, "WS", .{ 1, 1, 1, 1 });
342. defer t.allocator.free(f3);
343. try dec.feed(f1);
344. try dec.feed(f2);
345. try t.expectEqual(@as(?Event, null), try dec.next());
346. try dec.feed(f3);
347. var ev = (try dec.next()).?;
348. defer ev.deinitPayload(t.allocator);
349. try t.expectEqualStrings("Hello WS", ev.text);
350. }
352. test "control frame interleaved with fragments" {
353. var dec = Decoder.init(t.allocator);
354. defer dec.deinit();
355. const f1 = try maskedFrame(t.allocator, false, .text, "par", .{ 2, 2, 2, 2 });
356. defer t.allocator.free(f1);
357. const ping = try maskedFrame(t.allocator, true, .ping, "hb", .{ 3, 3, 3, 3 });
358. defer t.allocator.free(ping);
359. const f2 = try maskedFrame(t.allocator, true, .continuation, "tial", .{ 4, 4, 4, 4 });
360. defer t.allocator.free(f2);
361. try dec.feed(f1);
362. try dec.feed(ping);
363. var ev1 = (try dec.next()).?;
364. defer ev1.deinitPayload(t.allocator);
365. try t.expectEqualStrings("hb", ev1.ping);
366. try dec.feed(f2);
367. var ev2 = (try dec.next()).?;
368. defer ev2.deinitPayload(t.allocator);
369. try t.expectEqualStrings("partial", ev2.text);
370. }
372. test "unmasked client frame is a protocol error" {
373. var dec = Decoder.init(t.allocator);
374. defer dec.deinit();
375. var hdr: [10]u8 = undefined;
376. const hlen = encodeFrameHeader(&hdr, .text, 2, true);
377. try dec.feed(hdr[0..hlen]);
378. try dec.feed("hi");
379. const ev = (try dec.next()).?;
380. try t.expectEqual(CLOSE_PROTOCOL_ERROR, ev.protocol_error);
381. try t.expectEqual(@as(?Event, null), try dec.next()); // stream dead
382. }
384. test "invalid UTF-8 in text is 1007" {
385. var dec = Decoder.init(t.allocator);
386. defer dec.deinit();
387. const bad = [_]u8{ 0xC3, 0x28 }; // invalid 2-byte sequence
388. const frame = try maskedFrame(t.allocator, true, .text, &bad, .{ 7, 7, 7, 7 });
389. defer t.allocator.free(frame);
390. try dec.feed(frame);
391. const ev = (try dec.next()).?;
392. try t.expectEqual(CLOSE_INVALID_PAYLOAD, ev.protocol_error);
393. }
395. test "close with code and reason" {
396. var dec = Decoder.init(t.allocator);
397. defer dec.deinit();
398. var payload: [7]u8 = undefined;
399. std.mem.writeInt(u16, payload[0..2], 1000, .big);
400. @memcpy(payload[2..], "done!");
401. const frame = try maskedFrame(t.allocator, true, .close, &payload, .{ 6, 6, 6, 6 });
402. defer t.allocator.free(frame);
403. try dec.feed(frame);
404. var ev = (try dec.next()).?;
405. defer ev.deinitPayload(t.allocator);
406. try t.expectEqual(@as(u16, 1000), ev.close.code);
407. try t.expectEqualStrings("done!", ev.close.reason);
408. }
410. test "close with invalid code is 1002" {
411. var dec = Decoder.init(t.allocator);
412. defer dec.deinit();
413. var payload: [2]u8 = undefined;
414. std.mem.writeInt(u16, payload[0..2], 1006, .big); // 1006 must never appear on the wire
415. const frame = try maskedFrame(t.allocator, true, .close, &payload, .{ 1, 2, 3, 4 });
416. defer t.allocator.free(frame);
417. try dec.feed(frame);
418. const ev = (try dec.next()).?;
419. try t.expectEqual(CLOSE_PROTOCOL_ERROR, ev.protocol_error);
420. }
422. test "fragmented control frame is 1002" {
423. var dec = Decoder.init(t.allocator);
424. defer dec.deinit();
425. const frame = try maskedFrame(t.allocator, false, .ping, "x", .{ 1, 2, 3, 4 });
426. defer t.allocator.free(frame);
427. try dec.feed(frame);
428. const ev = (try dec.next()).?;
429. try t.expectEqual(CLOSE_PROTOCOL_ERROR, ev.protocol_error);
430. }
432. test "continuation without message is 1002" {
433. var dec = Decoder.init(t.allocator);
434. defer dec.deinit();
435. const frame = try maskedFrame(t.allocator, true, .continuation, "x", .{ 1, 2, 3, 4 });
436. defer t.allocator.free(frame);
437. try dec.feed(frame);
438. const ev = (try dec.next()).?;
439. try t.expectEqual(CLOSE_PROTOCOL_ERROR, ev.protocol_error);
440. }
442. test "new data frame while assembling is 1002" {
443. var dec = Decoder.init(t.allocator);
444. defer dec.deinit();
445. const f1 = try maskedFrame(t.allocator, false, .text, "a", .{ 1, 2, 3, 4 });
446. defer t.allocator.free(f1);
447. const f2 = try maskedFrame(t.allocator, true, .text, "b", .{ 1, 2, 3, 4 });
448. defer t.allocator.free(f2);
449. try dec.feed(f1);
450. try dec.feed(f2);
451. const ev = (try dec.next()).?;
452. try t.expectEqual(CLOSE_PROTOCOL_ERROR, ev.protocol_error);
453. }
455. test "oversize message is 1009" {
456. var dec = Decoder.init(t.allocator);
457. defer dec.deinit();
458. dec.max_message_size = 8;
459. const frame = try maskedFrame(t.allocator, true, .text, "123456789", .{ 1, 2, 3, 4 });
460. defer t.allocator.free(frame);
461. try dec.feed(frame);
462. const ev = (try dec.next()).?;
463. try t.expectEqual(CLOSE_TOO_BIG, ev.protocol_error);
464. }
466. test "16-bit extended length round trip" {
467. var dec = Decoder.init(t.allocator);
468. defer dec.deinit();
469. const big = try t.allocator.alloc(u8, 300);
470. defer t.allocator.free(big);
471. @memset(big, 'A');
472. const frame = try maskedFrame(t.allocator, true, .binary, big, .{ 9, 9, 9, 9 });
473. defer t.allocator.free(frame);
474. try dec.feed(frame);
475. var ev = (try dec.next()).?;
476. defer ev.deinitPayload(t.allocator);
477. try t.expectEqual(@as(usize, 300), ev.binary.len);
478. try t.expectEqual(@as(u8, 'A'), ev.binary[150]);
479. }
481. test "writeFrame emits parseable frame" {
482. const Sink = struct {
483. var buf: std.ArrayListUnmanaged(u8) = .empty;
484. fn write(_: ?*anyopaque, data: []const u8) bool {
485. buf.appendSlice(t.allocator, data) catch return false;
486. return true;
487. }
488. };
489. defer Sink.buf.deinit(t.allocator);
490. try t.expect(writeFrame(&Sink.write, null, .text, "server says hi"));
491. // Parse it back with an unmasked-tolerant decoder (client role)
492. var dec = Decoder.init(t.allocator);
493. dec.require_masked = false;
494. defer dec.deinit();
495. try dec.feed(Sink.buf.items);
496. var ev = (try dec.next()).?;
497. defer ev.deinitPayload(t.allocator);
498. try t.expectEqualStrings("server says hi", ev.text);
499. }
501. test "writeClose encodes code and reason" {
502. const Sink = struct {
503. var buf: std.ArrayListUnmanaged(u8) = .empty;
504. fn write(_: ?*anyopaque, data: []const u8) bool {
505. buf.appendSlice(t.allocator, data) catch return false;
506. return true;
507. }
508. };
509. defer Sink.buf.deinit(t.allocator);
510. try t.expect(writeClose(&Sink.write, null, 1000, "bye"));
511. var dec = Decoder.init(t.allocator);
512. dec.require_masked = false;
513. defer dec.deinit();
514. try dec.feed(Sink.buf.items);
515. var ev = (try dec.next()).?;
516. defer ev.deinitPayload(t.allocator);
517. try t.expectEqual(@as(u16, 1000), ev.close.code);
518. try t.expectEqualStrings("bye", ev.close.reason);
519. }