metered_realtime 0.1.0

Flutter WebRTC SDK for video & voice calls, screen sharing, and realtime pub/sub messaging — signaling, presence, auto-reconnect, and TURN, over flutter_webrtc.

Changelog

0.1.0

Initial release — the Flutter/Dart SDK for Metered Realtime Messaging.

Added — Signalling core

• Wire-protocol types mirroring the Metered Realtime Messaging server (WelcomePayload, ChannelMessage, DirectMessageEvent, PresenceEvent, PresencePeer, ServerErrorEvent, GoingAwayEvent, IceServerConfig, ErrorCode, WsCloseCode).
• Strict inbound frame parser (malformed frames are dropped, never thrown) and outbound frame builders with client-side validation + generateRequestId.
• Internal helpers: base-URL validation + connect-URL builder, credential isolation (CredentialStore), welcome.metadata.iceServers extraction with fail-closed validation, and credential/SDP scrubbing for log/error surfaces.
• Logger interface with NoopLogger / ConsoleLogger, and a UTF-8 byte-length helper for outbound size checks.
• SignallingClient: WebSocket pub/sub engine with connect/close/dispose/ subscribe/unsubscribe/publish/send, ack/requestId correlation, auto-reconnect (exponential backoff + jitter, terminal/slow-backoff close codes), token refresh + timeout on the tokenProvider path, an inactivity watchdog with keepalive ping (disable with inactivityTimeoutMs <= 0), and subscription replay on reconnect. Events are exposed as idiomatic Dart broadcast Streams (onConnected, onDisconnected, stateChanges, onMessage, onDirect, onPresence, onServerError, onGoingAway, onTokenProviderError); dispose() closes them.
• Public event/value types StateChange<T>, ConnectedEvent, DisconnectedEvent, TokenProviderError, and the injectable WebSocketLike seam (WsCloseInfo, WsReadyState, WebSocketFactory) over a default web_socket_channel adapter (plus a test fake).
• Typed exceptions: SignallingConnectError, SignallingServerError, SignallingDisconnectedError.
• Construction-time validation: ReconnectOptions and SignallingClientOptions assert sane values; base URLs reject path/query/fragment/userinfo and non-localhost plaintext ws://.

Added — WebRTC orchestration

• WebRTC abstractions behind an injectable factory (RtcPeerConnectionLike mirroring flutter_webrtc's surface, plus MediaStream/Track/RtpSender/ DataChannel *Like types, RtcSessionDescription/RtcIceCandidate, RtcTrackEvent, PeerConnectionState), and a PeerConnection engine with perfect-negotiation (polite/impolite collision + rollback) and an ICE-restart ladder (9 attempts, give-up-once, reset on connected) + inbound ICE flood caps.
• MeteredPeer / RemotePeer — the basic 1:N call: join/close, presence-driven onPeerJoined/onPeerLeft, one connection per remote with lexical-politeness perfect-negotiation, local-track fan-out (addStream/addTrack/removeStream/removeTrack), inbound RTC-signal routing (never surfaced as data), broadcast + direct onData, and onTrack/onStreamAdded/onStreamRemoved/stateChanges. Events are Stream-based; send/sendTo with client-side size + state checks; typed MeteredPeerSendError/MeteredPeerStateError/MeteredPeerOversizedError.

Added — flutter_webrtc binding

• The package now depends on the Flutter SDK and flutter_webrtc. A single adapter maps the plugin's RTCPeerConnection / MediaStream / Track / RtpSender / DataChannel to the *Like abstractions, so the orchestration core stays plugin-agnostic and fake-testable.
• rtcPeerConnectionFactory now defaults to the flutter_webrtc binding — MeteredPeer(MeteredPeerOptions(apiKey: ...)) works with no factory; tests still inject a fake.
• Send/receive real media with wrapMediaStream / wrapMediaStreamTrack (or FlutterWebrtcMediaStream / FlutterWebrtcMediaStreamTrack); inbound streams expose .native for rendering. See example/.

Added — Resilience, media metadata, data channels

• Transient signalling drops no longer tear the call down: MeteredPeer.state (and each RemotePeer.state) goes reconnecting, peer references stay valid, and on reconnect each surviving peer's transport is refreshed in place before state returns to joined. Remote streams re-announce via onStreamAdded with a fresh stream object (same id) — re-bind your renderer on every event. remote.pc goes stale across the refresh; re-read it on stateChanges → connected.
• Per-track/stream metadata: addStream(s, metadata: {...}) / addTrack(t, metadata: {...}) deliver a StreamMetadata bag to every current and future peer ahead of the media; receivers read it on the onTrack / onStreamAdded payloads. Sender-side lookups via getTrackMetadata / getStreamMetadata. The bag rides the direct channel under the reserved __meteredTrackMeta key — don't use that key in your own sendTo payloads (doing so logs a warning: the receiving SDK intercepts such payloads and they never surface on onData).
• MeteredPeer.replaceTrack(oldTrack, newTrack) — swap a sender's track across every peer without renegotiation (or pass null to silence). Partial failures throw MeteredPeerReplaceTrackError with per-peer succeeded/failed outcomes so you can retry just the failed subset.
• DataChannel — an opt-in wrapper over a raw channel (from remote.pc.createDataChannel(...) or RemotePeer.onDataChannel) with typed onOpen/onClose/onError/onMessage streams and a backpressure-aware send() (suspends while the transport buffer is above maxBufferedAmount — confirmed against a fresh platform reading, with a backstop poll so a missed drain event can't hang sends — and rejects with DataChannelOverflowError past maxQueuedSends). Configure via DataChannelOptions (non-positive values throw ArgumentError); RtcDataChannelMessage carries text or binary payloads.
• Terminal close codes surfaced on onError now include the code name (e.g. channel_not_authorized).