feat(users): implement rate limiting for users endpoint

- Add `configured_rate_limiter` import to middleware dependencies
- Refactor `permissionSetter` to `rateAndPermissionSetter` to include rate limiting
- Apply rate limiting to GET, PUT, and DELETE requests on users endpoints
- Update middleware documentation to reflect new rate limiting functionality

Author: fulleni

routes/api/v1/users/_middleware.dart

@@ -1,24 +1,26 @@
 import 'package:dart_frog/dart_frog.dart';
 import 'package:flutter_news_app_api_server_full_source_code/src/middlewares/authentication_middleware.dart';
 import 'package:flutter_news_app_api_server_full_source_code/src/middlewares/authorization_middleware.dart';
+import 'package:flutter_news_app_api_server_full_source_code/src/middlewares/configured_rate_limiter.dart';
 import 'package:flutter_news_app_api_server_full_source_code/src/rbac/permissions.dart';
 
 /// Middleware for the `/api/v1/users` route group.
 ///
 /// This middleware performs the following actions:
 /// 1. `requireAuthentication()`: Ensures a user is authenticated for all
 ///    /users/* routes.
-/// 2. `permissionSetter`: A middleware that provides the correct permission string
-///    into the context *only* for the `/users` and `/users/{id}` endpoints.
-///    It ignores sub-routes like `/users/{id}/settings`, leaving them to be
-///    handled by their own more specific middleware.
+/// 2. `rateAndPermissionSetter`: A middleware that applies rate limiting and
+///    provides the correct permission string into the context *only* for the
+///    `/users` and `/users/{id}` endpoints. It ignores sub-routes like
+///    `/users/{id}/settings`, leaving them to be handled by their own more
+///    specific middleware.
 /// 3. `authorizationMiddleware()`: Checks if the authenticated user has the
-///    permission provided by the `permissionSetter`.
+///    permission provided by the `rateAndPermissionSetter`.
 Handler middleware(Handler handler) {
-  // This middleware provides the required permission string into the context.
+  // This middleware applies rate limiting and provides the required permission.
   // It is scoped to only handle `/users` and `/users/{id}`.
   // ignore: prefer_function_declarations_over_variables
-  final permissionSetter = (Handler handler) {
+  final rateAndPermissionSetter = (Handler handler) {
     return (RequestContext context) {
       final request = context.request;
       final pathSegments = request.uri.pathSegments;
@@ -31,36 +33,43 @@ Handler middleware(Handler handler) {
       }
 
       final String permission;
+      final Middleware rateLimiter;
       final isItemRequest = pathSegments.length == 4;
 
       switch (request.method) {
         case HttpMethod.get:
           // Admins can list all users; users can read their own profile.
           permission =
               isItemRequest ? Permissions.userReadOwned : Permissions.userRead;
+          rateLimiter = createReadRateLimiter();
         case HttpMethod.put:
           // Users can update their own profile.
           permission = Permissions.userUpdateOwned;
+          rateLimiter = createWriteRateLimiter();
         case HttpMethod.delete:
           // Users can delete their own profile.
           permission = Permissions.userDeleteOwned;
+          rateLimiter = createWriteRateLimiter();
         default:
           // Disallow any other methods (e.g., POST) on this route group.
           // User creation is handled by the /auth routes.
           return Response(statusCode: 405);
       }
-      // Provide the required permission to the authorization middleware.
-      return handler(
-        context.provide<String>(() => permission),
-      );
+
+      // Apply the selected rate limiter and then provide the permission.
+      return rateLimiter(
+        (context) => handler(
+          context.provide<String>(() => permission),
+        ),
+      )(context);
     };
   };
 
   return handler
       // The authorization middleware runs after the permission has been set.
       .use(authorizationMiddleware())
-      // The permission setter runs after authentication is confirmed.
-      .use(permissionSetter)
+      // The rate limiter and permission setter runs after authentication.
+      .use(rateAndPermissionSetter)
       // Authentication is the first check for all /users/* routes.
       .use(requireAuthentication());
 }