docs: add web_socket_counter example (#450)

felangel · web-flow · commit 95334109823a · 2022-12-16T13:12:33.000-06:00
diff --git a/.github/workflows/examples_web_socket_counter.yaml b/.github/workflows/examples_web_socket_counter.yaml
@@ -0,0 +1,34 @@
+name: examples/web_socket_counter
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+on:
+  pull_request:
+    paths:
+      - "examples/web_socket_counter/routes/**"
+      - "examples/web_socket_counter/lib/**"
+      - "examples/web_socket_counter/test/**"
+      - "examples/web_socket_counter/e2e/**"
+      - ".github/workflows/examples_counter.yaml"
+      - "packages/dart_frog/lib/**"
+      - "packages/dart_frog/pubspec.yaml"
+      - "packages/dart_frog_cli/lib/**"
+      - "packages/dart_frog_cli/pubspec.yaml"
+    branches:
+      - main
+
+jobs:
+  build:
+    uses: VeryGoodOpenSource/very_good_workflows/.github/workflows/dart_package.yml@v1
+    with:
+      working_directory: examples/web_socket_counter
+      analyze_directories: "routes test"
+      report_on: "routes"
+
+  docker:
+    uses: ./.github/workflows/.docker_tests.yaml
+    with:
+      setup: rm pubspec_overrides.yaml && dart pub global activate --source path ../../packages/dart_frog_cli
+      working_directory: examples/web_socket_counter
diff --git a/examples/web_socket_counter/.gitignore b/examples/web_socket_counter/.gitignore
@@ -0,0 +1,13 @@
+# See https://www.dartlang.org/guides/libraries/private-files
+
+# Files and directories created by pub
+.dart_tool/
+.packages
+pubspec.lock
+
+# Files and directories created by dart_frog
+build/
+.dart_frog
+
+# Test related files
+coverage/
diff --git a/examples/web_socket_counter/README.md b/examples/web_socket_counter/README.md
@@ -0,0 +1,12 @@
+# WebSocket Counter
+
+[![style: very good analysis][very_good_analysis_badge]][very_good_analysis_link]
+[![License: MIT][license_badge]][license_link]
+[![Powered by Dart Frog](https://img.shields.io/endpoint?url=https://tinyurl.com/dartfrog-badge)](https://dartfrog.vgv.dev)
+
+An example counter app built with `dart_frog` using WebSockets.
+
+[license_badge]: https://img.shields.io/badge/license-MIT-blue.svg
+[license_link]: https://opensource.org/licenses/MIT
+[very_good_analysis_badge]: https://img.shields.io/badge/style-very_good_analysis-B22C89.svg
+[very_good_analysis_link]: https://pub.dev/packages/very_good_analysis
diff --git a/examples/web_socket_counter/analysis_options.yaml b/examples/web_socket_counter/analysis_options.yaml
@@ -0,0 +1,7 @@
+include: package:very_good_analysis/analysis_options.3.1.0.yaml
+analyzer:
+  exclude:
+    - build/**
+linter:
+  rules:
+    file_names: false
diff --git a/examples/web_socket_counter/e2e/ws_test.dart b/examples/web_socket_counter/e2e/ws_test.dart
@@ -0,0 +1,29 @@
+import 'package:test/test.dart';
+import 'package:web_socket_client/web_socket_client.dart';
+import 'package:web_socket_counter/counter/models/message.dart';
+
+void main() {
+  group('E2E', () {
+    test('establishes connection and receives the initial count.', () async {
+      final socket = WebSocket(Uri.parse('ws://localhost:8080/ws'));
+      await expectLater(socket.messages, emits('0'));
+      socket.close();
+    });
+
+    test('sending an increment message increases the count by 1', () async {
+      final socket = WebSocket(Uri.parse('ws://localhost:8080/ws'));
+      await expectLater(socket.messages, emits('0'));
+      socket.send(Message.increment.value);
+      await expectLater(socket.messages, emits('1'));
+      socket.close();
+    });
+
+    test('sending a decrement message decreases the count by 1', () async {
+      final socket = WebSocket(Uri.parse('ws://localhost:8080/ws'));
+      await expectLater(socket.messages, emits('1'));
+      socket.send(Message.decrement.value);
+      await expectLater(socket.messages, emits('0'));
+      socket.close();
+    });
+  });
+}
diff --git a/examples/web_socket_counter/lib/counter/counter.dart b/examples/web_socket_counter/lib/counter/counter.dart
@@ -0,0 +1,3 @@
+export 'cubit/counter_cubit.dart';
+export 'middleware/counter_provider.dart';
+export 'models/message.dart';
diff --git a/examples/web_socket_counter/lib/counter/cubit/counter_cubit.dart b/examples/web_socket_counter/lib/counter/cubit/counter_cubit.dart
@@ -0,0 +1,15 @@
+import 'package:broadcast_bloc/broadcast_bloc.dart';
+
+/// {@template counter_cubit}
+/// A cubit which manages the value of a count.
+/// {@endtemplate}
+class CounterCubit extends BroadcastCubit<int> {
+  /// {@macro counter_cubit}
+  CounterCubit() : super(0);
+
+  /// Increment the current state.
+  void increment() => emit(state + 1);
+
+  /// Decrement the current state.
+  void decrement() => emit(state - 1);
+}
diff --git a/examples/web_socket_counter/lib/counter/middleware/counter_provider.dart b/examples/web_socket_counter/lib/counter/middleware/counter_provider.dart
@@ -0,0 +1,7 @@
+import 'package:dart_frog/dart_frog.dart';
+import 'package:web_socket_counter/counter/counter.dart';
+
+final _counter = CounterCubit();
+
+/// Provides an instance of a [CounterCubit].
+final counterProvider = provider<CounterCubit>((_) => _counter);
diff --git a/examples/web_socket_counter/lib/counter/models/message.dart b/examples/web_socket_counter/lib/counter/models/message.dart
@@ -0,0 +1,16 @@
+/// {@template message}
+/// WebSocket counter messages.
+/// {@endtemplate}
+enum Message {
+  /// An increment message.
+  increment('__increment__'),
+
+  /// A decrement message.
+  decrement('__decrement__');
+
+  /// {@macro message}
+  const Message(this.value);
+
+  /// The value of the message.
+  final String value;
+}
diff --git a/examples/web_socket_counter/pubspec.yaml b/examples/web_socket_counter/pubspec.yaml
@@ -0,0 +1,20 @@
+name: web_socket_counter
+description: An example counter app built with Dart Frog using WebSockets.
+version: 1.0.0+1
+publish_to: none
+
+environment:
+  sdk: ">=2.18.0 <3.0.0"
+
+dependencies:
+  broadcast_bloc: ^0.1.0-dev.1
+  dart_frog: ^0.3.0
+  dart_frog_web_socket: ^0.1.0-dev.1
+
+dev_dependencies:
+  bloc_test: ^9.1.0
+  http: ^0.13.5
+  mocktail: ^0.3.0
+  test: ^1.19.2
+  very_good_analysis: ^3.1.0
+  web_socket_client: ^0.1.0-dev.1
diff --git a/examples/web_socket_counter/pubspec_overrides.yaml b/examples/web_socket_counter/pubspec_overrides.yaml
@@ -0,0 +1,3 @@
+dependency_overrides:
+  dart_frog:
+    path: ../../packages/dart_frog
diff --git a/examples/web_socket_counter/routes/_middleware.dart b/examples/web_socket_counter/routes/_middleware.dart
@@ -0,0 +1,4 @@
+import 'package:dart_frog/dart_frog.dart';
+import 'package:web_socket_counter/counter/counter.dart';
+
+Handler middleware(Handler handler) => handler.use(counterProvider);
diff --git a/examples/web_socket_counter/routes/ws.dart b/examples/web_socket_counter/routes/ws.dart
@@ -0,0 +1,42 @@
+import 'package:dart_frog/dart_frog.dart';
+import 'package:dart_frog_web_socket/dart_frog_web_socket.dart';
+import 'package:web_socket_counter/counter/counter.dart';
+
+Future<Response> onRequest(RequestContext context) async {
+  final handler = webSocketHandler(
+    (channel, protocol) {
+      final cubit = context.read<CounterCubit>()..subscribe(channel);
+
+      channel.sink.add('${cubit.state}');
+
+      channel.stream.listen(
+        (event) {
+          switch ('$event'.toMessage()) {
+            case Message.increment:
+              cubit.increment();
+              break;
+            case Message.decrement:
+              cubit.decrement();
+              break;
+            case null:
+              break;
+          }
+        },
+        onDone: () => cubit.unsubscribe(channel),
+      );
+    },
+  );
+
+  return handler(context);
+}
+
+extension on String {
+  Message? toMessage() {
+    for (final message in Message.values) {
+      if (this == message.value) {
+        return message;
+      }
+    }
+    return null;
+  }
+}
diff --git a/examples/web_socket_counter/test/counter/cubit/counter_cubit_test.dart b/examples/web_socket_counter/test/counter/cubit/counter_cubit_test.dart
@@ -0,0 +1,25 @@
+import 'package:bloc_test/bloc_test.dart';
+import 'package:test/test.dart';
+import 'package:web_socket_counter/counter/cubit/counter_cubit.dart';
+
+void main() {
+  group('CounterCubit', () {
+    test('initial state is 0', () {
+      expect(CounterCubit().state, equals(0));
+    });
+
+    blocTest<CounterCubit, int>(
+      'emits [1] when increment is called',
+      build: CounterCubit.new,
+      act: (cubit) => cubit.increment(),
+      expect: () => [1],
+    );
+
+    blocTest<CounterCubit, int>(
+      'emits [-1] when decrement is called',
+      build: CounterCubit.new,
+      act: (cubit) => cubit.decrement(),
+      expect: () => [-1],
+    );
+  });
+}
diff --git a/examples/web_socket_counter/test/routes/_middleware_test.dart b/examples/web_socket_counter/test/routes/_middleware_test.dart
@@ -0,0 +1,28 @@
+import 'package:dart_frog/dart_frog.dart';
+import 'package:mocktail/mocktail.dart';
+import 'package:test/test.dart';
+import 'package:web_socket_counter/counter/counter.dart';
+
+import '../../routes/_middleware.dart';
+
+class _MockRequestContext extends Mock implements RequestContext {}
+
+void main() {
+  group('middleware', () {
+    test('provides a CounterCubit instance.', () async {
+      CounterCubit? cubit;
+      final handler = middleware(
+        (context) {
+          cubit = context.read<CounterCubit>();
+          return Response();
+        },
+      );
+      final request = Request.get(Uri.parse('http://localhost/'));
+      final context = _MockRequestContext();
+      when(() => context.request).thenReturn(request);
+
+      await handler(context);
+      expect(cubit, isNotNull);
+    });
+  });
+}
diff --git a/examples/web_socket_counter/test/routes/ws_test.dart b/examples/web_socket_counter/test/routes/ws_test.dart
@@ -0,0 +1,104 @@
+import 'dart:io';
+
+import 'package:bloc_test/bloc_test.dart';
+import 'package:dart_frog/dart_frog.dart';
+import 'package:mocktail/mocktail.dart';
+import 'package:test/test.dart';
+import 'package:web_socket_client/web_socket_client.dart';
+import 'package:web_socket_counter/counter/counter.dart';
+
+import '../../routes/ws.dart' as route;
+
+class _MockCounterCubit extends MockCubit<int> implements CounterCubit {}
+
+void main() {
+  late HttpServer server;
+
+  late CounterCubit counterCubit;
+
+  tearDown(() => server.close(force: true));
+
+  group('GET /ws', () {
+    setUp(() {
+      counterCubit = _MockCounterCubit();
+      when(() => counterCubit.state).thenReturn(0);
+    });
+
+    test('establishes connection and receives the initial count.', () async {
+      const initialState = 42;
+      when(() => counterCubit.state).thenReturn(initialState);
+      server = await serve(
+        (context) => route.onRequest(
+          context.provide<CounterCubit>(() => counterCubit),
+        ),
+        InternetAddress.anyIPv4,
+        0,
+      );
+      final socket = WebSocket(Uri.parse('ws://localhost:${server.port}'));
+
+      await expectLater(socket.messages, emits('$initialState'));
+
+      socket.close();
+    });
+
+    test('sending an increment message calls increment.', () async {
+      server = await serve(
+        (context) => route.onRequest(
+          context.provide<CounterCubit>(() => counterCubit),
+        ),
+        InternetAddress.anyIPv4,
+        0,
+      );
+      final socket = WebSocket(Uri.parse('ws://localhost:${server.port}'));
+
+      await expectLater(socket.messages, emits(anything));
+
+      socket.send(Message.increment.value);
+
+      await untilCalled(counterCubit.increment);
+      verify(counterCubit.increment).called(1);
+
+      socket.close();
+    });
+
+    test('sending a decrement message calls decrement.', () async {
+      server = await serve(
+        (context) => route.onRequest(
+          context.provide<CounterCubit>(() => counterCubit),
+        ),
+        InternetAddress.anyIPv4,
+        0,
+      );
+      final socket = WebSocket(Uri.parse('ws://localhost:${server.port}'));
+
+      await expectLater(socket.messages, emits(anything));
+
+      socket.send(Message.decrement.value);
+
+      await untilCalled(counterCubit.decrement);
+      verify(counterCubit.decrement).called(1);
+
+      socket.close();
+    });
+
+    test('ignores invalid messages.', () async {
+      server = await serve(
+        (context) => route.onRequest(
+          context.provide<CounterCubit>(() => counterCubit),
+        ),
+        InternetAddress.anyIPv4,
+        0,
+      );
+      final socket = WebSocket(Uri.parse('ws://localhost:${server.port}'));
+
+      await expectLater(socket.messages, emits(anything));
+
+      socket.send('invalid_message');
+
+      verifyNever(counterCubit.increment);
+      verifyNever(counterCubit.decrement);
+
+      socket.close();
+    });
+  });
+}

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+export 'cubit/counter_cubit.dart';`
	`2`	`+export 'middleware/counter_provider.dart';`
	`3`	`+export 'models/message.dart';`