pharpend/fewd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

start renaming

Browse Source
This commit is contained in:
Peter Harpending
2025-10-31 12:33:11 -07:00
parent 4e48d6b40b
commit e12466d5f2
5 changed files with 24 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/qhl_ws.erl
+807
View File
@@ -0,0 +1,807 @@
% @doc websockets
%
% ref: https://datatracker.ietf.org/doc/html/rfc6455
-module(qhl_ws).
-export_type([
opcode/0,
frame/0,
ws_msg/0
]).
-export([
%% time units
ms/0, sec/0, min/0, hr/0, day/0,
%% porcelain
handshake/1,
recv/3, recv/4,
send/2
]).
-include("http.hrl").
-define(MAX_PAYLOAD_SIZE, ((1 bsl 63) - 1)).
%% Frames
%% https://datatracker.ietf.org/doc/html/rfc6455#section-5.2
-type opcode() :: continuation
| text
| binary
| close
| ping
| pong.
-record(frame,
{fin = none :: none | boolean(),
rsv = none :: none | <<_:3>>,
opcode = none :: none | opcode(),
mask = none :: none | boolean(),
payload_length = none :: none | non_neg_integer(),
masking_key = none :: none | <<>> | <<_:32>>,
payload = none :: none | binary()}).
-type frame() :: #frame{}.
%% porcelain messages
-type ws_msg() :: {text, Payload :: iodata()}
| {binary, Payload :: iodata()}
| {close, Payload :: iodata()}
| {ping, Payload :: iodata()}
| {pong, Payload :: iodata()}.
%% time units
ms() -> 1.
sec() -> 1_000.
min() -> 60*sec().
hr() -> 60*min().
day() -> 24*hr().
-spec handshake(Req) -> Result
when Req :: request(),
Result :: {ok, DraftResponse}
| {error, Reason},
DraftResponse :: response(),
Reason :: any().
% @doc
% This mostly just validates that all the 't's have been dotted and 'i's have
% been crossed.
%
% given an HTTP request:
%
% - if it is NOT a valid websocket handshake request, error
% - if it IS a valid websocket handshake request, form an initial candidate
% response record with the following fields:
%
% code = 101
% slogan = "Switching Protocols"
% headers = [{"Sec-WebSocket-Accept", ChallengeResponse},
% {"Connection", "Upgrade"},
% {"Upgrade", "websocket"}].
%
% YOU are responsible for dealing with any cookie logic, authentication logic,
% validating the Origin field, implementing cross-site-request-forgery, adding
% the retarded web date, rendering the response, sending it over the socket,
% etc.
%
% The returned ClientExtensions is the result of joining the
% <<"sec-websocket-extensions">> fields with ", "
%
% quoth section 9.1: https://datatracker.ietf.org/doc/html/rfc6455#section-9.1
%
% > Note that like other HTTP header fields, this header field MAY be
% > split or combined across multiple lines. Ergo, the following are
% > equivalent:
% >
% > Sec-WebSocket-Extensions: foo
% > Sec-WebSocket-Extensions: bar; baz=2
% >
% > is exactly equivalent to
% >
% > Sec-WebSocket-Extensions: foo, bar; baz=2
%
% Nobody actually uses extensions, so how you choose to parse this is on you.
handshake(R = #request{method = get, headers = Hs}) ->
%% downcase the headers because have to match on them
handshake2(R#request{headers = casefold_headers(Hs)});
handshake(_) ->
{error, bad_method}.
-spec casefold_headers(Headers) -> DowncaseHeaders
when Headers :: #{Key := Value},
Key :: binary(),
Value :: binary(),
DowncaseHeaders :: Headers.
% @private
% casefold all the keys in the header because they're case insensitive
casefold_headers(Headers) ->
Downcase =
fun({K, V}) ->
NewKey = unicode:characters_to_binary(string:casefold(K)),
{NewKey, V}
end,
maps:from_list(lists:map(Downcase, maps:to_list(Headers))).
-spec handshake2(DowncaseReq) -> Result
when DowncaseReq :: request(),
Result :: {ok, DraftResponse}
| {error, Reason},
DraftResponse :: response(),
Reason :: any().
% @private
% we may assume (WMA) method=get and headers have all been downcased
handshake2(#request{headers = DowncaseHeaders}) ->
% headers MUST contain fields:
% sec-websocket-key: _ % arbitrary
% sec-websocket-version: 13 % must be EXACTLY 13
% connection: Upgrade % must include the token "Upgrade"
% upgrade: websocket % must include the token "websocket"
MaybeResponseToken = validate_headers(DowncaseHeaders),
case MaybeResponseToken of
{ok, ResponseToken} ->
DraftResponse =
#response{code = 101,
slogan = "Switching Protocols",
headers = [{"Sec-WebSocket-Accept", ResponseToken},
{"Connection", "Upgrade"},
{"Upgrade", "websocket"}]},
{ok, DraftResponse};
Error ->
Error
end.
-spec validate_headers(HeadersMap) -> Result
when HeadersMap :: #{Key :: binary() := Val :: binary()},
Result :: {ok, ResponseToken}
| {error, Reason},
ResponseToken :: binary(),
Reason :: any().
% @private
% validate:
% Upgrade: websocket
% Connection: Upgrade
% Sec-WebSocket-Version: 13
validate_headers(#{<<"sec-websocket-key">> := ChallengeToken,
<<"sec-websocket-version">> := WS_Vsn,
<<"connection">> := Connection,
<<"upgrade">> := Upgrade}) ->
BadUpgrade = bad_upgrade(Upgrade),
BadConnection = bad_connection(Connection),
BadVersion = bad_version(WS_Vsn),
if
BadUpgrade -> {error, {bad_upgrade, Upgrade}};
BadConnection -> {error, {bad_connection, Connection}};
BadVersion -> {error, {bad_version, WS_Vsn}};
true -> {ok, response_token(ChallengeToken)}
end;
validate_headers(_) ->
{error, bad_request}.
-spec bad_upgrade(binary()) -> true | false.
% @private string must include "websocket" as a token
bad_upgrade(Str) ->
case string:find(Str, "websocket") of
nomatch -> true;
_ -> false
end.
-spec bad_connection(binary()) -> true | false.
% @private string must include "Upgrade" as a token
bad_connection(Str) ->
case string:find(Str, "Upgrade") of
nomatch -> true;
_ -> false
end.
-spec bad_version(binary()) -> true | false.
% @private version must be EXACTLY <<"13">>
bad_version(<<"13">>) -> false;
bad_version(_) -> true.
-spec response_token(binary()) -> binary().
% @doc
% Quoth the RFC:
%
% > Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
% >
% > For this header field, the server has to take the value (as present
% > in the header field, e.g., the base64-encoded [RFC4648] version minus
% > any leading and trailing whitespace) and concatenate this with the
% > Globally Unique Identifier (GUID, [RFC4122]) "258EAFA5-E914-47DA-
% > 95CA-C5AB0DC85B11" in string form, which is unlikely to be used by
% > network endpoints that do not understand the WebSocket Protocol. A
% > SHA-1 hash (160 bits) [FIPS.180-3], base64-encoded (see Section 4 of
% > [RFC4648]), of this concatenation is then returned in the server's
% > handshake.
% >
% > Concretely, if as in the example above, the |Sec-WebSocket-Key|
% > header field had the value "dGhlIHNhbXBsZSBub25jZQ==", the server
% > would concatenate the string "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
% > to form the string "dGhlIHNhbXBsZSBub25jZQ==258EAFA5-E914-47DA-95CA-
% > C5AB0DC85B11". The server would then take the SHA-1 hash of this,
% > giving the value 0xb3 0x7a 0x4f 0x2c 0xc0 0x62 0x4f 0x16 0x90 0xf6
% > 0x46 0x06 0xcf 0x38 0x59 0x45 0xb2 0xbe 0xc4 0xea. This value is
% > then base64-encoded (see Section 4 of [RFC4648]), to give the value
% > "s3pPLMBiTxaQ9kYGzzhZRbK+xOo=". This value would then be echoed in
% > the |Sec-WebSocket-Accept| header field.
response_token(ChallengeToken) when is_binary(ChallengeToken) ->
MagicString = <<"258EAFA5-E914-47DA-95CA-C5AB0DC85B11">>,
ConcatString = <<ChallengeToken/binary, MagicString/binary>>,
Sha1 = crypto:hash(sha, ConcatString),
base64:encode(Sha1).
-spec recv(Socket, Received, TimeoutMS) -> Result
when Socket :: gen_tcp:socket(),
Received :: binary(),
TimeoutMS :: non_neg_integer(),
Result :: {ok, Message, Frames, Remainder}
| {error, Reason},
Message :: ws_msg(),
Frames :: [frame()],
Remainder :: binary(),
Reason :: any().
% @doc
% Equivalent to recv(Socket, Received, [])
recv(Sock, Recv, TimeoutMS) ->
recv(Sock, Recv, TimeoutMS, []).
-spec recv(Socket, Received, TimeoutMS, Frames) -> Result
when Socket :: gen_tcp:socket(),
Received :: binary(),
TimeoutMS :: non_neg_integer(),
Frames :: [frame()],
Result :: {ok, Message, NewFrames, Remainder}
| {error, Reason},
Message :: ws_msg(),
NewFrames :: Frames,
Remainder :: binary(),
Reason :: any().
% @doc
% Pull a message off the socket
recv(Sock, Received, Timeout, Frames) ->
case maybe_pop_msg(Frames) of
{ok, Message, NewFrames} ->
{ok, Message, NewFrames, Received};
incomplete ->
case recv_frame(#frame{}, Sock, Received, Timeout) of
{ok, Frame, NewReceived} ->
NewFrames = [Frame | Frames],
recv(Sock, NewReceived, Timeout, NewFrames);
Error ->
Error
end;
Error ->
Error
end.
-spec maybe_pop_msg(Frames) -> Result
when Frames :: [frame()],
Result :: {ok, Message, NewFrames}
| incomplete
| {error, Reason},
Message :: ws_msg(),
NewFrames :: Frames,
Reason :: any().
% @private
% try to parse the stack of frames into a single message
%
% ignores RSV bits
% @end
maybe_pop_msg([]) ->
incomplete;
% case 1: control frames
% note that maybe_control_msg checks that the fin bit is true
%
% meaning if the client sends a malicious control frame with fin=false, that
% error will be caught in maybe_control_msg
maybe_pop_msg([Frame = #frame{opcode = ControlOpcode} | Frames])
when (ControlOpcode =:= close)
orelse (ControlOpcode =:= ping)
orelse (ControlOpcode =:= pong) ->
case maybe_control_msg(Frame) of
{ok, Msg} -> {ok, Msg, Frames};
Error -> Error
end;
% case 2: messages
% finished message in a single frame, just pull here
maybe_pop_msg([Frame = #frame{fin = true,
opcode = DataOpcode,
mask = Mask,
masking_key = Key,
payload = Payload}
| Rest])
when DataOpcode =:= text; DataOpcode =:= binary ->
case maybe_unmask(Frame, Mask, Key, Payload) of
{ok, Unmasked} ->
Message = {DataOpcode, Unmasked},
{ok, Message, Rest};
Error ->
Error
end;
% end of a long message
maybe_pop_msg(Frames = [#frame{fin = true,
opcode = continuation} | _]) ->
maybe_long_data_msg(Frames);
% unfinished message, say we need more
maybe_pop_msg([#frame{fin = false,
opcode = continuation}
| _]) ->
incomplete;
% wtf... this case should be impossible
maybe_pop_msg([Frame | _]) ->
{error, {wtf_frame, Frame}}.
-spec maybe_long_data_msg(Frames) -> Result
when Frames :: [frame()],
Result :: {ok, Message, NewFrames}
| {error, Reason},
Message :: ws_msg(),
NewFrames :: Frames,
Reason :: any().
% @private
% assumes:
% 1. top of stack is a finished frame
% 2. top opcode is continuation
% 3. the stack corresponds to a linear sequence of frames all corresponding to
% one message, until we get to the leading frame of the message, which must
% have opcode text|binary
%
% the reason we can make this assumption is because anterior in the call
% chain is recv/3, which eagerly consumes control messages
%
% meaning if we encounter a control frame in the middle here, we can assume
% there is some sort of bug
%
% TODO: I am NOT enforcing that the data message consumes the entire stack of
% frames. Given that the context here is eager consumption, this might be a
% point of enforcement. Need to think about this.
% @end
maybe_long_data_msg(Frames) ->
mldm(Frames, Frames, <<>>).
% general case: decode the payload in this frame
mldm(OrigFrames, [Frame | Rest], Acc) ->
Opcode = Frame#frame.opcode,
Mask = Frame#frame.mask,
Key = Frame#frame.masking_key,
Payload = Frame#frame.payload,
case maybe_unmask(Frame, Mask, Key, Payload) of
{ok, Unmasked} ->
NewAcc = <<Unmasked/binary, Acc/binary>>,
case Opcode of
continuation -> mldm(OrigFrames, Rest, NewAcc);
text -> {ok, {text, NewAcc}, Rest};
binary -> {ok, {binary, NewAcc}, Rest};
_ -> {error, {illegal_data_frame, Frame, OrigFrames, Acc}}
end;
Error ->
Error
end;
% out of frames
mldm(OrigFrames, [], Acc) ->
{error, {no_start_frame, Acc, OrigFrames}}.
-spec maybe_control_msg(Frame) -> Result
when Frame :: frame(),
Result :: {ok, Message}
| {error, Reason},
Message :: ws_msg(),
Reason :: any().
% @private
% assume the frame is a control frame, validate it, and unmask the payload
%
% TODO: this doesn't enforce that messages from the client HAVE to be masked,
% which strictly speaking is part of the protocol.
maybe_control_msg(F = #frame{fin = true,
opcode = Opcode,
mask = Mask,
payload_length = Len,
masking_key = Key,
payload = Payload})
when ((Opcode =:= close) orelse (Opcode =:= ping) orelse (Opcode =:= pong))
andalso (Len =< 125) ->
case maybe_unmask(F, Mask, Key, Payload) of
{ok, UnmaskedPayload} ->
Msg = {Opcode, UnmaskedPayload},
{ok, Msg};
Error ->
Error
end;
maybe_control_msg(F) ->
{error, {illegal_frame, F}}.
-spec maybe_unmask(Frame, Mask, Key, Payload) -> Result
when Frame :: frame(),
Mask :: boolean(),
Key :: <<>> | <<_:32>>,
Payload :: binary(),
Result :: {ok, Unmasked}
| {error, Reason},
Unmasked :: binary(),
Reason :: any().
% @private
% unmask the payload
% @end
% eliminate invalid pairs of {mask, masking_key}
maybe_unmask(_, true, <<Key:4/bytes>>, Payload) -> {ok, mask_unmask(Key, Payload)};
maybe_unmask(_, false, <<>>, Payload) -> {ok, Payload};
maybe_unmask(F, true, <<>>, _) -> {error, {illegal_frame, F}};
maybe_unmask(F, false, <<_:4/bytes>>, _) -> {error, {illegal_frame, F}}.
%% invertible
%% see: https://datatracker.ietf.org/doc/html/rfc6455#section-5.3
mask_unmask(Key = <<_:4/bytes>>, Payload) ->
mu(Key, Key, Payload, <<>>).
% essentially this is a modular zipWith xor of the masking key with the payload
mu(Key, <<KeyByte:8, KeyRest/binary>>, <<PayloadByte:8, PayloadRest/binary>>, Acc) ->
NewByte = KeyByte bxor PayloadByte,
NewAcc = <<Acc/binary, NewByte:8>>,
mu(Key, KeyRest, PayloadRest, NewAcc);
% this is the case where we need to refresh the active key
mu(Key, <<>>, Payload, Acc) ->
mu(Key, Key, Payload, Acc);
% done
mu(_, _, <<>>, Acc) ->
Acc.
-spec recv_frame(Parsed, Socket, Received, TimeoutMS) -> Result
when Parsed :: frame(),
Socket :: gen_tcp:socket(),
Received :: bitstring(),
TimeoutMS :: non_neg_integer(),
Result :: {ok, frame(), Remainder}
| {error, Reason},
Remainder :: bitstring(),
Reason :: any().
% @private
% parse a single frame off the socket
% @end
%% frame: 1 bit
recv_frame(Frame = #frame{fin = none}, Sock, <<FinBit:1, Rest/bits>>, Timeout) ->
NewFin =
case FinBit of
0 -> false;
1 -> true
end,
NewFrame = Frame#frame{fin = NewFin},
recv_frame(NewFrame, Sock, Rest, Timeout);
recv_frame(Frame = #frame{fin = none}, Sock, Received = <<>>, Timeout) ->
recv_frame_await(Frame, Sock, Received, Timeout);
%% rsv: 3 bits
recv_frame(Frame = #frame{rsv = none}, Sock, <<RSV:3/bits, Rest/bits>>, Timeout) ->
NewFrame = Frame#frame{rsv = RSV},
recv_frame(NewFrame, Sock, Rest, Timeout);
recv_frame(Frame = #frame{rsv = none}, Sock, Received, Timeout) ->
recv_frame_await(Frame, Sock, Received, Timeout);
%% opcode: 4 bits
recv_frame(Frame = #frame{opcode = none}, Sock, <<OpcodeInt:4, Rest/bits>>, Timeout) ->
Opcode =
case OpcodeInt of
0 -> continuation;
1 -> text;
2 -> binary;
8 -> close;
9 -> ping;
10 -> pong;
_ -> bad_opcode
end,
case Opcode of
bad_opcode ->
{error, {bad_opcode, OpcodeInt}};
_ ->
NewFrame = Frame#frame{opcode = Opcode},
recv_frame(NewFrame, Sock, Rest, Timeout)
end;
recv_frame(Frame = #frame{opcode = none}, Sock, Received, Timeout) ->
recv_frame_await(Frame, Sock, Received, Timeout);
%% mask: 1 bit
recv_frame(Frame = #frame{mask = none}, Sock, <<MaskBit:1, Rest/bits>>, Timeout) ->
NewMask =
case MaskBit of
0 -> false;
1 -> true
end,
NewFrame = Frame#frame{mask = NewMask},
recv_frame(NewFrame, Sock, Rest, Timeout);
recv_frame(Frame = #frame{mask = none}, Sock, Received = <<>>, Timeout) ->
recv_frame_await(Frame, Sock, Received, Timeout);
%% payload length: variable (yay)
% first case: short length 0..125
recv_frame(Frame = #frame{payload_length = none}, Sock, <<Len:7, Rest/bits>>, Timeout) when Len =< 125 ->
NewFrame = Frame#frame{payload_length = Len},
recv_frame(NewFrame, Sock, Rest, Timeout);
% second case: 126 -> 2 bytes to follow
recv_frame(Frame = #frame{payload_length = none}, Sock, <<126:7, Len:16, Rest/bits>>, Timeout) ->
NewFrame = Frame#frame{payload_length = Len},
recv_frame(NewFrame, Sock, Rest, Timeout);
% third case: 127 -> 8 bytes to follow
% bytes must start with a 0 bit
recv_frame(_Frame = #frame{payload_length = none}, _Sock, <<127:7, 1:1, _/bits>>, _Timeout) ->
{error, {illegal_frame, "payload length >= 1 bsl 63"}};
% 127, next is a legal length, continue
recv_frame(Frame = #frame{payload_length = none}, Sock, <<127:7, Len:64, Rest/bits>>, Timeout) ->
NewFrame = Frame#frame{payload_length = Len},
recv_frame(NewFrame, Sock, Rest, Timeout);
% otherwise wait
recv_frame(Frame = #frame{payload_length = none}, Sock, Received, Timeout) ->
recv_frame_await(Frame, Sock, Received, Timeout);
%% masking key: 0 or 4 bits
% not expecting a masking key, fill in that field here
recv_frame(Frame = #frame{mask = false, masking_key = none}, Sock, Received, Timeout) ->
NewFrame = Frame#frame{masking_key = <<>>},
recv_frame(NewFrame, Sock, Received, Timeout);
% expecting one
recv_frame(Frame = #frame{mask = true, masking_key = none}, Sock, <<Key:4/bytes, Rest/bits>>, Timeout) ->
NewFrame = Frame#frame{masking_key = Key},
recv_frame(NewFrame, Sock, Rest, Timeout);
% not found
recv_frame(Frame = #frame{mask = true, masking_key = none}, Sock, Received, Timeout) ->
recv_frame_await(Frame, Sock, Received, Timeout);
%% payload
recv_frame(Frame = #frame{payload_length = Len, payload = none}, Sock, Received, Timeout) when is_integer(Len) ->
case Received of
% we have enough bytes
<<Payload:Len/bytes, Rest/bits>> ->
FinalFrame = Frame#frame{payload = Payload},
{ok, FinalFrame, Rest};
% we do not have enough bytes
_ ->
recv_frame_await(Frame, Sock, Received, Timeout)
end.
%% factoring this out into a function to reduce repetition
recv_frame_await(Frame, Sock, Received, Timeout) ->
case inet:setopts(Sock, [{active, once}]) of
ok ->
receive
{tcp, Sock, Bin} -> recv_frame(Frame, Sock, <<Received/bits, Bin/binary>>, Timeout);
{tcp_closed, Sock} -> {error, tcp_closed};
{tcp_error, Sock, Reason} -> {error, {tcp_error, Reason}}
after Timeout ->
{error, timeout}
end;
{error, Reason} ->
{error, {inet, Reason}}
end.
-spec send(Socket, Message) -> Result
when Socket :: gen_tcp:socket(),
Message :: ws_msg(),
Result :: ok
| {error, Reason},
Reason :: any().
% @doc
% send message to client over Socket. handles frame nonsense
%
% max payload size is 2^63 - 1 bytes
% @end
send(Socket, {Type, Payload}) ->
BPayload = payload_to_binary(Payload),
Frame = message_to_frame(Type, BPayload),
send_frame(Socket, Frame).
payload_to_binary(Bin) when is_binary(Bin) -> Bin;
payload_to_binary(X) -> unicode:characters_to_binary(X).
% data messages
message_to_frame(Data, Payload)
when ((Data =:= text) orelse (Data =:= binary)),
is_binary(Payload),
(byte_size(Payload) =< ?MAX_PAYLOAD_SIZE) ->
#frame{fin = true,
opcode = Data,
payload_length = byte_size(Payload),
payload = Payload};
message_to_frame(Control, Payload)
when ((Control =:= close) orelse (Control =:= ping) orelse (Control =:= pong)),
is_binary(Payload),
(byte_size(Payload) =< 125) ->
#frame{fin = true,
opcode = Control,
payload_length = byte_size(Payload),
payload = Payload}.
-spec send_frame(Sock, Frame) -> Result
when Sock :: gen_tcp:socket(),
Frame :: frame(),
Result :: ok
| {error, Reason},
Reason :: tcp_error().
% @private
% send a frame on the socket
% @end
send_frame(Sock, Frame) ->
Binary = render_frame(Frame),
gen_tcp:send(Sock, Binary).
-spec render_frame(Frame) -> Binary
when Frame :: frame(),
Binary :: binary().
% @private
% render a frame
%
% All fields in a `#frame{}` record have default values of `none`.
%
% ```erlang
% -record(frame,
% {fin = none :: none | boolean(),
% rsv = none :: none | <<_:3>>,
% opcode = none :: none | opcode(),
% mask = none :: none | boolean(),
% payload_length = none :: none | non_neg_integer(),
% masking_key = none :: none | <<>> | <<_:32>>,
% payload = none :: none | binary()}).
% ```
%
% Given a value of `none`, some of these fields are inferred, some cannot be
% inferred.
%
% Inference cases:
%
% ```
% rsv = none -> <<0:3>>
% mask = none -> false
% masking_key = none -> <<>>
% payload_length = none -> byte_size(Payload)
% ```
%
% Non-inference:
%
% ```
% fin
% opcode
% payload
% ```
% @end
render_frame(#frame{fin = Fin,
rsv = RSV,
opcode = Opcode,
mask = Mask,
payload_length = Len,
masking_key = MaskingKey,
payload = Payload}) ->
BFin =
case Fin of
true -> <<1:1>>;
false -> <<0:1>>
end,
BRSV =
case RSV of
none -> <<0:3>>;
<<_:3>> -> RSV;
_ -> error({illegal_rsv, RSV})
end,
BOpcode =
case Opcode of
continuation -> << 0:4>>;
text -> << 1:4>>;
binary -> << 2:4>>;
close -> << 8:4>>;
ping -> << 9:4>>;
pong -> <<10:4>>
end,
BoolMask =
case Mask of
none -> false;
false -> false;
true -> true
end,
BMask =
case BoolMask of
true -> <<1:1>>;
false -> <<0:1>>
end,
IntPayloadLength =
case Len of
none -> byte_size(Payload);
_ -> Len
end,
BPayloadLength = render_payload_length(IntPayloadLength),
BMaskingKey =
case {BoolMask, MaskingKey} of
{false, none} -> <<>>;
{false, <<>>} -> <<>>;
{true, <<BKey:4/bytes>>} -> BKey;
{false, _} -> error({not_masking_but_have_masking_key, {Mask, MaskingKey}});
{true, _} -> error({illegal_masking_key, MaskingKey})
end,
% failure case here is same as error case just above, so no need to worry
% about cryptic "illegal frame" message
%
% masking = unmasking, so `maybe_unmask` is a bit of a misnomer
{ok, BPayload} = maybe_unmask(#frame{}, BoolMask, BMaskingKey, Payload),
<<BFin/bits,
BRSV/bits,
BOpcode/bits,
BMask/bits,
BPayloadLength/bits,
BMaskingKey/binary,
BPayload/binary>>.
-spec render_payload_length(non_neg_integer()) -> binary().
% @private
% > Payload length: 7 bits, 7+16 bits, or 7+64 bits
% >
% > The length of the "Payload data", in bytes: if 0-125, that is the
% > payload length. If 126, the following 2 bytes interpreted as a
% > 16-bit unsigned integer are the payload length. If 127, the
% > following 8 bytes interpreted as a 64-bit unsigned integer (the
% > most significant bit MUST be 0) are the payload length. Multibyte
% > length quantities are expressed in network byte order. Note that
% > in all cases, the minimal number of bytes MUST be used to encode
% > the length, for example, the length of a 124-byte-long string
% > can't be encoded as the sequence 126, 0, 124. The payload length
% > is the length of the "Extension data" + the length of the
% > "Application data". The length of the "Extension data" may be
% > zero, in which case the payload length is the length of the
% > "Application data".
render_payload_length(Len) when 0 =< Len, Len =< 125 ->
<<Len:7>>;
render_payload_length(Len) when 126 =< Len, Len =< 2#1111_1111_1111_1111 ->
<<126:7, Len:16>>;
render_payload_length(Len) when (1 bsl 16) =< Len, Len =< ?MAX_PAYLOAD_SIZE ->
<<127:7, Len:64>>.