docs: WebSockets (#443)

Author: felangel

README.md

@@ -74,34 +74,6 @@ The goal of Dart Frog is to help developers effectively build backends in Dart.
 
 Dart Frog provides a simple core with a small API surface area in order to reduce the learning curve and ramp-up time for developers. In addition, Dart Frog is intended to help Flutter/Dart developers maximize their productivity by having a unified tech stack that enables sharing tooling, models, and more!
 
-## Feature Set ✨
-
-✅ Hot Reload ⚡️
-
-✅ Dart Dev Tools ⚙️
-
-✅ File System Routing 🚏
-
-✅ Index Routes 🗂
-
-✅ Nested Routes 🪆
-
-✅ Dynamic Routes 🌓
-
-✅ Middleware 🍔
-
-✅ Dependency Injection 💉
-
-✅ Production Builds 👷‍♂️
-
-✅ Docker 🐳
-
-✅ Static File Support 📁
-
-🚧 Generated Dart Client Package 📦
-
-🚧 Generated API Documentation 📔
-
 [dart_installation_link]: https://dart.dev/get-dart
 [ci_badge]: https://github.com/VeryGoodOpenSource/dart_frog/actions/workflows/main.yaml/badge.svg
 [ci_link]: https://github.com/VeryGoodOpenSource/dart_frog/actions/workflows/main.yaml

docs/docs/advanced/powered_by_header.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 4
 title: 🔋 Powered By Header
 ---
 

docs/docs/advanced/web_socket.md

@@ -0,0 +1,235 @@
+---
+sidebar_position: 3
+title: 🔌 WebSockets
+---
+
+# WebSockets 🔌
+
+Dart Frog recently introduced [`package:dart_frog_web_socket`](https://pub.dev/packages/dart_frog_web_socket) to make working with WebSockets easier.
+
+:::info
+We added WebSocket support as a separate package to keep the Dart Frog package lightweight, containing only core functionality. In the future, we may add additional packages in order to extend the Dart Frog ecosystem without bloating the core.
+:::
+
+## Installation
+
+To get started, add the `dart_frog_web_socket` package as a dependency to your existing Dart Frog project:
+
+```sh
+dart pub add dart_frog_web_socket
+```
+
+## Creating a WebSocket Handler
+
+We can use the `webSocketHandler` from `package:dart_frog_web_socket` to manage WebSocket connections.
+
+You can either create a new route handler or integrate with an existing handler. For simplicity, we'll first take a look at adding a new route handler specifically for WebSocket connections.
+
+Start by creating a new route, `routes/ws.dart`:
+
+```dart
+import 'package:dart_frog/dart_frog.dart';
+
+Response onRequest(RequestContext context) {
+  return Response();
+}
+```
+
+Next, instead of handling the request directly, we can create a WebSocket handler:
+
+```dart
+import 'package:dart_frog/dart_frog.dart';
+import 'package:dart_frog_web_socket/dart_frog_web_socket.dart';
+
+Future<Response> onRequest(RequestContext context) async {
+  final handler = webSocketHandler((channel, protocol) {
+    // TODO: react to new connections.
+  });
+  return handler(context);
+}
+```
+
+:::note
+We need to refactor the request handler to be `async` and return a `Future<Response>` when using the `webSocketHandler`.
+:::
+
+The `webSocketHandler` will handle upgrading `HTTP` requests to WebSocket connections and provides an `onConnection` callback which exposes the `WebSocketChannel` as well as an optional subprotocol.
+
+## Receiving Messages from the Client
+
+Next, we can subscribe to the stream of messages exposed by the `WebSocketChannel`:
+
+```dart
+import 'package:dart_frog/dart_frog.dart';
+import 'package:dart_frog_web_socket/dart_frog_web_socket.dart';
+
+Future<Response> onRequest(RequestContext context) async {
+  final handler = webSocketHandler((channel, protocol) {
+    channel.stream.listen((message) {
+      // Handle incoming client messages.
+      print(message);
+    });
+  });
+  return handler(context);
+}
+```
+
+For simplicity, we are just printing all messages sent by connected clients.
+
+Before moving on, let's verify that a client is able to establish a connection and send a message to our server. To do this, we'll create a simple client in Dart.
+
+## Sending Messages from the Client
+
+Create a new directory called `example` at the project root and create a `pubspec.yaml`:
+
+```yaml
+name: example
+publish_to: none
+
+environment:
+  sdk: '>=2.18.0 <3.0.0'
+
+dependencies:
+  web_socket_channel: ^2.0.0
+```
+
+Next, install the dependencies:
+
+```sh
+dart pub get
+```
+
+Now, create a `main.dart` with the following contents:
+
+```dart
+import 'package:web_socket_channel/web_socket_channel.dart';
+
+void main() {
+  // Connect to the remote WebSocket endpoint.
+  final uri = Uri.parse('ws://localhost:8080/ws');
+  final channel = WebSocketChannel.connect(uri);
+
+  // Send a message to the server.
+  channel.sink.add('hello');
+}
+```
+
+We're using [`package:web_socket_channel`](https://pub.dev/packages/web_socket_channel) to connect to our Dart Frog `/ws` endpoint. We can then send messages to the server by calling `add` on the `WebSocketChannel` sink.
+
+We can run our Dart Frog dev server now:
+
+```sh
+dart_frog dev
+```
+
+:::note
+Be sure to run `dart_frog dev` from the project root.
+:::
+
+Once the server is running in a new terminal, we can run our example client to test the connection:
+
+```sh
+dart example/main.dart
+```
+
+We should see the message we sent in our server logs:
+
+```
+✓ Running on http://localhost:8080 (1.3s)
+The Dart VM service is listening on http://127.0.0.1:8181/YKEF_nbwOpM=/
+The Dart DevTools debugger and profiler is available at: http://127.0.0.1:8181/YKEF_nbwOpM=/devtools/#/?uri=ws%3A%2F%2F127.0.0.1%3A8181%2FYKEF_nbwOpM%3D%2Fws
+[hotreload] Hot reload is enabled.
+hello
+```
+
+## Sending Messages from the Server
+
+Now, let's send a message back to the client from the server. We can do that by adding a message to the channel sink on the server just like we previously did on the client.
+
+```dart
+import 'package:dart_frog/dart_frog.dart';
+import 'package:dart_frog_web_socket/dart_frog_web_socket.dart';
+
+Future<Response> onRequest(RequestContext context) async {
+  final handler = webSocketHandler((channel, protocol) {
+    channel.stream.listen((message) {
+      // Handle incoming client messages.
+      print(message);
+    });
+
+    // Send a message back to the client.
+    channel.sink.add('hi');
+  });
+  return handler(context);
+}
+```
+
+## Receiving Messages from the Server
+
+Lastly, we need to update the client code to subscribe to messages from the server.
+
+```dart
+import 'package:web_socket_channel/web_socket_channel.dart';
+
+void main() {
+  // Connect to the remote WebSocket endpoint.
+  final uri = Uri.parse('ws://localhost:8080/ws');
+  final channel = WebSocketChannel.connect(uri);
+
+  // Send a message to the server.
+  channel.sink.add('hello');
+
+  // Subscribe to messages from the server.
+  channel.stream.listen((message) {
+    print(message);
+  });
+}
+```
+
+Once we save all the changes and let the server hot reload, we can run the client code again:
+
+```sh
+dart example/main.dart
+```
+
+And we should see the following output:
+
+**Server**
+
+```sh
+[hotreload] Hot reload is enabled.
+hello
+```
+
+**Client**
+
+```sh
+hi
+```
+
+## Simplifying Things Further
+
+To make things even simpler, we can refactor the route handler implementation in cases where the route is only managing WebSocket connections:
+
+```dart
+import 'package:dart_frog/dart_frog.dart';
+import 'package:dart_frog_web_socket/dart_frog_web_socket.dart';
+
+Handler get onRequest {
+  return webSocketHandler((channel, protocol) {
+    channel.stream.listen((message) {
+      // Handle incoming client messages.
+      print(message);
+    });
+
+    // Send a message back to the client.
+    channel.sink.add('hi');
+  });
+}
+```
+
+## Conclusion
+
+That's it! 🎉
+
+We've successfully established a WebSocket connection between the Dart Frog server and a client. We've also demonstrated how messages can be streamed between a server and one or more clients.

docs/docs/overview.md

@@ -87,6 +87,8 @@ dart_frog build
 
 ✅ Static File Support 📁
 
+✅ WebSocket Support 🔌
+
 🚧 Generated Dart Client Package 📦
 
 🚧 Generated API Documentation 📔

docs/docs/roadmap.md

@@ -45,7 +45,7 @@ In the interest of transparency, we want to share high-level details of our road
 - [ ] CLI `new` command to generate new `routes` and `middleware`
 - [ ] Health Check endpoint for monitoring
 - [ ] Logger which can be configured to adhere to standard log formats (https://cloud.google.com/run/docs/logging)
-- [ ] Websocket support
+- [x] WebSocket support
 - [ ] VSCode/IntelliJ support for DartFrog
   - [ ] Create a new project
   - [ ] New Routes