a11::net::WireStream Class Reference

A bidirectional, message-oriented channel between two A11 endpoints. More...

#include <a11/net/wire_stream.h>

Inheritance diagram for a11::net::WireStream:

Public Member Functions
virtual	~WireStream ()=default
virtual absl::Status	Send (data::WireMessage message)=0
	Enqueue a message for delivery to the peer.
virtual a11::Task	Start (OnMessage on_message, OnDone on_done)=0
	Begin the stream as the initiating ("start") side.
virtual a11::Task	Accept (OnMessage on_message, OnDone on_done)=0
	Begin the stream as the accepting ("accept") side.
absl::Status	HalfClose ()
	Half-close with no trailers.
virtual absl::Status	HalfClose (data::ByteMap trailers)=0
	Signal that this side will send no more messages.
virtual a11::Task	DrainOutgoingMessages ()=0
	Await delivery of all buffered outbound messages.
virtual absl::Status	Abort (absl::Status status)=0
	Abort the stream, discarding buffered work.
absl::Status	SetDeadline ()
	Clear any deadline (equivalent to an infinite deadline).
virtual absl::Status	SetDeadline (absl::Time deadline)=0
	Set the absolute deadline after which the stream is aborted.
virtual absl::Time	deadline () const =0
virtual absl::Status	GetStatus () const =0
virtual std::optional< data::ByteMap >	GetTrailers () const =0
virtual std::string	GetId () const =0
virtual void *absl_nullable	GetImpl () const =0

Detailed Description

A bidirectional, message-oriented channel between two A11 endpoints.

A WireStream is A11's transport abstraction: an ordered neither – delivery carries no global ordering guarantee. Messages may be observed by the reader in an order different from how the sender enqueued them, and different transports (e.g. an unreliable WebRTC data channel) make that explicit. The one synchronisation point the interface does promise is closure: every message accepted for delivery is observed by the reader before the stream reports done, and the half-close marker follows messages already queued by that endpoint. HalfClose() queues that transition; DrainOutgoingMessages() is the explicit local delivery barrier. Callers that need ordering must impose it above the transport (an AsyncNode/ChunkStore log, which is ordered by sequence number, is the usual way).

Implement this interface to carry A11 traffic over a transport A11 does not ship; the runtime treats every implementation identically.

Constructor & Destructor Documentation

~WireStream()

virtual a11::net::WireStream::~WireStream ( )

virtualdefault

Member Function Documentation

Abort()

virtual absl::Status a11::net::WireStream::Abort ( absl::Status  status )

pure virtual

Abort the stream, discarding buffered work.

Parameters

status

A non-OK status reported to the peer as the abort reason.

Returns

OK if the abort was accepted.

Implemented in a11::net::ChannelWireStream, a11::net::HttpSseWireStream, a11::net::InProcessWireStream, and a11::net::WireStreamWithRecv.

Accept()

virtual a11::Task a11::net::WireStream::Accept ( OnMessage  on_message, OnDone  on_done  )

pure virtual

Begin the stream as the accepting ("accept") side.

Parameters

on_message	Invoked for each inbound message (nullopt = peer half-closed).
on_done	Invoked once when the stream has finished.

Returns

An awaitable that resolves once the stream is accepted.

Implemented in a11::net::ChannelWireStream, a11::net::HttpSseWireStream, a11::net::InProcessWireStream, and a11::net::WireStreamWithRecv.

deadline()

virtual absl::Time a11::net::WireStream::deadline ( ) const

pure virtual

Returns

The stream's current deadline.

Implemented in a11::net::ChannelWireStream, a11::net::HttpSseWireStream, a11::net::InProcessWireStream, and a11::net::WireStreamWithRecv.

DrainOutgoingMessages()

virtual a11::Task a11::net::WireStream::DrainOutgoingMessages ( )

pure virtual

Await delivery of all buffered outbound messages.

Returns

An awaitable that resolves once this endpoint's queued messages have been flushed to the transport (requires a prior HalfClose).

Implemented in a11::net::ChannelWireStream, a11::net::HttpSseWireStream, a11::net::InProcessWireStream, and a11::net::WireStreamWithRecv.

GetId()

virtual std::string a11::net::WireStream::GetId ( ) const

pure virtual

