HandlerService class

A Service backed by closures — the quickest way to host request/response (and optionally WebSocket) logic without declaring a class.

hub.registerService(HandlerService(
  name: 'api',
  mount: '/api',
  handler: (req) async => HubResponse.json({'ok': true}),
));

WebSocket integration

A HandlerService serves ordinary requests through handler and — if an onConnection handler is supplied — WebSocket connections on the same mount/port.

When a client sends a WebSocket upgrade request whose route resolves to this service, the hub performs the upgrade and invokes onConnection with the established duplex Connection and the originating HubRequest (for host, path, headers and the authenticated principal). The plain handler is not called for upgrade requests; it only handles non-upgrade HTTP requests to the same mount (e.g. a browser GET that should return a page or an error hint).

hub.registerService(HandlerService(
  name: 'chat',
  mount: '/chat',
  // Non-upgrade GET /chat — a hint for plain HTTP clients.
  handler: (req) async => HubResponse.text('Connect a WebSocket to /chat'),
  // WebSocket GET /chat (Upgrade: websocket) — the live connection.
  onConnection: (conn, req) {
    conn.incoming.listen((msg) {
      if (msg is TextMessage) conn.send(TextMessage('echo: ${msg.data}'));
    });
  },
));

If onConnection is null (handlesWebSocket is false), an upgrade routed here is rejected: the hub closes the connection with the WsCloseCodes.unsupported code (via ServiceBase.handleConnection).

Constructors

HandlerService({required String name, String mount = '/', required HubRequestHandler handler, ConnectionHandler? onConnection, Future<void> onStart()?, Future<void> onStop()?}): Creates a service mounted at mount that dispatches requests to handler and, when provided, WebSocket upgrades to onConnection.

Properties

handlesWebSocket → bool: Whether this service accepts WebSocket connections — i.e. an onConnection handler was supplied. When false, WebSocket upgrades routed to this service are rejected by handleConnection.
no setter
hashCode → int: The hash code for this object.
no setterinherited
mount → String: finalinherited
name → String: finalinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited

Methods

handle(HubRequest request) → Future<HubResponse>: Handles an ordinary request. The service receives the full request (its path is not stripped of mount).
handleConnection(Connection connection, HubRequest request) → FutureOr<void>: Handles an upgraded WebSocket connection whose upgrade request matched this service. Services that do not serve WebSockets should close the connection.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
start() → Future<void>: Starts the service (open resources, connect to backends, ...). Called by the hub on OmnyHub.start or when registered into a running hub.
stop() → Future<void>: Stops the service and releases its resources.
toString() → String: A string representation of this object.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited