websocket_core library
WebSocket Core - Backend WebSocket package for Dart
A pure WebSocket backend core with explicit protocol, session management, reconnection, rooms and zero external dependencies.
Quick Start
import 'package:websocket_core/websocket_core.dart';
void main() async {
final server = WsServer(
config: WsServerConfig(port: 8080),
);
// Register event handlers
server.on('chat.message', (context) async {
// Broadcast to room
server.rooms.broadcast(
context.payload['roomId'],
context.message,
excludeSessionId: context.sessionId,
);
return null;
});
await server.start();
}
Core Concepts
- Session > Connection: Sessions survive connection drops
- Explicit Protocol: No implicit message formats
- Pluggable Auth: Implement your own authentication
- Rooms by Session: Rooms track sessions, not connections
Classes
- AuthResult
- Resultado da autenticação
- CallbackAuthenticator
- Authenticator baseado em callback.
- HandlerRegistration
- Registro de handler com metadados
- HeartbeatManager
- Gerenciador de heartbeat (ping/pong).
- IdGenerator
- Interface para geração de IDs
- InMemoryMetrics
- Métricas em memória para desenvolvimento/debugging.
- LifecycleEvent
- Evento de lifecycle
- LifecycleEventEmitter
- Emitter de eventos de lifecycle
- LocalEventBus
- Event Bus local (em memória) - NÃO ESCALA.
- LocalTypedEventBus
- Event Bus local (em memória).
- NoAuthAuthenticator
- Authenticator que permite qualquer conexão (desenvolvimento/teste).
- NoopMetrics
- Métricas nulas (noop) para quando não precisar de métricas.
- ProtocolValidationResult
- Resultado da validação de protocolo
- RateLimitConfig
- Configuração do rate limiter
- RateLimiter
- Rate Limiter para proteção contra abuse.
- ReconnectionHandler
- Handler de reconexão.
- ReconnectionResult
- Resultado da tentativa de reconexão
- RoomBroadcastEvent
- Evento de broadcast para salas
- SessionEvent
- Evento de sessão
- ShortIdGenerator
- Gerador de IDs curtos (para debugging/desenvolvimento)
- TimestampIdGenerator
- Gerador baseado em timestamp + random
- UuidGenerator
- Gerador de UUIDs v4
- WsAuthenticator
- Interface de autenticação plugável.
- WsCloseCodes
- Close codes para WebSocket
- WsConnection
- Wrapper da conexão WebSocket.
- WsConnectionManager
- Gerenciador de conexões WebSocket.
- WsContext
- Contexto passado para handlers
- WsDispatcher
- Dispatcher de eventos WebSocket.
- WsErrorCodes
- Códigos de erro padrão
- WsEventBus
- Interface para Event Bus distribuído.
- WsEvents
- Eventos do sistema WebSocket.
- WsMessage
- Estrutura base de mensagem WebSocket.
- WsMetrics
- Interface de métricas do WebSocket.
- WsProtocol
- Gerenciador de protocolo WebSocket.
- WsPubSub
- Interface para Pub/Sub externo.
- WsRoom
- Sala lógica WebSocket.
- WsRoomManager
- Gerenciador de salas.
- WsServer
- Servidor WebSocket principal.
- WsServerConfig
- Configuração do servidor WebSocket
- WsSession
- Sessão WebSocket.
- WsSessionManager
- Gerenciador de sessões WebSocket.
Enums
- LifecycleEventType
- Tipo de evento de lifecycle
- WsConnectionState
- Estado da conexão WebSocket
- WsServerState
- Estado do servidor
- WsSessionState
- Estado da sessão
Mixins
- RequiresToken
- Mixin para autenticação que requer token obrigatório
Functions
-
rateLimitMiddleware(
{int maxRequests = 100, Duration window = const Duration(seconds: 60), bool perSession = true, Set< String> ? exemptEvents}) → WsMiddleware - Cria middleware de rate limiting.
-
rateLimitMiddlewareWithConfig(
RateLimitConfig config) → WsMiddleware - Cria middleware de rate limiting com configuração customizada
Typedefs
- ConnectionCallback = void Function(WsConnection connection)
- Callback para eventos de conexão
-
EventHandler<
T> = void Function(T event) - Tipo de evento do bus
- HeartbeatTimeoutCallback = void Function(WsSession session)
- Callback quando heartbeat falha
- LifecycleListener = void Function(LifecycleEvent event)
- Interface para listener de eventos de lifecycle
- ReconnectionCallback = void Function(WsSession session, WsConnection oldConnection)
- Callback de reconexão
- RoomCallback = void Function(WsRoom room, WsSession session)
- Callback quando uma sessão entra/sai de uma sala
- RoomEventCallback = void Function(WsRoom room, WsSession session)
- Callback para eventos de sala
- SessionCallback = void Function(WsSession session)
- Callback para eventos de sessão
-
WsHandler
= Future<
WsMessage?> Function(WsContext context) - Tipo de handler de eventos
-
WsMiddleware
= Future<
bool> Function(WsContext context) - Middleware para pipeline
Exceptions / Errors
- WsAuthException
- Erro de autenticação.
- WsAuthRequiredException
- Autenticação requerida mas não fornecida.
- WsConnectionClosedException
- Conexão fechada.
- WsConnectionException
- Erro de conexão.
- WsException
- Exceção base do WebSocket Core.
- WsForbiddenException
- Sem permissão para ação.
- WsHandlerNotFoundException
- Handler não encontrado para evento.
- WsProtocolException
- Erro de protocolo (formato inválido, versão não suportada).
- WsRateLimitException
- Rate limit excedido.
- WsRoomException
- Erro relacionado a sala.
- WsRoomFullException
- Sala cheia.
- WsRoomNotFoundException
- Sala não encontrada.
- WsSessionDuplicateException
- Sessão duplicada (já ativa em outra conexão).
- WsSessionException
- Erro relacionado a sessão.
- WsSessionNotFoundException
- Sessão não encontrada.
- WsTokenException
- Token inválido ou expirado.
- WsUnsupportedVersionException
- Versão de protocolo não suportada.
- WsValidationException
- Erro de validação.