dymokomi/luce-std
Source of release 0.7.0
0.7.0 / src / net / websocket / frame.lucb
#==============================================================================================
#
# frame - WebSocket frame codec
#
# DESCRIPTION:
# Parse and write RFC 6455 frames and decode a message stream; storage is caller-owned.
#
#==============================================================================================
# mark: Frames ================================================================================
## RFC 6455 base opcodes. Extensions and reserved bits/opcodes are rejected.
pub enum WebSocketOpcode as u8:
continuation = 0
text = 1
binary = 2
close = 8
ping = 9
pong = 10
## A decoded WebSocket frame: its opcode, control flags, and payload bytes.
pub struct WebSocketFrame:
## The frame's opcode.
pub var opcode: WebSocketOpcode
## Whether this is the final frame of a message.
pub var final: bool
## The payload length.
pub var length: u64
## The size of the frame header.
pub var header_bytes: usize
## The masking key.
pub var mask: u8[4]
## Whether the payload is masked.
pub var masked: bool
## Parse a frame header only. None means incomplete input; no payload is consumed.
## from_client enforces the direction's mandatory masking rule. Extended lengths
## must use the shortest encoding and may not set the 64-bit sign bit.
pub func websocket_parse_frame(data: const u8[], from_client: bool, maximum: u64 = 16777216) -> WebSocketFrame?!:
if data.length < 2:
return none
if data[0] & 112 != 0:
error(websocket_invalid, "WebSocket reserved bits require an extension")
let opcode = try websocket_opcode(data[0] & 15)
let final = data[0] & 128 != 0
let masked = data[1] & 128 != 0
if masked != from_client:
error(websocket_invalid, "WebSocket masking is wrong for this direction")
let short = data[1] & 127
var header_bytes: usize = 2
var length = (u64)short
if short == 126:
if data.length < 4:
return none
length = ((u64)data[2] << 8) | (u64)data[3]
header_bytes = 4
if length < 126:
error(websocket_invalid, "nonminimal WebSocket payload length")
elif short == 127:
if data.length < 10:
return none
if data[2] & 128 != 0:
error(websocket_invalid, "WebSocket payload length has its sign bit set")
length = 0
for index in 2..<10:
length = (length << 8) | (u64)data[index]
header_bytes = 10
if length < 65536:
error(websocket_invalid, "nonminimal WebSocket payload length")
if length > maximum:
error(websocket_limit, "WebSocket frame exceeds its byte limit")
if (u8)opcode >= 8 and (not final or length > 125):
error(websocket_invalid, "WebSocket control frame must be final and at most 125 bytes")
var mask: u8[4]
if masked:
if data.length - header_bytes < 4:
return none
memory.copy(mask, data[header_bytes..], 4)
header_bytes += 4
return WebSocketFrame(opcode = opcode, final = final, length = length, header_bytes = header_bytes, mask = mask, masked = masked)
func websocket_opcode(value: u8) -> WebSocketOpcode!:
match value:
0: return WebSocketOpcode.continuation
1: return WebSocketOpcode.text
2: return WebSocketOpcode.binary
8: return WebSocketOpcode.close
9: return WebSocketOpcode.ping
10: return WebSocketOpcode.pong
_: error(websocket_invalid, "reserved WebSocket opcode")
## Validate a close payload, including its optional status and UTF-8 reason.
## Empty means no status; wire-forbidden/reserved status codes are rejected.
pub func websocket_check_close(payload: const u8[]) -> !:
if payload.length == 0:
return
if payload.length < 2 or payload.length > 125:
error(websocket_invalid, "invalid WebSocket close payload length")
let code = ((u16)payload[0] << 8) | (u16)payload[1]
if code < 1000 or code >= 5000 or code == 1004 or code == 1005 or code == 1006 or (code >= 1016 and code < 3000) or code == 1015:
error(websocket_invalid, "reserved WebSocket close status")
var decoder: utf8.Decoder
for byte in payload[2..]:
_ = try decoder.push(byte)
try decoder.finish()
struct WebSocketSequence:
var fragmented: bool
var text: bool
var total: u64
var maximum: u64 = 16777216
var decoder: utf8.Decoder
var control: u8[125]
var control_used: usize
var closing: bool
func begin(frame: WebSocketFrame) -> !:
# a control frame the peer had queued may still follow its close (RFC 6455 ยง5.5.1)
if self.closing and (u8)frame.opcode < 8:
error(websocket_invalid, "WebSocket data follows a close frame")
if (u8)frame.opcode >= 8:
self.control_used = 0
return
if frame.opcode == WebSocketOpcode.continuation:
if not self.fragmented:
error(websocket_invalid, "WebSocket continuation has no initial frame")
else:
if self.fragmented:
error(websocket_invalid, "new WebSocket message interrupts fragmentation")
self.text = frame.opcode == WebSocketOpcode.text
self.total = 0
self.decoder.reset()
if frame.length > self.maximum - self.total:
error(websocket_limit, "WebSocket message exceeds its byte limit")
self.total += frame.length
self.fragmented = not frame.final
func payload(frame: WebSocketFrame, data: const u8[], ended: bool) -> !:
if (u8)frame.opcode >= 8:
if frame.opcode == WebSocketOpcode.close:
memory.copy(self.control[self.control_used..], data, data.length)
self.control_used += data.length
if ended:
try websocket_check_close(self.control[..<self.control_used])
self.closing = true
return
if self.text:
for byte in data:
_ = try self.decoder.push(byte)
if ended and frame.final:
try self.decoder.finish()
## One decoder step. Payload is output[..written], validated up to this point.
## Consume/frame/message flags delimit data; control payloads must be accumulated
## until frame_end before acting. On error, earlier fragments must be discarded.
pub struct WebSocketStep:
## Bytes consumed from the input this step.
pub var consumed: usize
## Bytes written to the output this step.
pub var written: usize
## The current message's opcode.
pub var opcode: WebSocketOpcode
## Whether a frame began this step.
pub var frame_start: bool
## Whether a frame ended this step.
pub var frame_end: bool
## Whether the message ended this step.
pub var message_end: bool
# mark: Decoding ==============================================================================
## Streaming frame/message validation and unmasking. State is connection-local;
## input, output and decoder storage must not overlap. Output must be nonempty.
## Failures latch. Control frames may interrupt a fragmented text/binary message.
pub struct WebSocketDecoder:
var from_client: bool
var maximum_frame: u64 = 16777216
var header: u8[14]
var used: usize
var active: bool
var frame: WebSocketFrame
var read: u64
var sequence: WebSocketSequence
var failed: bool
var failure: ErrorCode
## A message decoder for a client or server peer.
pub static func create(from_client: bool, maximum_frame: u64 = 16777216, maximum_message: u64 = 16777216) -> WebSocketDecoder:
return WebSocketDecoder(from_client = from_client, maximum_frame = maximum_frame, sequence = WebSocketSequence(maximum = maximum_message))
## Decode from `input` into `output`.
pub func consume(input: const u8[], output: u8[]) -> WebSocketStep!:
if self.failed:
error(self.failure, "WebSocket decoder has failed")
if output.length == 0:
error(io.invalid_buffer, "WebSocket output buffer must be nonempty")
return self.advance(input, output) catch problem:
self.failed = true
self.failure = problem.code
error(problem.code, problem.message)
## EOF is valid only after a complete close frame. A TCP EOF without one is
## abnormal closure, including between otherwise complete messages.
pub func finish() -> !:
if self.failed:
error(self.failure, "WebSocket decoder has failed")
if self.active or self.used != 0 or not self.sequence.closing:
self.failed = true
self.failure = io.unexpected_eof
error(io.unexpected_eof, "WebSocket ended without a complete close frame")
func advance(input: const u8[], output: u8[]) -> WebSocketStep!:
var at: usize = 0
var started = false
while not self.active and at < input.length:
self.header[self.used] = input[at]
self.used += 1
at += 1
if let frame = try websocket_parse_frame(self.header[..<self.used], self.from_client, self.maximum_frame):
try self.sequence.begin(frame)
self.frame = frame
self.active = true
self.read = 0
self.used = 0
started = true
if not self.active:
return WebSocketStep(consumed = at)
var count = input.length - at
if count > output.length:
count = output.length
if (u64)count > self.frame.length - self.read:
count = (usize)(self.frame.length - self.read)
for index in 0..<count:
let byte = input[at + index]
output[index] = byte ^ self.frame.mask[(usize)((self.read + (u64)index) % 4)] if self.frame.masked else byte
self.read += (u64)count
let ended = self.read == self.frame.length
try self.sequence.payload(self.frame, output[..<count], ended)
if ended:
self.active = false
return WebSocketStep(consumed = at + count, written = count, opcode = self.frame.opcode, frame_start = started, frame_end = ended, message_end = ended and self.frame.final and (u8)self.frame.opcode < 8)
# mark: Encoding ==============================================================================
## Stateful writer: validates message sequencing and UTF-8, masks every client
## frame using fresh OS entropy, and handles short writes with bounded scratch.
## A failure latches because some bytes may already have reached the peer.
pub struct WebSocketEncoder:
var client: bool
var maximum_frame: u64 = 16777216
var sequence: WebSocketSequence
var failed: bool
var failure: ErrorCode
## A message encoder for a client or server peer.
pub static func create(client: bool, maximum_frame: u64 = 16777216, maximum_message: u64 = 16777216) -> WebSocketEncoder:
return WebSocketEncoder(client = client, maximum_frame = maximum_frame, sequence = WebSocketSequence(maximum = maximum_message))
## Write a frame with `opcode` and `payload` to `destination`.
pub func write(destination: Writer, opcode: WebSocketOpcode, payload: const u8[], final: bool = true) -> !:
if self.failed:
error(self.failure, "WebSocket encoder has failed")
self.emit(destination, opcode, payload, final) catch problem:
self.failed = true
self.failure = problem.code
error(problem.code, problem.message)
func emit(destination: Writer, opcode: WebSocketOpcode, payload: const u8[], final: bool) -> !:
_ = try websocket_opcode((u8)opcode)
if (u64)payload.length > self.maximum_frame:
error(websocket_limit, "WebSocket frame exceeds its byte limit")
if (u8)opcode >= 8 and (not final or payload.length > 125):
error(websocket_invalid, "invalid WebSocket control frame")
let frame = WebSocketFrame(opcode = opcode, final = final, length = (u64)payload.length)
try self.sequence.begin(frame)
try self.sequence.payload(frame, payload, true)
var header: u8[14]
header[0] = (u8)opcode | (128 if final else 0)
var count: usize = 2
if payload.length < 126:
header[1] = (u8)payload.length
elif payload.length < 65536:
header[1] = 126
header[2] = (u8)(payload.length >> 8)
header[3] = (u8)payload.length
count = 4
else:
header[1] = 127
for index in 0..<8:
header[2 + index] = (u8)((u64)payload.length >> ((7 - index) * 8))
count = 10
var mask: u8[4]
if self.client:
if websocket_entropy((void*)&mask[0], 4) != 0:
error(failed, "WebSocket masking randomness is unavailable")
header[1] |= 128
memory.copy(header[count..], mask, 4)
count += 4
try io.write_all(destination, header[..<count])
if not self.client:
try io.write_all(destination, payload)
return
var scratch: u8[4096]
var at: usize = 0
while at < payload.length:
let size = payload.length - at if payload.length - at < scratch.length else scratch.length
for index in 0..<size:
scratch[index] = payload[at + index] ^ mask[(at + index) % 4]
try io.write_all(destination, scratch[..<size])
at += size