magic_socket
Real-time broadcasting for a Magic app. The Echo facade subscribes to public, private and presence channels through a BroadcastManager: ReverbBroadcastDriver speaks the Pusher protocol to Laravel Reverb and reconnects by itself, NullBroadcastDriver (the default) accepts every call and delivers nothing. BroadcastServiceProvider binds the manager, starts the connection at boot and adds the X-Socket-ID header to Http requests. ListensToBroadcasts shares one private channel between controllers, and Echo.fake tests it.
This skill covers magic_socket only. The Magic framework itself (container, providers, Http, MagicController, config) is the magic-framework skill.
Install
flutter pub add magic_socket
dart run magic:dowel plugin:install magic_socket
Requires Dart >=3.13, Flutter >=3.47 and magic ^1.0.0. The installer adds BroadcastServiceProvider to lib/config/app.dart and () => broadcastingConfig to the configFactories of lib/main.dart; it publishes no config. Import only package:magic_socket/magic_socket.dart. Set .env:
BROADCAST_CONNECTION=reverb
REVERB_HOST=localhost
REVERB_PORT=8080
REVERB_SCHEME=ws
REVERB_APP_KEY=
BROADCAST_CONNECTION defaults to null. Private and presence auth is POST /broadcasting/auth through Http, and X-Socket-ID needs a network driver, so the app lists NetworkServiceProvider.
Channel rules
- Use
Echo.channelfor public,Echo.privatefor private andEcho.joinfor presence. Pass the bare name (user.1); the driver addsprivate-orpresence-. Echo.listen(channel, event, cb)is a public-channel shorthand. A private event isEcho.private(name).listen(event, cb).- A second
listenfor one event on one channel replaces the first. Two controllers wanting one event useBroadcastListeners, not twolistencalls. - Handlers must be idempotent: the server can repeat a frame, including a retried queued job.
- Refetch missed data when
channel.onSubscriptionChangedturnstrue.Echo.onReconnectfires after the subscribe was sent, before the server confirms it. Echo.connect()is idempotent and joins an attempt in flight. Boot does not wait for the socket, so readEcho.socketIdonly after awaitingEcho.connect().- A 401 or 403 on the auth route is logged and not retried; a missing response or a 5xx is retried with backoff (
BroadcastAuthException.isRetryable).
Config rules
- Register
broadcastingConfiginconfigFactories, neverconfigs: it callsenv(), which needs.envloaded. auth_endpoint,reconnect,max_reconnect_delay(30000 ms),activity_timeout(120 s) andconnection_timeout(15 s) are not env keys; change them by wrapping the factory.- An unknown connection or driver name resolves to the null driver. Register a custom driver with
BroadcastManager.extend(name, factory)before the provider that resolves it. SocketIdInterceptoris added only for a connection other thannulland only when a network driver is bound; never add it by hand.
Listener rules
ListensToBroadcastsreplaces core's removedmake:controller --broadcasts; there is no generator. Keys are'<alias>:<event>'.- Declare each alias once,
BroadcastListeners.channel('team', () => id == null ? null : 'teams.$id'), and callawait BroadcastListeners.sync()at startup and on every auth change. startListening()runs fromonInit. A controller used only through.instancecalls it from its constructor.- A
nullalias name leaves that channel;sync()disconnects only when no alias is live. A standaloneAuthChannelSubscriptiondisconnects on its ownnullname unlessdisconnectOnTeardown: false.
Recipes
Subscribe and react:
import 'package:magic_socket/magic_socket.dart';
void watchOrders() {
// The name must equal the frame's event name (the server's broadcastAs()).
Echo.channel('orders').listen('OrderShipped', (event) {
print('Order ${event.data['id']} has shipped');
});
}
listen compares the name with the frame's event name exactly and resolves no namespace, unlike Echo JS. A Laravel event without broadcastAs() arrives as its full class name (App\Events\OrderShipped), so give the event a broadcastAs() or pass the full name.
Join a presence channel:
import 'package:magic_socket/magic_socket.dart';
void joinRoom() {
final room = Echo.join('room.1');
room.onJoin.listen((member) => print('${member['name']} joined'));
room.onLeave.listen((member) => print('${member['name']} left'));
}
A controller on a shared channel:
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),
};
}
Future<void> declareTeamChannel(int? teamId) async {
BroadcastListeners.channel('team', () => teamId == null ? null : 'teams.$teamId');
await BroadcastListeners.sync();
}
Testing
Import package:magic_socket/testing.dart. In setUp() call MagicApp.reset() and Magic.flush(). Echo.fake() returns a FakeBroadcastManager; assert with assertSubscribed, assertNotSubscribed, assertListening, assertNotListening, assertConnected, assertDisconnected and assertInterceptorAdded. Private and presence names carry their prefix in assertions (private-user.1). assertSubscribed does not prove a handler exists, so use assertListening, and fake.dispatch(channel, event, data) to run it with a decoded payload. fake.driver.setSubscribed(name, true) stands in for the server's confirmation.
The BroadcastListeners registry and BroadcastManager.extend are statics that Magic.flush() does not clear: in tearDown() call BroadcastListeners.reset() and BroadcastManager.resetDrivers(). Echo.fake binds into the container, so Magic.flush() drops it.
import 'package:flutter_test/flutter_test.dart';
import 'package:magic_socket/magic_socket.dart';
import 'package:magic_socket/testing.dart';
void main() {
tearDown(() => Echo.unfake());
test('a handler receives a frame', () {
final FakeBroadcastManager fake = Echo.fake();
final received = <BroadcastEvent>[];
Echo.private('user.1').listen('ProfileUpdated', received.add);
fake.dispatch('private-user.1', 'ProfileUpdated', {'name': 'Ada'});
expect(received, hasLength(1));
});
}