# Getting Started with Turbo Rate Limiter

Welcome to **Turbo Rate Limiter**, a powerful WordPress plugin that protects your website from abuse by limiting the rate at which visitors can make requests to specific areas of your site. This guide will help you understand what the plugin does, its key features, and how to configure it for your needs.

---

## What Is Turbo Rate Limiter?

Turbo Rate Limiter is a rate limiting solution designed specifically for WordPress websites. Rate limiting is a technique used to control the amount of incoming and outgoing traffic to or from a network. In the context of a WordPress site, it helps prevent abuse such as:

- **Brute force attacks** on login pages
- **API abuse** from automated scripts
- **Comment spam** from bots
- **Resource exhaustion** from aggressive crawling
- **DDoS-like behavior** from overly aggressive visitors

The plugin works by monitoring incoming requests to your website and applying rules you define to restrict how often visitors can access certain URLs or URL patterns. When a visitor exceeds the defined limit, the plugin can block the request, redirect the visitor, or take other actions you specify.

---

## Key Features

Turbo Rate Limiter offers a comprehensive set of features to help you protect your WordPress site:

### Flexible URI-Based Filtering

The plugin allows you to create rate limit rules based on any URI pattern on your website. Whether you want to protect your entire `/wp-admin/` area, just your login page, your custom API endpoints, or any other URL structure, you can easily create a filter to match exactly what you need. The matching system supports multiple strategies, from simple exact matches to powerful regular expressions.

### Multiple Match Types

To give you maximum flexibility in defining which requests should be rate limited, the plugin supports five different match types:

- **Exact Match**: Matches a specific URL exactly as written, useful for targeting single URLs like `/wp-login.php`
- **Contains**: Matches any URL that contains a specific string, ideal for matching groups of URLs like all API endpoints
- **Starts With**: Matches URLs beginning with a specific prefix, perfect for protecting entire directories
- **Ends With**: Matches URLs ending with a specific suffix, useful for targeting specific file types
- **Regex**: Uses regular expressions for complex matching needs, giving you maximum control over pattern matching

### Configurable Limit Windows

You can define exactly how many requests are allowed within any time period. The plugin supports time windows measured in seconds, minutes, hours, or days, allowing you to set appropriate limits for different use cases. For example, you might allow 60 requests per minute for API access but only 10 requests per hour for certain sensitive operations.

### Multiple Response Actions

When a visitor exceeds their rate limit, you can choose how the plugin responds:

- **HTTP 429 (Too Many Requests)**: Returns a standard HTTP 429 status code with a friendly error message, the most common and recommended approach
- **Redirect to URL**: Sends the visitor to any URL you specify, useful for redirecting to a custom rate limit page or your homepage
- **Redirect to Page**: Redirects to an existing WordPress page on your site, allowing you to create a custom message page

### Test Mode

Before enabling rate limits that might affect your real visitors, you can use Test Mode to preview how your filters will behave. In Test Mode, the plugin tracks and logs which requests would have been rate limited without actually blocking anyone. This allows you to fine-tune your filters and ensure they match the correct URLs before going live.

### Real-Time Debug Panel

When Debug Mode is enabled, administrators see a floating debug panel on the front end of the site that shows real-time information about rate limiting for the current request. The panel displays the current request URI, your IP address, which filters matched (if any), the current request count, remaining requests, and the overall status. This is invaluable for troubleshooting and verifying that your filters are working as expected.

### Performance Optimized

The plugin is built with performance in mind. It uses transient-based caching to minimize database queries, compiles filter rules for efficient matching, and skips unnecessary processing for requests that don't match any filters. The matching algorithm checks exact matches first (O(1) lookup) before moving to more complex pattern matching, ensuring minimal overhead for your site.

### Internationalization Ready

Turbo Rate Limiter is translation-ready and already includes translations for multiple languages including Arabic, German, Spanish, French, Italian, Japanese, Dutch, Portuguese, Russian, and Chinese. You can easily add more languages or customize existing translations to suit your needs.

---

## How Rate Limiting Works

Understanding the basic flow of how the plugin processes requests will help you configure it more effectively.

### Request Processing Flow

Every time a request comes to your WordPress site, the plugin performs the following steps:

1. **Initialization**: The plugin loads on every request (at the `init` action, early in the WordPress loading process) and checks if rate limiting is enabled globally.

2. **URI Detection**: The plugin captures the request URI, which is the part of the URL after your domain name. For example, if someone visits `https://yoursite.com/wp-login.php`, the URI would be `/wp-login.php`.

3. **Filter Matching**: The plugin checks the request URI against all your configured filters in a specific order, starting with exact matches for efficiency, then progressively more complex matches.

