// Handle WebSocket connections and hijack connections for SSE or custom protocols in Relic. Use when implementing real-time communication, WebSocket endpoints, or server-sent events.
Bootstrap a Relic web server, configure RelicApp, start serving, and enable hot reload. Use when creating a new Relic project, setting up a server, or configuring the development workflow.
Create and apply middleware for auth, CORS, logging, and other cross-cutting concerns. Use context properties for type-safe request-scoped data. Use when adding middleware, request/response transformations, or passing data between middleware and handlers.
Handle HTTP requests and create responses with Body, headers, and status codes in Relic. Use when reading request data, parsing JSON, building API responses, working with headers, or streaming content.
Define routes with path parameters, wildcards, tail segments, and typed params in Relic. Use when adding endpoints, handling dynamic URLs, setting up URL patterns, or forwarding requests.
Migrate a Dart web server from Shelf to Relic. Side-by-side reference for every API change. Use when converting Shelf code to Relic, replacing shelf/shelf_router/shelf_web_socket imports, or upgrading an existing server.
Serve static files and directories with caching and cache busting in Relic. Use when serving assets, images, CSS, JS, favicons, or configuring HTTP cache control headers.
| name | relic-websockets |
| description | Handle WebSocket connections and hijack connections for SSE or custom protocols in Relic. Use when implementing real-time communication, WebSocket endpoints, or server-sent events. |
Relic handlers return a Result, which can be a Response, WebSocketUpgrade, or Hijack. WebSockets and hijacking are built-in -- no extra packages needed.
Return a WebSocketUpgrade to upgrade an HTTP connection to a WebSocket:
app.get('/ws', (Request req) {
return WebSocketUpgrade((webSocket) async {
webSocket.sendText('Welcome!');
await for (final event in webSocket.events) {
switch (event) {
case TextDataReceived(text: final message):
webSocket.sendText('Echo: $message');
case CloseReceived():
break;
default:
break;
}
}
});
});
webSocket.sendText('Hello!'); // throws on failure
webSocket.trySendText('Hello!'); // silent on failure
Listen on webSocket.events and pattern-match:
TextDataReceived(text: final message) -- text frame receivedCloseReceived() -- connection closed by clientWebSocketUpgrade websocketHandler(Request request) {
return WebSocketUpgrade((ws) async {
ws.events.listen((event) {
log('Received: $event');
});
ws.trySendText('Hello!');
ws.sendText('Hello!');
});
}
Return a Hijack to take direct control of the underlying TCP connection. Useful for Server-Sent Events (SSE) or custom protocols:
app.get('/sse', (Request req) {
return Hijack((channel) async {
channel.sink.add(utf8.encode('data: Connected\n\n'));
final timer = Timer.periodic(
Duration(seconds: 1),
(_) => channel.sink.add(
utf8.encode('data: ${DateTime.now()}\n\n'),
),
);
await channel.sink.done;
timer.cancel();
});
});
app.get('/custom', (Request req) {
return Hijack((channel) {
const response =
'HTTP/1.1 200 OK\r\n'
'Content-Type: text/plain\r\n'
'Connection: close\r\n'
'\r\n'
'Custom protocol response!';
channel.sink.add(utf8.encode(response));
channel.sink.close();
});
});
import 'dart:async';
import 'dart:convert';
import 'package:relic/relic.dart';
Future<void> main() async {
final app = RelicApp()
..get('/ws', (req) {
return WebSocketUpgrade((ws) async {
ws.sendText('Welcome to Relic WebSocket!');
await for (final event in ws.events) {
switch (event) {
case TextDataReceived(text: final message):
ws.sendText('Echo: $message');
case CloseReceived():
break;
default:
break;
}
}
});
})
..get('/sse', (req) {
return Hijack((channel) async {
channel.sink.add(utf8.encode('data: Connected\n\n'));
final timer = Timer.periodic(
Duration(seconds: 1),
(_) => channel.sink.add(utf8.encode('data: tick\n\n')),
);
await channel.sink.done;
timer.cancel();
});
});
await app.serve();
}