Implements the WebSocket framing protocol as defined in RFC-6455. More...

#include <framing.hpp>

Inheritance diagram for caf::net::web_socket::framing:

Public Types
using	binary_buffer = std::vector< std::byte >

using	upper_layer_ptr = std::unique_ptr< web_socket::upper_layer >

Public Member Functions
auto &	up () noexcept

const auto &	up () const noexcept

auto &	down () noexcept

const auto &	down () const noexcept

error	start (octet_stream::lower_layer *down) override
	Initializes the upper layer.

void	abort (const error &reason) override
	Called by the lower layer for cleaning up any state in case of an error or when disposed.

ptrdiff_t	consume (byte_span input, byte_span) override
	Consumes bytes from the lower layer.

void	prepare_send () override
	Gives the upper layer an opportunity to add additional data to the output buffer.

bool	done_sending () override
	Queries whether all pending data has been sent.

multiplexer &	mpx () noexcept override
	Returns the multiplexer instance that executes this protocol stack.

bool	can_send_more () const noexcept override
	Queries whether the output device can accept more data straight away.

void	suspend_reading () override
	Stops reading messages until calling `request_messages`.

bool	is_reading () const noexcept override
	Queries whether the lower layer is currently reading from its input device.

void	write_later () override
	Triggers a write callback after the write device signals downstream capacity.

void	shutdown (status code, std::string_view desc) override
	Sends a shutdown message with custom status `code` and `msg` text.

void	request_messages () override
	Pulls messages from the transport until calling `suspend_reading`.

void	begin_binary_message () override
	Begins transmission of a binary message.

byte_buffer &	binary_message_buffer () override
	Returns the buffer for the current binary message.

bool	end_binary_message () override
	Seals the current binary message buffer and ships a new WebSocket frame.

void	begin_text_message () override
	Begins transmission of a text message.

text_buffer &	text_message_buffer () override
	Returns the buffer for the current text message.

bool	end_text_message () override
	Seals the current text message buffer and ships a new WebSocket frame.

virtual error	start (lower_layer *down)=0
	Initializes the upper layer.

virtual ptrdiff_t	consume (byte_span buffer, byte_span delta)=0
	Consumes bytes from the lower layer.

virtual void	prepare_send ()=0
	Gives the upper layer an opportunity to add additional data to the output buffer.

virtual bool	done_sending ()=0
	Queries whether all pending data has been sent.

virtual void	abort (const error &reason)=0
	Called by the lower layer for cleaning up any state in case of an error or when disposed.

Public Member Functions inherited from caf::net::web_socket::lower_layer
virtual void	request_messages ()=0
	Pulls messages from the transport until calling `suspend_reading`.

virtual void	suspend_reading ()=0
	Stops reading messages until calling `request_messages`.

virtual void	begin_binary_message ()=0
	Begins transmission of a binary message.

virtual byte_buffer &	binary_message_buffer ()=0
	Returns the buffer for the current binary message.

virtual bool	end_binary_message ()=0
	Seals the current binary message buffer and ships a new WebSocket frame.

virtual void	begin_text_message ()=0
	Begins transmission of a text message.

virtual text_buffer &	text_message_buffer ()=0
	Returns the buffer for the current text message.

virtual bool	end_text_message ()=0
	Seals the current text message buffer and ships a new WebSocket frame.

void	shutdown () override
	Shuts down any connection or session gracefully.

void	shutdown (const error &reason) override
	Shuts down any connection or session due to an error.

virtual void	shutdown (status code, std::string_view msg)=0
	Sends a shutdown message with custom status `code` and `msg` text.

virtual multiplexer &	mpx () noexcept=0
	Returns the multiplexer instance that executes this protocol stack.

virtual bool	can_send_more () const noexcept=0
	Queries whether the output device can accept more data straight away.

virtual bool	is_reading () const noexcept=0
	Queries whether the lower layer is currently reading from its input device.

virtual void	write_later ()=0
	Triggers a write callback after the write device signals downstream capacity.

virtual void	shutdown ()=0
	Shuts down any connection or session gracefully.

virtual void	shutdown (const error &reason)
	Shuts down any connection or session due to an error.

Static Public Member Functions
static error	validate_closing_payload (const_byte_span payload)
	Checks whether the payload of a closing frame contains a valid status code and an UTF-8 formatted message.

static std::unique_ptr< framing >	make_client (upper_layer_ptr up)
	Creates a new framing protocol for client mode.

static std::unique_ptr< framing >	make_server (upper_layer_ptr up)
	Creates a new framing protocol for server mode.