4. **Rate Limit Check**: If a matching filter is found, the plugin checks the request count for the visitor's IP address against the filter's limit and time window.

5. **Action Execution**: If the visitor hasn't exceeded their limit, the request proceeds normally and the count is incremented. If the limit has been exceeded, the configured action (HTTP 429, redirect, etc.) is executed.

6. **Response Headers**: When Test Mode is enabled, an `X-Rate-Limit-Test` header is added to all responses showing the filter name, current count, limit, remaining requests, and whether the request would be blocked. In Live Mode, no response headers are added.

### Understanding Rate Limit Counters

The plugin uses IP-based rate limiting, which means each unique visitor IP address has its own counter for each filter. When a visitor requests a URL that matches a filter, the plugin:

1. Creates a unique key combining the filter ID and the visitor's IP address
2. Checks if a counter exists for that key and retrieves the current count
3. Increments the counter if the time window hasn't expired
4. Resets the counter when the time window expires

This approach ensures that each visitor has their own allowance and cannot exhaust another visitor's rate limit.

---

## Quick Start Guide

Getting started with Turbo Rate Limiter is straightforward. Follow these steps to create your first rate limiting filter.

### ⚠️ Important: Search Engine Considerations

**Turbo Rate Limiter does not exclude search engines or bots from rate limiting.** All requests, including those from Google, Bing, and other search engine crawlers, are subject to your configured rate limits.

**Be cautious when rate limiting URLs you want search engines to crawl.** For example:

- Rate limiting your entire site too aggressively may slow down search engine crawling
- Strict limits on popular pages might prevent search engines from indexing all your content
- API endpoints that feed data to search engines might be affected

**Recommendations:**
- Be generous with limits for public-facing content you want indexed
- Consider higher limits (100-300 requests per minute) for pages that need frequent crawling
- Monitor your crawl stats in Google Search Console to ensure adequate crawling
- Avoid rate limiting critical SEO URLs unless you have a specific abuse issue

If search engine crawling is a concern, consider using higher limits that won't affect normal crawling patterns while still blocking abusive traffic.

### Step 1: Access the Plugin Settings

After activating the plugin, navigate to **Turbo Rate Limiter** in your WordPress admin dashboard. You can find it under the main WordPress admin menu. The settings page shows your current filters at the top, followed by the form to add new filters, and a sidebar with documentation links.

### Step 2: Create Your First Filter

To create a rate limiting filter, fill out the Add New Filter form with the following information:

- **Filter Name**: Enter a descriptive name for the filter, such as "Login Protection" or "API Rate Limit". This name is for your reference and appears in the filters list and debug panel.

- **URI Pattern**: Enter the URI pattern you want to match. For example, `/wp-login.php` to protect the login page, `/api/` to protect all API endpoints, or `?s=` to protect search results.

- **Match Type**: Select how the pattern should be matched. For most cases, "Exact" works well for single URLs, "Contains" works for groups of URLs sharing a common path, and "Starts With" works for entire directories.

- **Request Limit**: Set the maximum number of requests allowed within the time window. For login protection, 10 requests is often sufficient. For APIs, you might allow hundreds of requests per minute.

- **Time Window**: Set the time period for the limit. The standard login protection might allow 10 requests per minute (60 seconds), while API limits might allow 600 requests per minute.

- **Action**: Choose what happens when the limit is exceeded. HTTP 429 is recommended for most cases as it's the standard response and gives clear feedback to legitimate users.

- **Status**: Enable the filter when you're ready for it to start protecting your site.

### Step 3: Test Your Configuration

Before enabling filters that might affect real visitors, use Test Mode to verify your configuration:

1. Scroll to the Test Mode section at the bottom of the settings page
2. Enable Test Mode by checking the box
3. Visit URLs that should match your new filter
4. Check the "Recent Test Matches" table to see which requests would have been blocked
5. Verify that the matches are correct before disabling Test Mode

### Step 4: Enable and Monitor

When you're confident your filters are working correctly:

1. Disable Test Mode
2. Enable Debug Mode to see real-time information for administrators
3. Monitor the filters list to see which filters are active and how many requests they've processed

---

## Recommended Configurations

The following filters are recommended for most WordPress sites. These protect common attack vectors while maintaining good user experience.

### 1. Login Page Protection

Protects the WordPress login page from brute force attacks.

| Setting | Value |
|---------|-------|
| Filter Name | Login Page Protection |
| URI Pattern | `/wp-login.php` |
| Match Type | Starts With |
| Request Limit | 10 requests per 60 seconds |
| Action | HTTP 429 |
| Status | Enabled |

**Why:** Prevents automated scripts from trying thousands of password combinations while allowing legitimate users multiple login attempts.

### 2. Search Protection

Limits abuse of your site's search function.

