simple_websocket

API Reference

WS_FRAME Class

Represents a single WebSocket frame with encoding/decoding capabilities.

Creation Procedures

make_text (a_text: STRING; a_is_fin: BOOLEAN)

create frame.make_text ("Hello", True)

Create a text frame with UTF-8 payload.

Contracts

require: text_not_void: a_text /= Void
ensure: is_text: is_text
ensure: opcode_set: opcode = Opcode_text

make_binary (a_data: ARRAY [NATURAL_8]; a_is_fin: BOOLEAN)

create frame.make_binary (byte_array, True)

Create a binary frame with raw byte payload.

Contracts

require: data_not_void: a_data /= Void
ensure: is_binary: is_binary
ensure: opcode_set: opcode = Opcode_binary

make_close (a_code: INTEGER; a_reason: STRING)

create frame.make_close (1000, "Normal closure")

Create a close frame with status code and reason.

Contracts

require: valid_code: a_code >= 1000 and a_code <= 4999
require: reason_not_void: a_reason /= Void
ensure: is_close: is_close
ensure: is_control: is_control

make_ping / make_pong

create frame.make_ping
create frame.make_pong

Create ping/pong control frames for heartbeat.

Contracts

ensure: is_control: is_control
ensure: is_fin: is_fin

Status Queries

Feature Type Description
is_fin BOOLEAN Is this the final fragment?
is_text BOOLEAN Is this a text frame?
is_binary BOOLEAN Is this a binary frame?
is_close BOOLEAN Is this a close frame?
is_ping BOOLEAN Is this a ping frame?
is_pong BOOLEAN Is this a pong frame?
is_control BOOLEAN Is this a control frame?
opcode INTEGER Frame opcode (0-15)
payload_length INTEGER Payload byte count

Payload Access

text_payload: STRING

text := frame.text_payload

Get payload as UTF-8 string (for text frames).

close_code: INTEGER

code := frame.close_code

Get close status code (for close frames).

close_reason: STRING

reason := frame.close_reason

Get close reason text (for close frames).

Operations

set_mask (a_key: ARRAY [NATURAL_8])

frame.set_mask (<<0x12, 0x34, 0x56, 0x78>>)

Set 4-byte mask key for client-to-server frames.

Contracts

require: key_not_void: a_key /= Void
require: key_size: a_key.count = 4

to_bytes: ARRAY [NATURAL_8]

bytes := frame.to_bytes

Encode frame to wire format bytes.

Contracts

ensure: result_not_void: Result /= Void
ensure: minimum_size: Result.count >= 2

Constants

Constant Value Description
Opcode_continuation 0 Continuation frame
Opcode_text 1 Text frame
Opcode_binary 2 Binary frame
Opcode_close 8 Close frame
Opcode_ping 9 Ping frame
Opcode_pong 10 Pong frame

WS_FRAME_PARSER Class

Streaming parser for reading frames from byte streams.

make

create parser.make

Initialize parser with empty buffer.

add_bytes (a_bytes: ARRAY [NATURAL_8])

parser.add_bytes (received_data)

Add bytes to parse buffer.

Contracts

require: bytes_not_void: a_bytes /= Void
ensure: bytes_added: buffer.count >= old buffer.count

parse: BOOLEAN

if parser.parse then ...

Attempt to parse a frame. Returns True if successful.

Contracts

ensure: frame_if_success: Result implies has_frame

has_frame: BOOLEAN

if parser.has_frame then ...

Is a complete frame available?

last_frame: detachable WS_FRAME

if attached parser.last_frame as f then ...

Get the last parsed frame.

reset

parser.reset

Clear parser state and buffer.

WS_HANDSHAKE Class

WebSocket opening handshake for client and server.

Client Features

create_client_request (a_host, a_path: STRING): STRING

request := handshake.create_client_request ("example.com", "/chat")

Generate HTTP upgrade request for client.

Contracts

require: host_not_void: a_host /= Void
require: path_not_void: a_path /= Void
ensure: key_generated: sec_websocket_key /= Void

validate_server_response (a_response: STRING): BOOLEAN

if handshake.validate_server_response (response) then ...

Validate server's handshake response.

Server Features

parse_client_request (a_request: STRING): BOOLEAN

if handshake.parse_client_request (request) then ...

Parse incoming client handshake request.

Contracts

require: request_not_void: a_request /= Void

create_server_response: STRING

response := handshake.create_server_response

Generate HTTP 101 response for server.

Contracts

require: valid_request: is_valid
ensure: has_101: Result.has_substring ("101")

Status

Feature Type Description
is_valid BOOLEAN Was handshake successful?
last_error STRING Error message if failed
sec_websocket_key detachable STRING The Sec-WebSocket-Key value
requested_path detachable STRING Requested URI path

WS_MESSAGE Class

High-level message abstraction with fragmentation support.

make_text (a_text: STRING)

create msg.make_text ("Hello")

Create a text message.

make_binary (a_data: ARRAY [NATURAL_8])

create msg.make_binary (byte_array)

Create a binary message.

to_frame: WS_FRAME

frame := msg.to_frame

Convert to a single frame (for small messages).

to_frames (a_max_size: INTEGER): ARRAYED_LIST [WS_FRAME]

frames := msg.to_frames (1024)

Split into multiple frames with maximum payload size.

Contracts

require: positive_size: a_max_size > 0
ensure: at_least_one: Result.count >= 1
ensure: last_is_fin: Result.last.is_fin