Public Attributes
bool	mask_outgoing_frames = true
	When set to true, causes the layer to mask all outgoing frames with a randomly chosen masking key (cf.

Static Public Attributes
static constexpr size_t	max_frame_size = INT32_MAX
	Restricts the size of received frames (including header).

static constexpr auto	default_receive_policy = receive_policy::up_to(2048)
	Default receive policy for a new frame.

Detailed Description

Implements the WebSocket framing protocol as defined in RFC-6455.

Member Function Documentation

◆ abort()

void caf::net::web_socket::framing::abort ( const error & reason )

overridevirtual

Called by the lower layer for cleaning up any state in case of an error or when disposed.

Implements caf::net::generic_upper_layer.

◆ begin_binary_message()

void caf::net::web_socket::framing::begin_binary_message ( )

overridevirtual

Begins transmission of a binary message.

Implements caf::net::web_socket::lower_layer.

◆ begin_text_message()

void caf::net::web_socket::framing::begin_text_message ( )

overridevirtual

Begins transmission of a text message.

Implements caf::net::web_socket::lower_layer.

◆ binary_message_buffer()

byte_buffer & caf::net::web_socket::framing::binary_message_buffer ( )

overridevirtual

Returns the buffer for the current binary message.

Must be called between calling begin_binary_message and end_binary_message.

Implements caf::net::web_socket::lower_layer.

◆ can_send_more()

bool caf::net::web_socket::framing::can_send_more ( ) const

overridevirtualnoexcept

Queries whether the output device can accept more data straight away.

Implements caf::net::generic_lower_layer.

◆ consume()

ptrdiff_t caf::net::web_socket::framing::consume	(	byte_span	buffer,
		byte_span	delta
	)

overridevirtual

Consumes bytes from the lower layer.

Parameters

buffer	Available bytes to read.
delta	Bytes that arrived since last calling this function.

Returns: The number of consumed bytes. May be zero if waiting for more input or negative to signal an error.

Implements caf::net::octet_stream::upper_layer.

◆ done_sending()

bool caf::net::web_socket::framing::done_sending ( )

overridevirtual

Queries whether all pending data has been sent.

The lower calls this function to decide whether it has to wait for write events on the socket.

Implements caf::net::generic_upper_layer.

◆ end_binary_message()

bool caf::net::web_socket::framing::end_binary_message ( )

overridevirtual

Seals the current binary message buffer and ships a new WebSocket frame.

Implements caf::net::web_socket::lower_layer.

◆ end_text_message()

bool caf::net::web_socket::framing::end_text_message ( )

overridevirtual

Seals the current text message buffer and ships a new WebSocket frame.

Implements caf::net::web_socket::lower_layer.

◆ is_reading()

bool caf::net::web_socket::framing::is_reading ( ) const

overridevirtualnoexcept

Queries whether the lower layer is currently reading from its input device.

Implements caf::net::generic_lower_layer.

◆ mpx()

multiplexer & caf::net::web_socket::framing::mpx ( )

overridevirtualnoexcept

Returns the multiplexer instance that executes this protocol stack.

Implements caf::net::generic_lower_layer.

◆ prepare_send()

void caf::net::web_socket::framing::prepare_send ( )

overridevirtual

Gives the upper layer an opportunity to add additional data to the output buffer.

Implements caf::net::generic_upper_layer.

◆ request_messages()

void caf::net::web_socket::framing::request_messages ( )

overridevirtual

Pulls messages from the transport until calling suspend_reading.

Implements caf::net::web_socket::lower_layer.

◆ shutdown()

void caf::net::web_socket::framing::shutdown	(	status	code,
		std::string_view	msg
	)

overridevirtual

Sends a shutdown message with custom status code and msg text.

Implements caf::net::web_socket::lower_layer.

◆ start()

error caf::net::web_socket::framing::start ( octet_stream::lower_layer * down )

overridevirtual

Initializes the upper layer.

Parameters

down	A pointer to the lower layer that remains valid for the lifetime of the upper layer.

Implements caf::net::octet_stream::upper_layer.

◆ suspend_reading()

void caf::net::web_socket::framing::suspend_reading ( )

overridevirtual

Stops reading messages until calling request_messages.

Implements caf::net::web_socket::lower_layer.

◆ text_message_buffer()

text_buffer & caf::net::web_socket::framing::text_message_buffer ( )

overridevirtual

Returns the buffer for the current text message.

Must be called between calling begin_text_message and end_text_message.

Implements caf::net::web_socket::lower_layer.

◆ validate_closing_payload()

error caf::net::web_socket::framing::validate_closing_payload ( const_byte_span payload )

static

Checks whether the payload of a closing frame contains a valid status code and an UTF-8 formatted message.

Returns: A default constructed error if the payload is valid, error kind otherwise.

◆ write_later()

void caf::net::web_socket::framing::write_later ( )

overridevirtual

Triggers a write callback after the write device signals downstream capacity.

Does nothing if this layer is already writing.

Implements caf::net::generic_lower_layer.

Member Data Documentation

◆ mask_outgoing_frames

bool caf::net::web_socket::framing::mask_outgoing_frames = true

When set to true, causes the layer to mask all outgoing frames with a randomly chosen masking key (cf.

RFC 6455, Section 5.3). Servers may set this to false, whereas clients are required to always mask according to the standard.

The documentation for this class was generated from the following files:

libcaf_net/caf/net/web_socket/framing.hpp
libcaf_net/caf/net/web_socket/framing.cpp

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Detailed Description

Member Function Documentation

◆ abort()

◆ begin_binary_message()

◆ begin_text_message()

◆ binary_message_buffer()

◆ can_send_more()

◆ consume()

◆ done_sending()

◆ end_binary_message()

◆ end_text_message()

◆ is_reading()

◆ mpx()

◆ prepare_send()

◆ request_messages()

◆ shutdown()

◆ start()

◆ suspend_reading()

◆ text_message_buffer()

◆ validate_closing_payload()

◆ write_later()

Member Data Documentation

◆ mask_outgoing_frames