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.