Returns

This stream's transport-assigned identifier.

Implemented in a11::net::ChannelWireStream, a11::net::HttpSseWireStream, a11::net::InProcessWireStream, and a11::net::WireStreamWithRecv.

GetImpl()

virtual void *absl_nullable a11::net::WireStream::GetImpl ( ) const

pure virtual

Returns

An opaque handle to the underlying transport object (advanced; may be null).

Implemented in a11::net::ChannelWireStream, a11::net::HttpSseWireStream, a11::net::InProcessWireStream, and a11::net::WireStreamWithRecv.

GetStatus()

virtual absl::Status a11::net::WireStream::GetStatus ( ) const

pure virtual

Returns

The stream's terminal status (OK unless it failed or was aborted).

Implemented in a11::net::ChannelWireStream, a11::net::HttpSseWireStream, a11::net::InProcessWireStream, and a11::net::WireStreamWithRecv.

GetTrailers()

virtual std::optional< data::ByteMap > a11::net::WireStream::GetTrailers ( ) const

pure virtual

Returns

The peer's closing trailers, if the stream has received them.

Implemented in a11::net::ChannelWireStream, a11::net::HttpSseWireStream, a11::net::InProcessWireStream, and a11::net::WireStreamWithRecv.

HalfClose() [1/2]

absl::Status a11::net::WireStream::HalfClose ( )

inline

Half-close with no trailers.

See also

HalfClose(data::ByteMap)

HalfClose() [2/2]

virtual absl::Status a11::net::WireStream::HalfClose ( data::ByteMap  trailers )

pure virtual

Signal that this side will send no more messages.

The terminal marker is queued after buffered outbound messages and, once the peer also half-closes, the stream completes. Inbound messages continue to be delivered until then. Call DrainOutgoingMessages() to await local transport delivery.

Parameters

trailers

Optional closing metadata delivered to the peer.

Returns

OK, or a non-OK status if the stream cannot be half-closed.

Implemented in a11::net::ChannelWireStream, a11::net::HttpSseWireStream, a11::net::InProcessWireStream, a11::net::WireStreamWithRecv, a11::net::ChannelWireStream, a11::net::HttpSseWireStream, a11::net::InProcessWireStream, and a11::net::WireStreamWithRecv.

Send()

virtual absl::Status a11::net::WireStream::Send ( data::WireMessage  message )

pure virtual

Enqueue a message for delivery to the peer.

Non-blocking.

The message is admitted to this endpoint's outbound queue and delivered asynchronously by the transport task, which is also where backpressure is applied; there is no delivery-order guarantee across messages (see the class comment).

Parameters

message

The message to send.

Returns

OK once the message is queued, or a non-OK status if the stream is not writable (e.g. already half-closed or aborted).

Implemented in a11::net::ChannelWireStream, a11::net::HttpSseWireStream, a11::net::InProcessWireStream, and a11::net::WireStreamWithRecv.

SetDeadline() [1/2]

absl::Status a11::net::WireStream::SetDeadline ( )

inline

Clear any deadline (equivalent to an infinite deadline).

SetDeadline() [2/2]

virtual absl::Status a11::net::WireStream::SetDeadline ( absl::Time  deadline )

pure virtual

Set the absolute deadline after which the stream is aborted.

Parameters

deadline

The deadline; absl::InfiniteFuture() disables it.

Implemented in a11::net::ChannelWireStream, a11::net::HttpSseWireStream, a11::net::InProcessWireStream, a11::net::WireStreamWithRecv, a11::net::ChannelWireStream, a11::net::HttpSseWireStream, a11::net::InProcessWireStream, and a11::net::WireStreamWithRecv.

Start()

virtual a11::Task a11::net::WireStream::Start ( OnMessage  on_message, OnDone  on_done  )

pure virtual

Begin the stream as the initiating ("start") side.

Parameters

on_message	Invoked for each inbound message (nullopt = peer half-closed).
on_done	Invoked once when the stream has finished.

Returns

An awaitable that resolves once the startup handshake completes.

Implemented in a11::net::ChannelWireStream, a11::net::HttpSseWireStream, a11::net::InProcessWireStream, and a11::net::WireStreamWithRecv.

---

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

• cpp/a11/net/wire_stream.h