Listeners

Basic Usage#

import 'package:magic/magic.dart';
import 'package:magic_socket/magic_socket.dart';

class MonitorController extends MagicController with ListensToBroadcasts {
  @override
  Map<String, void Function(BroadcastEvent)> get listeners => {
    'team:check.recorded': (event) => print(event.data['monitor_id']),
  };
}

Future<void> boot(String? Function() teamChannel) async {
  BroadcastListeners.channel('team', teamChannel);
  await BroadcastListeners.sync();
}

A controller that mixes in ListensToBroadcasts declares the events it wants as '<alias>:<event>'. The alias names a channel you declared once with BroadcastListeners.channel. This is the Magic replacement for the --broadcasts flag that make:controller used to have: write the mixin by hand, there is no generator.

Quick Reference#

Declaring an Alias#

Left to Echo, a second controller's Echo.private(name).listen(event, ...) replaces the first controller's handler for that event, and either controller closing would tear the channel down under the other. BroadcastListeners is the process-wide registry that fixes both: one subscription per alias, with every handler fanned out from one stable callback in registration order.

import 'package:magic_socket/magic_socket.dart';

Future<void> declare(int? teamId, Future<void> Function() refetchAll) async {
  BroadcastListeners.channel(
    'team',
    () => teamId == null ? null : 'teams.$teamId',
    onReconnect: refetchAll,
  );

  await BroadcastListeners.sync();
}

Declare aliases once, typically in a provider's boot(). Calling channel again for the same alias replaces its name resolver and onReconnect in place. The channel is always a private one (Echo.private), so the server must authorise it.

A handler that throws is logged with Log.error and the next handler still runs.

The ListensToBroadcasts Mixin#

import 'package:magic/magic.dart';
import 'package:magic_socket/magic_socket.dart';

class MonitorController extends MagicController with ListensToBroadcasts {
  @override
  Map<String, void Function(BroadcastEvent)> get listeners => {
    'team:check.recorded': _onCheck,
    'team:monitor.paused': _onPaused,
  };

  void _onCheck(BroadcastEvent event) => print(event.data);
  void _onPaused(BroadcastEvent event) => print(event.data);
}

A controller read only through .instance and never mounted in a view never gets onInit, so call startListening() from its own constructor.

Syncing on Auth Changes#

BroadcastListeners.sync() is what moves the subscription when the answer of a name resolver changes, so wire it to whatever changes that answer, usually the auth state.

import 'package:flutter/foundation.dart';
import 'package:magic_socket/magic_socket.dart';

void wire(ChangeNotifier authState) {
  authState.addListener(BroadcastListeners.sync);

  BroadcastListeners.sync(); // the listener only fires on a change
}

The aliases share the default Echo connection. A null name on one alias leaves only that alias's channel. sync() disconnects once no alias resolves a channel any more, so a user leaving their last team does not silence an alias that still names them.

AuthChannelSubscription#

AuthChannelSubscription is the single-channel building block under BroadcastListeners. Use it directly when one controller owns one auth-scoped channel and nothing else shares it.

import 'package:magic_socket/magic_socket.dart';

void watchTeam(int? teamId) {
  final subscription = AuthChannelSubscription(
    channelName: () => teamId == null ? null : 'teams.$teamId',
    listeners: {
      'incident.opened': (event) => print(event.data),
    },
    onReconnect: () => print('refetch what the socket missed'),
  );

  subscription.sync();
}

BroadcastListeners builds each alias with disconnectOnTeardown: false so one alias leaving does not drop the others.

Gotchas#

Related Documentation#

• Channels: Echo.private and the event envelope.
• Connection: what Echo.connect() and Echo.disconnect() do.
• Testing: fake.dispatch against a listener.