|
| 1 | +// |
| 2 | +// RFC_1123.Domain.Label.swift |
| 3 | +// swift-rfc-1123 |
| 4 | +// |
| 5 | +// Created by Coen ten Thije Boonkkamp on 21/11/2025. |
| 6 | +// |
| 7 | + |
| 8 | +public import INCITS_4_1986 |
| 9 | + |
| 10 | +extension RFC_1123.Domain { |
| 11 | + /// RFC 1123 compliant host label |
| 12 | + /// |
| 13 | + /// Represents a single label within a host name as defined by RFC 1123 Section 2.1. |
| 14 | + /// Labels are case-insensitive ASCII strings that can start with letters or digits. |
| 15 | + /// |
| 16 | + /// ## RFC 1123 Constraints |
| 17 | + /// |
| 18 | + /// Per RFC 1123 Section 2.1: |
| 19 | + /// - Must be 1-63 octets long |
| 20 | + /// - Can start with letter or digit (relaxed from RFC 1035) |
| 21 | + /// - Must end with a letter or digit |
| 22 | + /// - May contain letters, digits, and hyphens |
| 23 | + /// |
| 24 | + /// Note: The RFC 1123 constraint that "the highest-level component label will be alphabetic" |
| 25 | + /// is enforced at the Domain level, not here, since it's a positional constraint about where |
| 26 | + /// the label appears in a hostname, not a grammar rule about label syntax. |
| 27 | + /// |
| 28 | + /// ## Example |
| 29 | + /// |
| 30 | + /// ```swift |
| 31 | + /// let label = try RFC_1123.Domain.Label("3com") // Valid |
| 32 | + /// let label2 = try RFC_1123.Domain.Label("com") // Valid |
| 33 | + /// ``` |
| 34 | + public struct Label: Sendable, Codable { |
| 35 | + /// The label value |
| 36 | + public let rawValue: String |
| 37 | + |
| 38 | + /// Creates a label WITHOUT validation |
| 39 | + /// |
| 40 | + /// **Warning**: Bypasses RFC 1123 validation. |
| 41 | + /// Only use with compile-time constants or pre-validated values. |
| 42 | + /// |
| 43 | + /// - Parameters: |
| 44 | + /// - unchecked: Void parameter to prevent accidental use |
| 45 | + /// - rawValue: The raw label value (unchecked) |
| 46 | + init( |
| 47 | + __unchecked: Void, |
| 48 | + rawValue: String |
| 49 | + ) { |
| 50 | + self.rawValue = rawValue |
| 51 | + } |
| 52 | + } |
| 53 | +} |
| 54 | + |
| 55 | +// MARK: - Hashable |
| 56 | + |
| 57 | +extension RFC_1123.Domain.Label: Hashable { |
| 58 | + /// Hash value (case-insensitive per RFC 1123) |
| 59 | + public func hash(into hasher: inout Hasher) { |
| 60 | + hasher.combine(rawValue.lowercased()) |
| 61 | + } |
| 62 | + |
| 63 | + /// Equality comparison (case-insensitive per RFC 1123) |
| 64 | + public static func == (lhs: Self, rhs: Self) -> Bool { |
| 65 | + lhs.rawValue.lowercased() == rhs.rawValue.lowercased() |
| 66 | + } |
| 67 | + |
| 68 | + /// Equality comparison with raw value (case-insensitive) |
| 69 | + public static func == (lhs: Self, rhs: Self.RawValue) -> Bool { |
| 70 | + lhs.rawValue.lowercased() == rhs.lowercased() |
| 71 | + } |
| 72 | +} |
| 73 | + |
| 74 | +// MARK: - Serializing |
| 75 | + |
| 76 | +extension RFC_1123.Domain.Label: UInt8.ASCII.Serializing { |
| 77 | + public static let serialize: @Sendable (Self) -> [UInt8] = [UInt8].init |
| 78 | + |
| 79 | + /// Parses a host label from canonical byte representation (CANONICAL PRIMITIVE) |
| 80 | + /// |
| 81 | + /// This is the primitive parser that works at the byte level. |
| 82 | + /// RFC 1123 host labels are ASCII-only. |
| 83 | + /// |
| 84 | + /// ## RFC 1123 Compliance |
| 85 | + /// |
| 86 | + /// Per RFC 1123 Section 2.1: |
| 87 | + /// - Labels must be 1-63 octets |
| 88 | + /// - Can start with letter or digit (relaxed from RFC 1035) |
| 89 | + /// - Must end with a letter or digit |
| 90 | + /// - May contain letters, digits, and hyphens |
| 91 | + /// |
| 92 | + /// ## Category Theory |
| 93 | + /// |
| 94 | + /// This is the fundamental parsing transformation: |
| 95 | + /// - **Domain**: [UInt8] (ASCII bytes) |
| 96 | + /// - **Codomain**: RFC_1123.Domain.Label (structured data) |
| 97 | + /// |
| 98 | + /// String-based parsing is derived as composition: |
| 99 | + /// ``` |
| 100 | + /// String → [UInt8] (UTF-8 bytes) → Domain.Label |
| 101 | + /// ``` |
| 102 | + /// |
| 103 | + /// ## Example |
| 104 | + /// |
| 105 | + /// ```swift |
| 106 | + /// let bytes = Array("3com".utf8) |
| 107 | + /// let label = try RFC_1123.Domain.Label(ascii: bytes) |
| 108 | + /// ``` |
| 109 | + /// |
| 110 | + /// - Parameter bytes: The ASCII byte representation of the label |
| 111 | + /// - Throws: `RFC_1123.Domain.Label.Error` if the bytes are malformed |
| 112 | + public init<Bytes: Collection>(ascii bytes: Bytes) throws(Error) |
| 113 | + where Bytes.Element == UInt8 { |
| 114 | + guard let firstByte = bytes.first else { |
| 115 | + throw Error.empty |
| 116 | + } |
| 117 | + |
| 118 | + var count = 0 |
| 119 | + var lastByte = firstByte |
| 120 | + |
| 121 | + for byte in bytes { |
| 122 | + count += 1 |
| 123 | + lastByte = byte |
| 124 | + |
| 125 | + let valid = byte.ascii.isLetter || byte.ascii.isDigit || byte == .ascii.hyphen |
| 126 | + guard valid else { |
| 127 | + let string = String(decoding: bytes, as: UTF8.self) |
| 128 | + throw Error.invalidCharacters( |
| 129 | + string, |
| 130 | + byte: byte, |
| 131 | + reason: "Only letters, digits, and hyphens allowed" |
| 132 | + ) |
| 133 | + } |
| 134 | + } |
| 135 | + |
| 136 | + guard count <= RFC_1123.Domain.Limits.maxLabelLength else { |
| 137 | + let string = String(decoding: bytes, as: UTF8.self) |
| 138 | + throw Error.tooLong(count, label: string) |
| 139 | + } |
| 140 | + |
| 141 | + // RFC 1123: Can start with letter or digit |
| 142 | + guard firstByte.ascii.isLetter || firstByte.ascii.isDigit else { |
| 143 | + let string = String(decoding: bytes, as: UTF8.self) |
| 144 | + throw Error.invalidCharacters( |
| 145 | + string, |
| 146 | + byte: firstByte, |
| 147 | + reason: "Must start with a letter or digit" |
| 148 | + ) |
| 149 | + } |
| 150 | + |
| 151 | + // Must end with a letter or digit |
| 152 | + guard lastByte.ascii.isLetter || lastByte.ascii.isDigit else { |
| 153 | + let string = String(decoding: bytes, as: UTF8.self) |
| 154 | + throw Error.invalidCharacters( |
| 155 | + string, |
| 156 | + byte: lastByte, |
| 157 | + reason: "Must end with a letter or digit" |
| 158 | + ) |
| 159 | + } |
| 160 | + |
| 161 | + self.init(__unchecked: (), rawValue: String(decoding: bytes, as: UTF8.self)) |
| 162 | + } |
| 163 | +} |
| 164 | + |
| 165 | +// MARK: - Byte Serialization |
| 166 | + |
| 167 | +extension [UInt8] { |
| 168 | + /// Creates ASCII byte representation of an RFC 1123 host label |
| 169 | + /// |
| 170 | + /// This is the canonical serialization of host labels to bytes. |
| 171 | + /// RFC 1123 host labels are ASCII-only by definition. |
| 172 | + /// |
| 173 | + /// ## Category Theory |
| 174 | + /// |
| 175 | + /// This is the most universal serialization (natural transformation): |
| 176 | + /// - **Domain**: RFC_1123.Domain.Label (structured data) |
| 177 | + /// - **Codomain**: [UInt8] (ASCII bytes) |
| 178 | + /// |
| 179 | + /// String representation is derived as composition: |
| 180 | + /// ``` |
| 181 | + /// Domain.Label → [UInt8] (ASCII) → String (UTF-8 interpretation) |
| 182 | + /// ``` |
| 183 | + /// |
| 184 | + /// ## Example |
| 185 | + /// |
| 186 | + /// ```swift |
| 187 | + /// let label = try RFC_1123.Domain.Label("3com") |
| 188 | + /// let bytes = [UInt8](label) |
| 189 | + /// // bytes == "3com" as ASCII bytes |
| 190 | + /// ``` |
| 191 | + /// |
| 192 | + /// - Parameter label: The host label to serialize |
| 193 | + public init(_ label: RFC_1123.Domain.Label) { |
| 194 | + self = Array(label.rawValue.utf8) |
| 195 | + } |
| 196 | +} |
| 197 | + |
| 198 | +// MARK: - Protocol Conformances |
| 199 | + |
| 200 | +extension RFC_1123.Domain.Label: UInt8.ASCII.RawRepresentable {} |
| 201 | +extension RFC_1123.Domain.Label: CustomStringConvertible {} |
0 commit comments