Connection class

A single WebSocket shared by many Channel handles (PieSocket v4).

The channel named at connect time is the "primary" — its lifecycle is the socket's lifecycle. Every other channel is subscribed with a system::subscribe control frame and rides the same socket; outbound frames for it are tagged with system::channel, and inbound frames are routed back to it by the system::channel / data.channel the server stamps on them.

All v4 control/system events are system::x (double colon) — this is a separate, untouched convention from v3's single-colon system: events that Channel still speaks natively when not attached to a hub.

Constructors

Connection(String primaryChannelId, PieSocketOptions options, Logger logger, String uuid, Channel primaryChannel, {String? jwt})
Opens the shared socket with primaryChannelId as primary. uuid and jwt (if the channel is guarded) are baked into the connect URL the same way a standalone Channel builds its own. primaryChannel is attached before the socket connects — _connect() fires onOpen() synchronously (Dart's WebSocketChannel has no async "open" event to wait for), which looks up channels[primaryChannelId] to fire system:connected; attaching it here instead of leaving the caller to call attachChannel() afterward means that lookup is never too late.
Connection.forTesting(String primaryChannelId, PieSocketOptions options, Logger logger, void sendOverride(String data)?)

Properties

channels → Map<String, Channel>
final
connected ↔ bool
getter/setter pair
hashCode → int
The hash code for this object.
no setterinherited
logger → Logger
final
onPrimaryConnected ↔ void Function()?
Set by PieSocket to learn when the primary channel's socket actually opens (or fails) — join() itself stays synchronous, this is purely for callers who want to know when the shared connection is live.
getter/setter pair
onPrimaryError ↔ void Function(dynamic error)?
getter/setter pair
options → PieSocketOptions
final
primaryChannelId ↔ String
getter/setter pair
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
sendBinaryOverride ↔ void Function(List<int> bytes)?
Overridable for tests — binary counterpart of sendOverride.
getter/setter pair
sendOverride ↔ void Function(String data)?
Overridable for tests — avoids needing a real socket to test routing.
getter/setter pair
shouldReconnect ↔ bool
getter/setter pair

Methods

attachChannel(String channelId, Channel channel) → void
close() → void
detachChannel(String channelId) → void
isPrimary(String channelId) → bool
migratePrimary(String newPrimaryId, String endpoint, {String? newUuid, String? newJwt}) → void
Re-open the socket with newPrimaryId as the primary channel, keeping every other subscription. Frames in flight during the swap may be missed.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
onClose() → void
onError(dynamic error) → void
onMessage(dynamic message) → void
onOpen() → void
requestMembers(String channelId) → Future<List>
send(String channelId, PieSocketEvent event) → void
Send an application frame on behalf of channelId. Secondary channels get a system::channel tag so the receiving multiplexed client (and the server) can attribute the frame to the right subscription.
sendBinary(String channelId, List<int> bytes) → void
Send a raw binary frame on the shared socket — see Channel.sendBinary. Only valid for the primary channel: raw bytes carry no system::channel tag, so a secondary channel's frame can't be attributed server-side.
sendControl(String eventName, Map<String, dynamic> data) → void
sendRaw(String channelId, String text) → void
Like send, but for an already-serialised (or non-JSON) payload — used by Channel.send. Tries to parse it as JSON to tag system::channel on a secondary channel; falls back to sending it verbatim if it isn't JSON.
subscribeChannel(String channelId, Map<String, dynamic> params) → Future<void>
toString() → String
A string representation of this object.
inherited
unsubscribeChannel(String channelId) → Future<void>

Operators

operator ==(Object other) → bool
The equality operator.
inherited