preparing for another refactoring...

2026-03-29 23:16:41 +02:00
parent 2edd68b0aa
commit b5d4481502
69 changed files with 4329 additions and 1076 deletions
@@ -0,0 +1,65 @@
+# flash-ext-limiter
+
+Rate limiting for the Flash HTTP server. Zero-allocation hot-path, lock-free counters,
+pluggable key resolvers, and two built-in algorithms.
+
+## What it provides
+
+| Component | Description |
+|---|---|
+| `@Limit` | Annotation for class-based handlers — processed once at boot |
+| `Guard` | Programmatic middleware factory for lambda routes |
+| `LimiterConfig` | Resolver registry — map string names to key-extraction lambdas |
+| `FIXED_WINDOW` | Clock-aligned counter reset; minimal memory |
+| `TOKEN_BUCKET` | Continuous refill; absorbs bursts smoothly |
+
+## Dependency
+
+```xml
+<dependency>
+    <groupId>dev.relism</groupId>
+    <artifactId>flash-ext-limiter</artifactId>
+    <version>1.0-SNAPSHOT</version>
+</dependency>
+```
+
+## Quick start
+
+```java
+// Default install — only the built-in "ip" resolver available
+FlashApp.create(8080)
+    .install(new LimiterExtension())
+    .scan("com.example.handlers");
+```
+
+```java
+// With custom resolvers
+LimiterConfig conf = new LimiterConfig()
+    .registerResolver("auth_user", req ->
+        ClaimsHolder.exists() ? ClaimsHolder.user().sub() : "anonymous");
+
+FlashApp.create(8080)
+    .install(new LimiterExtension(conf))
+    .scan("com.example.handlers");
+```
+
+## Installation order
+
+Install `LimiterExtension` **before** authentication extensions. Rate-limit checks
+then short-circuit over-limit requests before expensive token validation runs.
+
+```java
+app.install(new LimiterExtension(conf))   // ← first
+   .install(new OidcExtension(oidcConf))  // ← second
+   .scan("com.example");
+```
+
+## Docs
+
+| File | Contents |
+|---|---|
+| [key-resolvers.md](key-resolvers.md) | Resolver registration, built-in defaults, custom logic |
+| [annotation.md](annotation.md) | `@Limit` reference — all fields and examples |
+| [guard.md](guard.md) | `Guard` for lambda routes — all overloads |
+| [strategies.md](strategies.md) | `FIXED_WINDOW` vs `TOKEN_BUCKET` — algorithm reference |
+| [http-headers.md](http-headers.md) | HTTP compliance — headers and 429 response |