Add CustomBaseRateLimiter extension for descriptor filtering, key derivation, and duplicate handling

[Copilot]

BaseRateLimiter has no extension points for customizing cache key generation, skipping rate limit checks for specific descriptors, or deduplicating descriptors before processing. This PR adds CustomBaseRateLimiter as a pure additive wrapper with three optional hooks.

Core (src/limiter/)

• custom_base_limiter.go — Embeds *BaseRateLimiter, overrides GenerateCacheKeys to apply filter and derivation hooks, adds HandleDuplicates. Fluent builder API via With* methods.
• descriptor_filters.go — AllowAll, DenyAll, FilterByKey, FilterByValue, FilterByKeyValue
• key_derivations.go — IdentityKeyDerivation, PrefixKeyDerivation, SuffixKeyDerivation, HashSensitiveValueKeyDerivation, NormalizeKeyDerivation
• duplicate_handlers.go — PassThroughDuplicateHandler, KeepFirstDuplicateHandler, KeepLastDuplicateHandler

Tests (test/limiter/)

• custom_base_limiter_test.go — 26 unit tests covering hook behaviour, pre-built helpers, and edge cases (e.g. derivation not called when key is already empty)
• examples_test.go — 4 integration-style tests: internal-traffic bypass, multi-tenant key namespacing, deduplication, sensitive-token hashing

Usage

cl := limiter.NewCustomBaseRateLimit(timeSource, jitterRand, expJitter, localCache, nearLimitRatio, prefix, statsManager).
    WithDescriptorFilter(limiter.FilterByKeyValue("client_type", "internal")).
    WithKeyDerivation(limiter.HashSensitiveValueKeyDerivation("api_token")).
    WithDuplicateHandler(limiter.KeepFirstDuplicateHandler())

// Before generating keys, deduplicate:
descriptors, limits = cl.HandleDuplicates(request.Descriptors, limits)
cacheKeys := cl.GenerateCacheKeys(request, limits, hitsAddends)

• DescriptorFilterFn returning true sets the cache key to "", causing an immediate OK without a cache lookup.
• KeyDerivationFn is skipped when the key is already empty.
• No existing files modified; a CustomBaseRateLimiter with no hooks set is behaviourally identical to BaseRateLimiter.

See CUSTOMIZATION_README.md for the full integration guide.

Original prompt

Add CustomBaseRateLimiter extension for advanced rate limit customization with support for descriptor filtering, key derivation, and duplicate handling. This includes:

1. Core implementation of CustomBaseRateLimiter in src/limiter/custom_base_limiter.go
2. Pre-built descriptor filters in src/limiter/descriptor_filters.go
3. Pre-built key derivation functions in src/limiter/key_derivations.go
4. Pre-built duplicate handlers in src/limiter/duplicate_handlers.go
5. Comprehensive unit tests in test/limiter/custom_base_limiter_test.go
6. Real-world examples in test/limiter/examples_test.go
7. Complete documentation in CUSTOMIZATION_README.md

The implementation extends BaseRateLimiter with three customization hooks:

• DescriptorFilterFn: Skip cache lookup for specific descriptors (allow/deny without cache)
• KeyDerivationFn: Customize cache key generation (sanitize, normalize, hash sensitive data)
• DuplicateHandlerFn: Handle duplicate descriptors intelligently (deduplication, retry logic)

Key features:

• Zero modifications to existing code (pure addition)
• Backward compatible with all existing deployments
• Fluent API for easy chaining of customizations
• Pre-built implementations for common use cases
• Fully tested with comprehensive unit tests
• Well documented with integration guide and examples

This pull request was created from Copilot chat.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.