Choosing an identifier

Overview

In the Guardian rate limiting system, the identifier is a crucial component that determines how rate limits are applied and tracked. This guide will help you understand the importance of identifiers, how to choose them effectively, and how they are processed within the system.

Importance of Identifiers

The identifier serves as a unique key for storing and retrieving rate limit data. Each distinct identifier will have its own set of cache entries, allowing for granular control over rate limiting for different resources, users, or actions.

Relationship with Cache Stores

It's essential to understand that cache stores are made against the identifier. This means:

1. Each unique identifier will have its own separate cache entries.

2. Rate limits are tracked and enforced independently for each identifier.

3. Clearing or resetting rate limits for one identifier won't affect others.

Choosing an Identifier

When selecting an identifier, consider the following:

1. Uniqueness: Choose identifiers that uniquely represent the entity or action you're rate limiting.

2. Granularity: More specific identifiers allow for more fine-grained control.

3. Consistency: Use consistent identifiers for the same entities or actions across your application.

Examples of good identifiers:

• User IDs: user_123

• IP addresses: ip_192.168.1.1

• API endpoints: api_get_users

• Combinations: user_123_api_get_users

Identifier Processing

Guardian processes the identifier to ensure it's safe for use as a cache key. Here's how the identifier is parsed:

1. Character Sanitization: Only alphanumeric characters, underscores, and hyphens are allowed. All other characters are replaced with underscores.

   $safe = preg_replace('/[^a-zA-Z0-9_-]/', '_', $identifier);

2. Prefix Handling:

   • If a prefix is provided (default is 'guardian'), it's sanitized and added to the beginning of the identifier.

   • If no prefix is provided and the sanitized identifier doesn't start with a letter, 'id_' is prepended.

3. Duplicate Character Removal: Consecutive underscores are reduced to a single underscore.

4. Trailing Underscore Removal: Any trailing underscore is removed from the identifier.

5. Case Conversion: The entire identifier is converted to lowercase.

6. Length Limitation: The final identifier is truncated to a maximum of 100 characters (including the prefix).

7. Empty Check: If the resulting identifier is empty or just 'id_', an exception is thrown.

Example

$originalIdentifier = "user@123_action/get";
$guardian = new Guardian($originalIdentifier, $cache);

// Internally, this becomes: "guardian_user_123_action_get"

Best Practices

1. Use Meaningful Identifiers: Choose identifiers that clearly represent what's being rate limited.

2. Be Consistent: Use the same identifier format for similar entities or actions.

3. Consider Combining Factors: For more specific rate limiting, combine multiple factors in your identifier (e.g., "{$userId}_{$action}_{$resourceId}").

4. Be Aware of Truncation: Remember that very long identifiers will be truncated to 100 characters.

5. Avoid Relying on Case: Since identifiers are converted to lowercase, don't rely on case for uniqueness.

6. Consider Special Character Replacement: Be aware that special characters will be replaced with underscores.

Security Considerations

• Don't include sensitive information in identifiers, as they may be logged or visible in cache systems.

• Be cautious about using easily guessable identifiers that could allow bad actors to manipulate rate limits.

Troubleshooting

• If rate limits aren't behaving as expected, double-check that you're using consistent identifiers.

• Remember that changing an identifier (even slightly) will result in a new set of cache entries and rate limit tracking.

By carefully choosing and consistently using identifiers, you can create a robust and granular rate limiting system with Guardian. The identifier is key to how Guardian tracks and enforces rate limits, so give careful consideration to your identifier strategy when implementing Guardian in your application.