Dart Frog Documentation

Middleware in Dart Frog allows you to execute code before and after a request is processed. It can be used to modify inbound requests, modify outbound responses, or provide dependencies to your routes.

In Dart Frog, middleware is defined by a middleware function exported from a _middleware.dart file located within a subdirectory of the routes folder.

There are two levels of middleware application:

1. Global Middleware: A _middleware.dart file located directly in the routes/ directory is executed for all inbound requests.
2. Route-specific Middleware: A _middleware.dart file located within a specific subdirectory (e.g., routes/hello/_middleware.dart) is executed only for requests matching that route and its children.

import 'package:dart_frog/dart_frog.dart';

Handler middleware(Handler handler) {
  return (context) async {
    // Execute code before request is handled.

    // Forward the request to the respective handler.
    final response = await handler(context);

    // Execute code after request is handled.

    // Return a response.
    return response;
  };
}

The dart_frog_auth package handles Authentication (verifying who a user is). It does not handle Authorization (verifying what a user can do).

• Authentication failure: The middleware automatically returns 401 Unauthorized if the authenticator returns null.
• Authorization failure: You must manually implement checks in your handlers. If a user is authenticated but lacks permission for a specific action, you should return 403 Forbidden.

Example of manual authorization check:

Future<Response> _deleteUser(RequestContext context, String id) async {
  // If there is no authenticated user, `dart_frog_auth` automatically
  // responds with a 401.

  final user = context.read<User>();
  if (user.id != id) {
    // If the current authenticated user is not the owner of the resource,
    // return a forbidden response.
    return Response(statusCode: HttpStatus.forbidden);
  }
  await context.read<UserRepository>().deleteUser(user.id);
  return Response(statusCode: HttpStatus.noContent);
}

The Dart Frog daemon uses specific naming conventions for events to distinguish between operational logs and long-running task progress.

Logging Events

Logs are identified by the logger prefix followed by a severity level. The domain of the log is determined by the operation that generated it (e.g., dev_server.loggerInfo).

Progress Events

Progress events signal the lifecycle of long-running operations (like generating server code). They are identified by the progress prefix and include the following identifiers:

• progressStart: Signals the start of an operation. Includes a progressId for tracking.
• progressUpdate: Signals an update in progress.
• progressCancel: Signals that progress was cancelled.
• progressFail: Signals that progress failed.
• progressComplete: Signals that progress completed successfully.

You can combine package:broadcast_bloc with WebSockets to broadcast state changes to connected clients.

1. Create a BroadcastCubit to manage state.
2. Provide the Cubit via Dart Frog's provider and inject it into the request context using middleware.
3. In the WebSocket handler, use context.read<YourCubit>() to access the instance.
4. Use cubit.subscribe(channel) to link the WebSocket channel to the Cubit's state stream.
5. Use cubit.unsubscribe(channel) in the onDone callback of the stream listener to clean up when the client disconnects.

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) {
      // Subscribe the new client to receive notifications whenever the cubit state changes.
      final cubit = context.read<CounterCubit>()..subscribe(channel);

      // Send the current count to the new client.
      channel.sink.add('${cubit.state}');

      // Listen for messages from the client.
      channel.stream.listen(
        (event) {
          switch (event) {
            case '__increment__':
              cubit.increment();
              break;
            case '__decrement__':
              cubit.decrement();
              break;
            default:
              break;
          }
        },
        // Unsubscribe the channel when the client disconnects.
        onDone: () => cubit.unsubscribe(channel),
      );
    },
  );

  return handler(context);
}