Detailed Description

WebRtcWireStream is a concrete implementation of WireStream that uses WebRTC for communication.

It supports sending and receiving ActionEngine wire messages over a WebRTC data channel. This class is designed to be used in both client and server contexts, allowing for flexible communication patterns.

#include <actionengine/net/webrtc/wire_stream.h>

Inheritance diagram for act::net::WebRtcWireStream:

Public Member Functions
absl::Status	Send (WireMessage message) override

absl::StatusOr< std::optional< WireMessage > >	Receive (absl::Duration timeout) override

absl::Status	Start () override

absl::Status	Accept () override

void	HalfClose () override

void	Abort () override

absl::Status	GetStatus () const override

std::string	GetId () const override

const void *absl_nullable	GetImpl () const override

Public Member Functions inherited from act::WireStream
template<typename T>
auto	GetImpl () const -> T *

Member Function Documentation

◆ Abort()

void act::net::WebRtcWireStream::Abort ( )

overridevirtual

Aborts the stream.

This is used to terminate the stream immediately with an "error" state. For example, the result of Receive() following an Abort() call by either side should be an error status, indicating that the stream is no longer usable, and not an empty optional.

Implements act::WireStream.

◆ Accept()

absl::Status act::net::WebRtcWireStream::Accept ( )

inlineoverridevirtual

Accepts the stream on the server side.

Clients should not call this method. It is intended to be called by the server to accept a stream that has been initiated by a client. Implementations that differentiate between client and server streams are allowed to return an error if this method is called on a client, or even to perform a hard termination of the process, as such a call is considered a misuse of the API.

Some implementations may not require this method, in which case they can return an OK status without doing anything.

Returns: An OK status if the stream is successfully accepted, or an error status if the stream cannot be accepted (e.g., if it is already accepted, or some underlying negotiation failed).

Implements act::WireStream.

◆ GetId()

std::string act::net::WebRtcWireStream::GetId ( ) const

inlinenodiscardoverridevirtual

Returns the unique (in this process) identifier of the stream.

Returns: A string representing the unique identifier of the stream. This identifier is used to distinguish between different streams in the same process, but not across a load balanced group, for example.

Implements act::WireStream.

◆ GetImpl()

const void *absl_nullable act::net::WebRtcWireStream::GetImpl ( ) const

inlinenodiscardoverridevirtual

Returns the underlying implementation of the stream.

This function is intended to be overridden by derived classes to provide access to the specific implementation of the stream, in case such access is required. The default implementation returns a null pointer.

Returns: A pointer to the underlying implementation of the stream.

Reimplemented from act::WireStream.

◆ GetStatus()

absl::Status act::net::WebRtcWireStream::GetStatus ( ) const

overridevirtual

Returns the status of the stream.

This method is used to check the current status of the stream, which is OK unless the stream has been aborted.

Returns: An absl::Status indicating the current status of the stream. If the stream is in a valid state, it returns absl::OkStatus(). If the stream is in an error state (e.g., due to an abort), it returns an appropriate error status.

Implements act::WireStream.

◆ HalfClose()

void act::net::WebRtcWireStream::HalfClose ( )

inlineoverridevirtual

Communicates to the other end that no more messages will be sent over this stream.

Note: This method does not close the stream, nor does it initiate a finalisation. It simply indicates that no more messages will be sent. The stream remains open for receiving messages, and the other end can still send messages until it also calls HalfClose() or closes the stream.; Nor does this method guarantee that the other end will receive the half-close message immediately, or at all. However, if the stream is indeed broken, GetStatus() will return an error status, and Send() and Receive() will return errors as well if a stream is in a state where they cannot proceed.

Implements act::WireStream.

◆ Receive()

absl::StatusOr< std::optional< WireMessage > > act::net::WebRtcWireStream::Receive ( absl::Duration timeout )

overridevirtual

Receives an ActionEngine wire message from the stream.

Blocks to wait for a message to be received, up to the specified timeout.

Parameters

timeout The maximum duration to wait for a message to be received. If the timeout is reached, the function will return an absl::DeadlineExceededError.

Returns: An optional WireMessage if a message is received within the specified timeout. An empty optional indicates that no message will be received.

Note: Correct implementations of this method should return an empty optional if the stream is half-closed, and no more messages can be received. If the stream is aborted (e.g., due to an error), the method should return an error status.; Implementations MUST ensure that this method reacts to an Abort() call, returning an error status and not blocking indefinitely. This is important in the inner workings of the ActionEngine, where Receive() is called in a loop, and the loop should be able to terminate gracefully when the stream is aborted.

Implements act::WireStream.

◆ Send()

absl::Status act::net::WebRtcWireStream::Send ( WireMessage message )

overridevirtual

Sends a WireMessage over the stream.

May or may not block, depending on the implementation. For example, WebsocketWireStream will block until the message is sent, while WebRtcWireStream will return immediately, allowing the message to be sent asynchronously.

With that in mind, the caller should not assume that the message has been sent immediately after this function returns, or even that it has been sent successfully. Failure modes of this method are more about the invariants of the stream itself: for example, if the stream is closed, or half-closed (no more messages can be sent), this method will return an error.

Parameters

message The WireMessage to send, containing action calls (in the form of multiple ActionMessage) and/or node fragments.

Returns: An OK status unless the stream is in a state where it cannot send messages, such as being half-closed or closed.

Note: Implementations of WireStream should and will treat a WireMessage with no actions or node fragments as an initiation or acknowledgment of a half-close.

Implements act::WireStream.

◆ Start()

absl::Status act::net::WebRtcWireStream::Start ( )

inlineoverridevirtual

Starts the stream on the client side.

Clients should call this method to initiate the stream after it has been created. This method is intended to be called by the client to start the stream, which may involve some underlying negotiation or setup. Implementations that differentiate between client and server streams are allowed to return an error if this method is called on a server, or even to perform a hard termination of the process, as such a call is considered a misuse of the API.

Some implementations may not require this method, in which case they can return an OK status without doing anything.

Returns: An OK status if the stream is successfully started, or an error status if the stream cannot be started (e.g., if it is already started, or some underlying negotiation failed).

Implements act::WireStream.

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

/Users/helenapankov/dev/actionengine/src/actionengine/net/webrtc/wire_stream.h
/Users/helenapankov/dev/actionengine/src/actionengine/net/webrtc/wire_stream.cc

Detailed Description

Public Member Functions

Member Function Documentation

◆ Abort()

◆ Accept()

◆ GetId()

◆ GetImpl()

◆ GetStatus()

◆ HalfClose()

◆ Receive()

◆ Send()

◆ Start()