Abuse Guards & Rate Limiting

Relevant source files

The following files were used as context for generating this wiki page:

• app/Support/AbuseGuards/ActionRateLimiter.php
• app/Support/AbuseGuards/SuspiciousActivityLogger.php
• app/Exceptions/Abuse/RateLimitExceededException.php
• app/Support/AbuseGuards/RateLimitKey.php
• tests/Feature/Support/ActionRateLimiterTest.php
• tests/Feature/Filament/UserResourceTest.php
• tests/Feature/Filament/ReportResourceTest.php

Introduction

Abuse Guards and Rate Limiting in RateGuru provide a structured layer to protect the platform from malicious activity, automated spam, and excessive resource consumption. This system is responsible for throttling user actions such as uploading content, commenting, reporting, and voting. By implementing a standardized rate limiting service, the application ensures fair usage and maintains system stability.

The core architecture relies on a specialized ActionRateLimiter service and a utility class for generating consistent cache keys. When limits are reached, the system triggers specific exceptions that can be handled by the UI or API layers to inform users of the cooldown period. Additionally, the project includes administrative tools within the Filament dashboard to monitor suspicious activity and manage user status (e.g., banning or shadowbanning).

Sources: tests/Feature/Support/ActionRateLimiterTest.php, app/Support/AbuseGuards/ActionRateLimiter.php, tests/Feature/Filament/UserResourceTest.php

Architecture & Logic

Rate Limiting Service

The primary component for enforcement is the ActionRateLimiter. This service abstracts the underlying Laravel RateLimiter facade to provide a domain-specific interface for checking and recording hits against specific actions.

Key methods include:

• hitOrFail(string $key, int $maxAttempts, int $decaySeconds, string $message): Increments the counter for a given key and throws a RateLimitExceededException if the limit is exceeded.
• remaining(string $key, int $maxAttempts): Returns the number of attempts left before the limit is reached.

Sources: app/Support/AbuseGuards/ActionRateLimiter.php:7-25, tests/Feature/Support/ActionRateLimiterTest.php:35-42

Rate Limit Key Generation

To ensure consistency across the application, the RateLimitKey final class provides static methods to generate scoped strings for the cache. This prevents key collisions and allows for both general user-level throttling and target-specific throttling (e.g., limiting comments on a specific post).

The diagram above shows how action requests flow through the key generation and enforcement layers.

Sources: app/Support/AbuseGuards/RateLimitKey.php:7-22, tests/Feature/Support/ActionRateLimiterTest.php:48-53

Protected Actions & Configuration

The system defines several default rate-limited actions within the application configuration. These limits are validated through feature tests to ensure they are properly registered.

Action	Description	Configuration Keys
Upload	Limits how often a user can create new posts.	rate_limits.upload.max_attempts, decay_seconds
Comment	Throttles the frequency of user comments.	rate_limits.comment.max_attempts, decay_seconds
Report	Prevents mass reporting of content.	rate_limits.report.max_attempts, decay_seconds
Vote	Controls the rate at which users can submit ratings.	rate_limits.vote.max_attempts, decay_seconds

Sources: tests/Feature/Support/ActionRateLimiterTest.php:9-25

Abuse Monitoring & Administration

Suspicious Activity Logging

While rate limiting provides immediate protection, the SuspiciousActivityLogger (and related administrative widgets) tracks long-term patterns. In the admin dashboard, suspicious users are identified based on their reports count, status (e.g., shadowbanned), or high frequency of reported content.

Sources: app/Support/AbuseGuards/SuspiciousActivityLogger.php, tests/Feature/Filament/ModerationDashboardTest.php:110-130

Reporting System

Users can report Posts and Comments. These reports are stored with a specific reason (e.g., Spam) and a status (e.g., Open). Admins and Moderators use the ReportResource in the Filament panel to review these flags.

The sequence diagram illustrates the flow from a user reporting content (subject to rate limits) to the administrative review process.

Sources: tests/Feature/Filament/ReportResourceTest.php:51-120, app/Enums/ReportStatus.php, app/Enums/ReportReason.php

User Sanctions

Administrators have the authority to manage user statuses through the UserResource. This includes:

• Active: Normal participation.
• Limited: Restricted permissions.
• Shadowbanned: Content is hidden from others without the user's knowledge.
• Banned: Full access restriction.

Sources: tests/Feature/Filament/UserResourceTest.php:33-55, app/Enums/UserStatus.php

Implementation Details

Exception Handling

The RateLimitExceededException is a specialized exception that extends RuntimeException. It is designed to capture the specific error message provided during the hitOrFail call, which typically includes "Slow down" instructions or time-to-wait information.

Sources: app/Exceptions/Abuse/RateLimitExceededException.php:7-10, tests/Feature/Support/ActionRateLimiterTest.php:44-46

Key Structure Code Snippet

The following snippet from RateLimitKey.php demonstrates how keys are structured to incorporate user IDs and target metadata:

final class RateLimitKey
{
    public static function userAction(string $action, User $user): string
    {
        return "rate-limit:{$action}:user:{$user->id}";
    }

    public static function userTarget(
        string $action,
        User $user,
        string $targetType,
        int|string $targetId,
    ): string {
        return "rate-limit:{$action}:user:{$user->id}:target:{$targetType}:{$targetId}";
    }
}

Sources: app/Support/AbuseGuards/RateLimitKey.php:7-22

Summary

The Abuse Guards & Rate Limiting system in RateGuru combines preventative throttling with reactive moderation tools. By using the ActionRateLimiter and RateLimitKey utilities, the project ensures that rate limiting logic is decoupled from business logic and consistently applied across all user-facing actions. Coupled with the Filament-based ReportResource and UserResource, the architecture provides a comprehensive toolkit for maintaining platform integrity.