feat(api): implement rate limiting for data routes

- Add rate limiting middleware for /api/v1/data routes
- Implement bypass permission for rate limiting
- Configure rate limit using environment variables
- Update middleware documentation and comments

Author: fulleni

routes/api/v1/data/_middleware.dart

@@ -1,27 +1,60 @@
 import 'package:core/core.dart';
 import 'package:dart_frog/dart_frog.dart';
+import 'package:flutter_news_app_api_server_full_source_code/src/config/environment_config.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 authorization middleware
+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/rate_limiter_middleware.dart';
+import 'package:flutter_news_app_api_server_full_source_code/src/rbac/permission_service.dart';
+import 'package:flutter_news_app_api_server_full_source_code/src/rbac/permissions.dart';
 import 'package:flutter_news_app_api_server_full_source_code/src/registry/model_registry.dart';
 
 /// Middleware specific to the generic `/api/v1/data` route path.
 ///
 /// This middleware chain performs the following in order:
 /// 1.  **Authentication Check (`requireAuthentication`):** Ensures that the user
 ///     is authenticated. If not, it aborts the request with a 401.
-/// 2.  **Model Validation & Context Provision (`_modelValidationAndProviderMiddleware`):**
+/// 2.  **Data Rate Limiting (`_dataRateLimiterMiddleware`):** Applies a
+///     configurable, user-centric rate limit. Bypassed by admin/publisher roles.
+/// 3.  **Model Validation & Context Provision (`_modelValidationAndProviderMiddleware`):**
 ///     - Validates the `model` query parameter.
 ///     - Looks up the `ModelConfig` from the `ModelRegistryMap`.
-///     - Provides the `ModelConfig` and `modelName` into the request context
-///       for downstream middleware and route handlers.
-/// 3.  **Authorization Check (`authorizationMiddleware`):** Enforces role-based
+///     - Provides the `ModelConfig` and `modelName` into the request context.
+/// 4.  **Authorization Check (`authorizationMiddleware`):** Enforces role-based
 ///     and model-specific permissions based on the `ModelConfig` metadata.
 ///     If the user lacks permission, it throws a [ForbiddenException].
 ///
 /// This setup ensures that data routes are protected, have the necessary
 /// model-specific configuration available, and access is authorized before
 /// reaching the final route handler.
 
+// Helper middleware for applying rate limiting to the data routes.
+Middleware _dataRateLimiterMiddleware() {
+  return (handler) {
+    return (context) {
+      final user = context.read<User>();
+      final permissionService = context.read<PermissionService>();
+
+      // Users with the bypass permission are not rate-limited.
+      if (permissionService.hasPermission(
+        user,
+        Permissions.rateLimitingBypass,
+      )) {
+        return handler(context);
+      }
+
+      // For all other users, apply the configured rate limit.
+      // The key is the user's ID, ensuring the limit is per-user.
+      final rateLimitHandler = rateLimiter(
+        limit: EnvironmentConfig.rateLimitDataApiLimit,
+        window: EnvironmentConfig.rateLimitDataApiWindow,
+        keyExtractor: (context) async => context.read<User>().id,
+      )(handler);
+
+      return rateLimitHandler(context);
+    };
+  };
+}
+
 // Helper middleware for model validation and context provision.
 Middleware _modelValidationAndProviderMiddleware() {
   return (handler) {
@@ -79,15 +112,19 @@ Handler middleware(Handler handler) {
   //      resulting in a 401 response via the global `errorHandler`).
   //    - If `User` is present, the request proceeds to the next middleware.
   //
-  // 2. `_modelValidationAndProviderMiddleware()`:
+  // 2. `_dataRateLimiterMiddleware()`:
   //    - This runs if `requireAuthentication()` passes.
+  //    - It checks if the user has a bypass permission. If not, it applies
+  //      the configured rate limit based on the user's ID.
+  //    - If the limit is exceeded, it throws a `ForbiddenException`.
+  //
+  // 3. `_modelValidationAndProviderMiddleware()`:
+  //    - This runs if rate limiting passes.
   //    - It validates the `?model=` query parameter and provides the
   //      `ModelConfig` and `modelName` into the context.
-  //    - If model validation fails, it throws a BadRequestException, caught
-  //      by the global errorHandler.
-  //    - If successful, it calls the next handler in the chain (authorizationMiddleware).
+  //    - If model validation fails, it throws a `BadRequestException`.
   //
-  // 3. `authorizationMiddleware()`:
+  // 4. `authorizationMiddleware()`:
   //    - This runs if `_modelValidationAndProviderMiddleware()` passes.
   //    - It reads the `User`, `modelName`, and `ModelConfig` from the context.
   //    - It checks if the user has permission to perform the requested HTTP
@@ -97,14 +134,15 @@ Handler middleware(Handler handler) {
   //    - If successful, it calls the next handler in the chain (the actual
   //      route handler).
   //
-  // 4. Actual Route Handler (from `index.dart` or `[id].dart`):
+  // 5. Actual Route Handler (from `index.dart` or `[id].dart`):
   //    - This runs last, only if all preceding middlewares pass. It will have
   //      access to a non-null `User`, `ModelConfig`, and `modelName` from the context.
   //    - It performs the data operation and any necessary handler-level
   //      ownership checks (if flagged by `ModelActionPermission.requiresOwnershipCheck`).
   //
   return handler
-      .use(authorizationMiddleware()) // Applied third (inner)
-      .use(_modelValidationAndProviderMiddleware()) // Applied second
+      .use(authorizationMiddleware()) // Applied fourth (inner-most)
+      .use(_modelValidationAndProviderMiddleware()) // Applied third
+      .use(_dataRateLimiterMiddleware()) // Applied second
       .use(requireAuthentication()); // Applied first (outermost)
 }