// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT //! RFC 6455 §7.4: the status codes a Close frame carries, and which of them //! may appear on the wire. //! //! Three of the defined codes may never be *sent* — 1005, 1006 and 1015 exist //! so that an application can be told "there was no code" or "the connection //! broke" in the same shape as a real one. An endpoint that puts one in a //! Close frame is making a statement the protocol reserves for the library //! talking to its own caller, and receiving one is a protocol error. const std = @import("std"); pub const Code = enum(u16) { /// §7.4.1: "the purpose for which the connection was established has been /// fulfilled". normal = 1000, /// An endpoint is going away: a server shutting down, a browser /// navigating off the page. going_away = 1001, protocol_error = 1002, /// A kind of data this endpoint cannot accept — a binary message to /// something that only speaks text. unsupported_data = 1003, /// Reserved with no meaning yet. May not be sent. reserved = 1004, /// "No status code was actually present." Never on the wire. no_status = 1005, /// "The connection was closed abnormally." Never on the wire. abnormal = 1006, /// Data inconsistent with the type of the message — the one this library /// sends most, because it is what invalid UTF-8 in a text message is. invalid_payload = 1007, policy_violation = 1008, message_too_big = 1009, /// A client did not get the extensions it required. A server never sends /// this one. mandatory_extension = 1010, internal_error = 1011, /// TLS handshake failure. Never on the wire. tls_handshake = 1015, _, /// Whether a Close frame may carry this code. /// /// §7.4.2 gives the ranges: 0-999 unused, 1000-2999 for this protocol and /// its extensions, 3000-3999 for libraries and frameworks registered with /// IANA, 4000-4999 private. Inside the protocol's own range only the /// codes it has actually defined are sendable, which is what stops a /// peer inventing 1016 and meaning something by it. pub fn isSendable(c: Code) bool { const n = @intFromEnum(c); if (n >= 3000 and n <= 4999) return true; return switch (c) { .normal, .going_away, .protocol_error, .unsupported_data, .invalid_payload, .policy_violation, .message_too_big, .mandatory_extension, .internal_error, => true, // 1004, 1005, 1006 and 1015, and everything else in and below the // protocol's range. else => false, }; } }; const testing = std.testing; test "the codes RFC 6455 7.4.1 defines are the ones it numbers" { try testing.expectEqual(@as(u16, 1000), @intFromEnum(Code.normal)); try testing.expectEqual(@as(u16, 1001), @intFromEnum(Code.going_away)); try testing.expectEqual(@as(u16, 1002), @intFromEnum(Code.protocol_error)); try testing.expectEqual(@as(u16, 1003), @intFromEnum(Code.unsupported_data)); try testing.expectEqual(@as(u16, 1007), @intFromEnum(Code.invalid_payload)); try testing.expectEqual(@as(u16, 1008), @intFromEnum(Code.policy_violation)); try testing.expectEqual(@as(u16, 1009), @intFromEnum(Code.message_too_big)); try testing.expectEqual(@as(u16, 1011), @intFromEnum(Code.internal_error)); } test "the three codes that exist only for an application may not be sent" { // This is the rule with teeth: 1005 and 1006 are what a library reports // when there was no Close frame at all, so a peer that sends one is // claiming something it cannot know. try testing.expect(!Code.no_status.isSendable()); try testing.expect(!Code.abnormal.isSendable()); try testing.expect(!Code.tls_handshake.isSendable()); try testing.expect(!Code.reserved.isSendable()); } test "the reserved ranges of 7.4.2" { // Below the protocol's range. try testing.expect(!@as(Code, @enumFromInt(0)).isSendable()); try testing.expect(!@as(Code, @enumFromInt(999)).isSendable()); // Inside it but never defined. try testing.expect(!@as(Code, @enumFromInt(1016)).isSendable()); try testing.expect(!@as(Code, @enumFromInt(2999)).isSendable()); // Libraries and frameworks. try testing.expect(@as(Code, @enumFromInt(3000)).isSendable()); try testing.expect(@as(Code, @enumFromInt(3999)).isSendable()); // Private use. try testing.expect(@as(Code, @enumFromInt(4000)).isSendable()); try testing.expect(@as(Code, @enumFromInt(4999)).isSendable()); // And above it. try testing.expect(!@as(Code, @enumFromInt(5000)).isSendable()); try testing.expect(!@as(Code, @enumFromInt(65535)).isSendable()); }