| Setting | Value |
|---------|-------|
| Filter Name | Search Protection |
| URI Pattern | `/?s=` |
| Match Type | Starts With |
| Request Limit | 30 requests per 60 seconds |
| Action | HTTP 429 |
| Status | Enabled |

**Why:** Prevents keyword scraping and reduces server load from automated search queries.

### 3. XML-RPC Protection

Protects the XML-RPC endpoint, which is commonly exploited for attacks.

| Setting | Value |
|---------|-------|
| Filter Name | XML-RPC Protection |
| URI Pattern | `/xmlrpc.php` |
| Match Type | Exact Match |
| Request Limit | 20 requests per 60 seconds |
| Action | HTTP 429 |
| Status | Optional |

| Setting | Value |
|---------|-------|
| Filter Name | XML-RPC Protection |
| URI Pattern | `/xmlrpc.php/` |
| Match Type | Starts With |
| Request Limit | 20 requests per 60 seconds |
| Action | HTTP 429 |
| Status | Optional |

**Why:** XML-RPC is frequently targeted for brute force attacks and DDoS amplification. Add both filters for complete protection. If you don't use the WordPress mobile app or Jetpack, you can safely disable this endpoint entirely.

---

## Common Use Cases

Here are some common scenarios where Turbo Rate Limiter can protect your WordPress site.

### Protecting the Login Page

One of the most common uses for rate limiting is protecting the WordPress login page from brute force attacks. Attackers often use automated scripts to try thousands of username and password combinations. By limiting requests to `/wp-login.php` (using Starts With match), you can significantly slow down or completely stop these attacks.

For login protection, a typical configuration might allow 10 requests per minute. This is more than enough for legitimate users who might mistype their password a few times, but it will quickly block automated scripts attempting hundreds of guesses per minute.

### API Rate Limiting

If your WordPress site exposes a REST API, rate limiting is essential to prevent abuse. Whether you're running a public API for other applications or just want to protect internal API endpoints, you can create a filter that matches your API URLs (typically `/wp-json/` or `/api/`) and set appropriate limits based on your expected usage patterns.

For public APIs, you might allow 300 requests per minute per IP address. For internal APIs used only by your own applications, you might set higher limits or create separate filters with different limits for different endpoints.

### Search Protection

If your site's search function is being abused by bots or scrapers, you can rate limit requests to search results. Create a filter that matches the search query parameter (typically `?s=`) to limit how often visitors can perform searches. A common configuration allows 30 searches per 60 seconds.

### Comment Spam Reduction

While many comment spam solutions focus on content analysis, rate limiting can help reduce comment spam at the source. By limiting the rate at which new comments can be submitted from a single IP address, you can make it impractical for spammers to submit large volumes of comments.

### Protecting Sensitive Endpoints

Any area of your site that performs resource-intensive operations or exposes sensitive information should be protected. This might include password reset pages, administrative AJAX actions, or any custom endpoints you've created for your site.

---

## Configuration Best Practices

When configuring rate limits for your site, keep these best practices in mind.

### Start Conservative

When first implementing rate limiting, start with generous limits and monitor traffic patterns. You can always tighten restrictions later, but overly aggressive limits will frustrate legitimate users. Use Test Mode extensively to understand your normal traffic patterns before applying restrictions.

### Consider User Experience

Rate limits affect real users, so choose limits that won't interfere with normal site usage. A login page that allows only 5 requests per minute might be too restrictive for legitimate users who occasionally mistype passwords. Balance security with usability.

### Test Thoroughly

Before applying rate limits to production traffic, test thoroughly in a development environment or use Test Mode extensively. Verify that your filters match exactly the URLs you intend to protect and don't accidentally catch legitimate traffic.

### Monitor and Adjust

After enabling rate limits, monitor the filters list regularly to see which filters are being triggered and how traffic patterns change. Adjust limits as needed based on actual usage and any issues that arise.

### Use Multiple Filters

Rather than trying to create one filter that covers everything, use multiple filters for different areas of your site. This gives you fine-grained control and allows different limits for different types of traffic.

---

## Next Steps

Now that you understand the basics of Turbo Rate Limiter, explore these additional resources to get the most out of the plugin:

- **[Match Types Explained](match-types.md)**: Learn more about each match type and when to use them for optimal filter configuration.

- **[Rate Limiting Best Practices](best-practices.md)**: Discover strategies and tips for implementing effective rate limiting on your WordPress site.

- **[FAQ](faq.md)**: Find answers to common questions about configuration, troubleshooting, and best practices.

---

## Need Help?

If you have questions about configuring Turbo Rate Limiter or need assistance with a specific use case, check the FAQ or report an issue through the support links in the plugin's sidebar.

---

*Last updated for Turbo Rate Limiter v1.0.0*