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,22 @@
+package dev.relism.ext.limiter;
+
+import java.util.concurrent.atomic.AtomicLong;
+
+/**
+ * Pre-allocated per-key rate limit state. Holds two {@link AtomicLong} slots whose
+ * semantics are strategy-specific:
+ *
+ * <ul>
+ *   <li><b>FIXED_WINDOW</b>: {@code slot0} = packed {@code (epoch << 32 | count)},
+ *       {@code slot1} unused.</li>
+ *   <li><b>TOKEN_BUCKET</b>: {@code slot0} = tokens × 1000 (scaled),
+ *       {@code slot1} = last-refill timestamp (ms since epoch).</li>
+ * </ul>
+ *
+ * <p>Buckets are created once per unique key (via {@link BucketStore}) and reused
+ * for the lifetime of the server — zero allocation on the warm path.
+ */
+public final class Bucket {
+    public final AtomicLong slot0 = new AtomicLong(0L);
+    public final AtomicLong slot1 = new AtomicLong(0L);
+}
@@ -0,0 +1,28 @@
+package dev.relism.ext.limiter;
+
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Thread-safe store of pre-allocated {@link Bucket} instances keyed by partition key.
+ *
+ * <p>On the warm path (key already seen), {@link #get} performs a single
+ * {@link ConcurrentHashMap} lookup — no allocation. On the cold path (new key),
+ * {@code computeIfAbsent} allocates exactly one {@link Bucket} and inserts it.
+ *
+ * <p>Buckets accumulate indefinitely; for workloads with unbounded unique keys
+ * (e.g. one-shot crawlers), consider periodic store replacement or a bounded
+ * LRU map implementation.
+ */
+public final class BucketStore {
+
+    private final ConcurrentHashMap<String, Bucket> map = new ConcurrentHashMap<>();
+
+    /**
+     * Returns the bucket for {@code key}, creating one if absent.
+     * Two threads racing on the same new key are guaranteed to receive the same bucket instance.
+     */
+    public Bucket get(String key) {
+        Bucket b = map.get(key);
+        return b != null ? b : map.computeIfAbsent(key, k -> new Bucket());
+    }
+}
@@ -0,0 +1,69 @@
+package dev.relism.ext.limiter;
+
+import dev.relism.routing.Middleware;
+
+import java.util.concurrent.TimeUnit;
+
+/**
+ * Manual rate-limit guard for lambda routes.
+ *
+ * <p>Available via {@link dev.relism.extension.FlashContext}:
+ * <pre>{@code
+ * Guard guard = ctx.require(Guard.class);
+ * }</pre>
+ *
+ * <p>{@link #limit} creates a {@link Middleware} that is composed once at route registration
+ * time — the resolver lambda is captured directly from the registry (no runtime map lookup):
+ * <pre>{@code
+ * // 50 req/s per IP — fixed window (default)
+ * app.get("/api/search", handler)
+ *    .with(guard.limit("ip", 50, 1, TimeUnit.SECONDS));
+ *
+ * // 10 req/min per authenticated user — token bucket
+ * app.post("/api/export", handler)
+ *    .with(guard.limit("auth_user", 10, 1, TimeUnit.MINUTES, LimitStrategy.TOKEN_BUCKET));
+ * }</pre>
+ *
+ * <p>The resolver name is looked up once here (at {@code .with(guard.limit(...))} call time,
+ * i.e. during app wiring, not on each request). If the name is not registered,
+ * {@link dev.relism.exceptions.InitializationException} is thrown immediately.
+ */
+public final class Guard {
+
+    private final LimiterConfig config;
+    private final BucketStore   store;
+
+    Guard(LimiterConfig config, BucketStore store) {
+        this.config = config;
+        this.store  = store;
+    }
+
+    /**
+     * Returns a {@link Middleware} that enforces the given rate limit using
+     * {@link LimitStrategy#FIXED_WINDOW}.
+     *
+     * @param resolverKey name registered via {@link LimiterConfig#registerResolver}
+     * @param requests    maximum requests allowed per window
+     * @param window      window duration in {@code unit}
+     * @param unit        time unit for {@code window}
+     */
+    public Middleware limit(String resolverKey, int requests, long window, TimeUnit unit) {
+        return limit(resolverKey, requests, window, unit, LimitStrategy.FIXED_WINDOW);
+    }
+
+    /**
+     * Returns a {@link Middleware} that enforces the given rate limit with the specified strategy.
+     *
+     * @param resolverKey name registered via {@link LimiterConfig#registerResolver}
+     * @param requests    maximum requests allowed per window
+     * @param window      window duration in {@code unit}
+     * @param unit        time unit for {@code window}
+     * @param strategy    rate-limit algorithm
+     */
+    public Middleware limit(String resolverKey, int requests, long window, TimeUnit unit, LimitStrategy strategy) {
+        // Fail-fast: resolve the lambda at wiring time, not at request time.
+        KeyResolver resolver = config.requireResolver(resolverKey);
+        LimitConfig cfg      = new LimitConfig(requests, unit.toMillis(window), strategy.create());
+        return LimiterExtension.buildMiddleware(resolver, cfg, store);
+    }
+}
@@ -0,0 +1,20 @@
+package dev.relism.ext.limiter;
+
+import dev.relism.models.Request;
+
+/**
+ * Extracts a partition key from an incoming request.
+ *
+ * <p>The resolved key identifies who the rate limit applies to — an IP address,
+ * an authenticated user ID, an API key, etc. Implementations are captured once
+ * at route registration time and called directly (no registry lookup) on every request.
+ *
+ * <pre>{@code
+ * conf.registerResolver("ip",       req -> req.header("X-Forwarded-For"));
+ * conf.registerResolver("auth_user", req -> ClaimsHolder.user().sub());
+ * }</pre>
+ */
+@FunctionalInterface
+public interface KeyResolver {
+    String resolve(Request req);
+}
@@ -0,0 +1,45 @@
+package dev.relism.ext.limiter;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * Applies a rate limit to a class-based {@link dev.relism.models.RequestHandler}.
+ *
+ * <p>The annotation is processed at boot time by the {@link LimiterExtension} annotation
+ * processor. If {@link #key()} names a resolver that was never registered,
+ * startup fails immediately with {@link dev.relism.exceptions.InitializationException}.
+ *
+ * <pre>{@code
+ * // 100 req/s per client IP — fixed window
+ * @Limit(requests = 100, window = 1)
+ * public class SearchHandler extends RequestHandler { ... }
+ *
+ * // 20 req/min per authenticated user — token bucket
+ * @Limit(key = "auth_user", requests = 20, window = 1, windowUnit = TimeUnit.MINUTES,
+ *        strategy = LimitStrategy.TOKEN_BUCKET)
+ * public class ExpensiveHandler extends RequestHandler { ... }
+ * }</pre>
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Limit {
+
+    /** Name of the resolver registered via {@link LimiterConfig#registerResolver}. Default: {@code "ip"}. */
+    String key() default "ip";
+
+    /** Maximum number of requests allowed per {@link #window()}. */
+    int requests();
+
+    /** Window duration in {@link #windowUnit()} units. */
+    long window();
+
+    /** Unit for {@link #window()}. Default: {@link TimeUnit#SECONDS}. */
+    TimeUnit windowUnit() default TimeUnit.SECONDS;
+
+    /** Rate-limit algorithm. Default: {@link LimitStrategy#FIXED_WINDOW}. */
+    LimitStrategy strategy() default LimitStrategy.FIXED_WINDOW;
+}
@@ -0,0 +1,11 @@
+package dev.relism.ext.limiter;
+
+/**
+ * Immutable configuration snapshot for a single rate-limit rule.
+ * Created once at boot time and captured directly in the middleware closure.
+ *
+ * @param limit      Maximum allowed requests per window.
+ * @param windowMs   Window duration in milliseconds.
+ * @param strategy   Strategy instance bound to this rule (one per rule, not shared).
+ */
+public record LimitConfig(int limit, long windowMs, RateLimitStrategy strategy) {}
@@ -0,0 +1,45 @@
+package dev.relism.ext.limiter;
+
+import dev.relism.ext.limiter.strategy.FixedWindowStrategy;
+import dev.relism.ext.limiter.strategy.TokenBucketStrategy;
+
+/**
+ * Enumeration of built-in rate-limit algorithms. Each constant is a factory
+ * for its corresponding {@link RateLimitStrategy} implementation.
+ *
+ * <p>New algorithms can be added here without touching the rest of the extension.
+ * The enum value is referenced by {@link Limit#strategy()} so user code refers
+ * to the algorithm by name ({@code LimitStrategy.FIXED_WINDOW}) rather than
+ * instantiating strategy objects directly.
+ *
+ * <pre>{@code
+ * @Limit(key = "ip", requests = 100, window = 1, strategy = LimitStrategy.TOKEN_BUCKET)
+ * public class SearchHandler extends RequestHandler { ... }
+ * }</pre>
+ */
+public enum LimitStrategy {
+
+    /**
+     * Fixed-window counter: resets to zero at each clock-aligned window boundary.
+     * Simple, minimal memory, but allows up to 2× the limit in bursts that straddle
+     * two windows.
+     */
+    FIXED_WINDOW {
+        @Override
+        public RateLimitStrategy create() { return new FixedWindowStrategy(); }
+    },
+
+    /**
+     * Token-bucket: tokens refill continuously. Smooth burst absorption — a client
+     * that was idle accumulates tokens and can fire a short burst, but sustained
+     * excess traffic is rejected. Preferred for API endpoints where occasional bursts
+     * are legitimate.
+     */
+    TOKEN_BUCKET {
+        @Override
+        public RateLimitStrategy create() { return new TokenBucketStrategy(); }
+    };
+
+    /** Creates a fresh, stateless {@link RateLimitStrategy} instance for this algorithm. */
+    public abstract RateLimitStrategy create();
+}
@@ -0,0 +1,82 @@
+package dev.relism.ext.limiter;
+
+import dev.relism.exceptions.InitializationException;
+
+import java.net.InetSocketAddress;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/**
+ * Extension configuration: holds the named {@link KeyResolver} registry.
+ *
+ * <p>Resolvers are registered during the <em>config phase</em> (before {@code install}).
+ * After {@link LimiterExtension#install} is called, the registry is consulted once per
+ * route/handler at boot to capture the resolver lambda directly into the middleware closure.
+ * There is no map lookup on the request hot-path.
+ *
+ * <p>The built-in {@code "ip"} resolver is always present and extracts the client IP from
+ * {@code X-Forwarded-For} (first address) or {@code X-Real-IP}. Override it with
+ * {@code registerResolver("ip", ...)} if needed.
+ *
+ * <pre>{@code
+ * LimiterConfig conf = new LimiterConfig()
+ *     .registerResolver("auth_user", req -> {
+ *         // custom logic — e.g. extract sub from ClaimsHolder
+ *         return ClaimsHolder.exists() ? ClaimsHolder.user().sub() : "anonymous";
+ *     });
+ *
+ * app.install(new LimiterExtension(conf));
+ * }</pre>
+ */
+public final class LimiterConfig {
+
+    private final Map<String, KeyResolver> resolvers = new LinkedHashMap<>();
+
+    public LimiterConfig() {
+        // Built-in mandatory "ip" resolver.
+        // Resolution order (standard reverse-proxy chain):
+        //   1. X-Forwarded-For — first address (client behind one or more proxies)
+        //   2. X-Real-IP       — single forwarded IP (nginx proxy_set_header X-Real-IP)
+        //   3. Socket address  — direct connection, no proxy headers (zero alloc: the
+        //                        InetSocketAddress already exists from accept(); only
+        //                        getHostAddress() allocates a String, and only when reached)
+        resolvers.put("ip", req -> {
+            String xff = req.header("X-Forwarded-For");
+            if (xff != null) {
+                int comma = xff.indexOf(',');
+                return comma > 0 ? xff.substring(0, comma).strip() : xff.strip();
+            }
+            String xri = req.header("X-Real-IP");
+            if (xri != null) return xri.strip();
+            InetSocketAddress addr = req.remoteAddress();
+            return addr != null ? addr.getAddress().getHostAddress() : "unknown";
+        });
+    }
+
+    /**
+     * Registers (or replaces) a named key resolver. Returns {@code this} for fluent chaining.
+     *
+     * @param name     identifier referenced by {@link Limit#key()} and {@link Guard#limit}
+     * @param resolver lambda that extracts the partition key from a request
+     */
+    public LimiterConfig registerResolver(String name, KeyResolver resolver) {
+        if (name == null || name.isBlank()) throw new IllegalArgumentException("Resolver name must not be blank");
+        if (resolver == null)               throw new IllegalArgumentException("Resolver must not be null");
+        resolvers.put(name, resolver);
+        return this;
+    }
+
+    /**
+     * Returns the resolver for {@code name}.
+     *
+     * @throws InitializationException if no resolver with that name has been registered —
+     *         checked at boot time so misconfigurations surface immediately.
+     */
+    KeyResolver requireResolver(String name) {
+        KeyResolver r = resolvers.get(name);
+        if (r == null) throw new InitializationException(
+                "Rate-limit resolver \"" + name + "\" is not registered. " +
+                "Call LimiterConfig.registerResolver(\"" + name + "\", req -> ...) before install.");
+        return r;
+    }
+}
@@ -0,0 +1,130 @@
+package dev.relism.ext.limiter;
+
+import dev.relism.extension.FlashContext;
+import dev.relism.extension.FlashExtension;
+import dev.relism.extension.FlashRegistrar;
+import dev.relism.http.HttpStatus;
+import dev.relism.routing.Middleware;
+
+import java.util.List;
+
+/**
+ * Rate-limiting extension for Flash.
+ *
+ * <p>On {@link #install}:
+ * <ol>
+ *   <li>Creates a single {@link BucketStore} shared by all rules in this extension instance.</li>
+ *   <li>Provides a {@link Guard} in the {@link FlashContext} for manual use on lambda routes.</li>
+ *   <li>Registers an {@link dev.relism.extension.AnnotationProcessor} for {@link Limit}:
+ *       reads the annotation once per handler class at boot, resolves the key lambda
+ *       from the registry <em>fail-fast</em>, then returns a pre-compiled middleware
+ *       that captures the lambda and config directly — zero map lookups at request time.</li>
+ * </ol>
+ *
+ * <h3>Annotation-based (class handlers)</h3>
+ * <pre>{@code
+ * @Limit(requests = 100, window = 1)                          // 100 req/s per IP
+ * public class SearchHandler extends RequestHandler { ... }
+ *
+ * @Limit(key = "auth_user", requests = 20, window = 1,
+ *        windowUnit = TimeUnit.MINUTES,
+ *        strategy   = LimitStrategy.TOKEN_BUCKET)
+ * public class ReportHandler extends RequestHandler { ... }
+ * }</pre>
+ *
+ * <h3>Lambda routes (via Guard)</h3>
+ * <pre>{@code
+ * LimiterConfig conf = new LimiterConfig()
+ *     .registerResolver("auth_user", req -> ClaimsHolder.user().sub());
+ *
+ * app.install(new LimiterExtension(conf));
+ *
+ * Guard guard = app.ctx().require(Guard.class);
+ * app.get("/api/search", handler).with(guard.limit("ip", 50, 1, TimeUnit.SECONDS));
+ * }</pre>
+ *
+ * <h3>Installation order matters</h3>
+ * Install {@code LimiterExtension} <em>before</em> authentication extensions so that
+ * rate-limit checks short-circuit before expensive token validation on over-limit requests.
+ */
+public final class LimiterExtension implements FlashExtension {
+
+    private final LimiterConfig config;
+
+    /** Installs with default config (only the built-in {@code "ip"} resolver). */
+    public LimiterExtension() {
+        this(new LimiterConfig());
+    }
+
+    /** Installs with a custom {@link LimiterConfig} (custom resolvers, etc.). */
+    public LimiterExtension(LimiterConfig config) {
+        this.config = config;
+    }
+
+    @Override
+    public void install(FlashRegistrar app, FlashContext ctx) {
+        BucketStore store = new BucketStore();
+        Guard       guard = new Guard(config, store);
+
+        ctx.provide(Guard.class,        guard);
+        ctx.provide(LimiterConfig.class, config);
+
+        // Annotation processor: runs once per class-based handler at boot.
+        ctx.addAnnotationProcessor(handlerClass -> {
+            Limit ann = handlerClass.getAnnotation(Limit.class);
+            if (ann == null) return List.of();
+
+            // Fail-fast: if the key is unknown the server refuses to start.
+            KeyResolver resolver = config.requireResolver(ann.key());
+            LimitConfig cfg      = new LimitConfig(
+                    ann.requests(),
+                    ann.windowUnit().toMillis(ann.window()),
+                    ann.strategy().create()
+            );
+
+            return List.of(buildMiddleware(resolver, cfg, store));
+        });
+    }
+
+    // ── Package-private helper — shared with Guard ────────────────────────────
+
+    /**
+     * Builds the rate-limit {@link Middleware} from an already-resolved resolver lambda.
+     *
+     * <p>Hot-path design:
+     * <ul>
+     *   <li>{@code resolver} is captured directly in the closure — no registry lookup per request.</li>
+     *   <li>{@code resultBuf} is a per-{@link Middleware}-instance ThreadLocal {@code long[2]}.
+     *       Allocated once per thread, reused forever — zero per-request allocation.</li>
+     *   <li>Header values ({@code String.valueOf(...)}) are the only unavoidable allocations;
+     *       they are tiny and bounded.</li>
+     * </ul>
+     */
+    static Middleware buildMiddleware(KeyResolver resolver, LimitConfig cfg, BucketStore store) {
+        // One result buffer per thread, per middleware instance.
+        // ThreadLocal is captured in the closure at boot time — not re-created per request.
+        ThreadLocal<long[]> resultBuf = ThreadLocal.withInitial(() -> new long[2]);
+
+        return next -> (req, res) -> {
+            String key    = resolver.resolve(req);
+            Bucket bucket = store.get(key);
+            long[] out    = resultBuf.get();
+
+            boolean allowed = cfg.strategy().check(bucket, cfg, out);
+
+            // Always inject rate-limit headers — useful even on allowed requests.
+            res.header("X-RateLimit-Limit",     String.valueOf(cfg.limit()));
+            res.header("X-RateLimit-Remaining", String.valueOf(out[0]));
+            res.header("X-RateLimit-Reset",     String.valueOf(out[1]));
+
+            if (!allowed) {
+                long retryAfter = Math.max(1L, out[1] - System.currentTimeMillis() / 1000L);
+                res.status(HttpStatus.TOO_MANY_REQUESTS)
+                   .header("Retry-After", String.valueOf(retryAfter));
+                return "Too Many Requests";
+            }
+
+            return next.handle(req, res);
+        };
+    }
+}
@@ -0,0 +1,34 @@
+package dev.relism.ext.limiter;
+
+/**
+ * Contract for a rate-limit algorithm. Implementations must be:
+ * <ul>
+ *   <li><b>Lock-free</b> — rely only on {@link java.util.concurrent.atomic.AtomicLong} CAS operations.</li>
+ *   <li><b>Stateless</b> — all mutable state lives in the {@link Bucket}; the strategy itself
+ *       holds no instance fields so the same object can be shared across threads and rules.</li>
+ * </ul>
+ *
+ * <p>Called on every request — must not allocate on the hot path.
+ *
+ * @see dev.relism.ext.limiter.strategy.FixedWindowStrategy
+ * @see dev.relism.ext.limiter.strategy.TokenBucketStrategy
+ */
+public interface RateLimitStrategy {
+
+    /**
+     * Checks whether this request is within the limit and updates the bucket atomically.
+     *
+     * <p>On return, {@code out} contains:
+     * <ul>
+     *   <li>{@code out[0]} — remaining allowed requests in the current window (≥ 0).</li>
+     *   <li>{@code out[1]} — Unix epoch seconds at which the quota resets (for {@code X-RateLimit-Reset}
+     *       and {@code Retry-After} headers).</li>
+     * </ul>
+     *
+     * @param bucket  per-key state carrier (pre-allocated, never null)
+     * @param cfg     immutable rule configuration
+     * @param out     caller-supplied two-element array; values are overwritten on every call
+     * @return {@code true} if the request is within the limit and should proceed
+     */
+    boolean check(Bucket bucket, LimitConfig cfg, long[] out);
+}
@@ -0,0 +1,54 @@
+package dev.relism.ext.limiter.strategy;
+
+import dev.relism.ext.limiter.Bucket;
+import dev.relism.ext.limiter.LimitConfig;
+import dev.relism.ext.limiter.RateLimitStrategy;
+
+/**
+ * Fixed-window rate limit: allows up to {@link LimitConfig#limit()} requests per window of
+ * {@link LimitConfig#windowMs()} milliseconds. The window is aligned to clock time
+ * (e.g. 10:00:00 – 10:00:59 for a 60-second window), not sliding.
+ *
+ * <h3>Implementation</h3>
+ * The entire state fits in a single {@link java.util.concurrent.atomic.AtomicLong}
+ * ({@link Bucket#slot0}), packed as:
+ * <pre>
+ *   high 32 bits = reduced epoch  (currentTimeMs / windowMs) & 0xFFFFFFFFL
+ *   low  32 bits = request count in the current window
+ * </pre>
+ * Each request performs a single CAS loop — no locks, no allocations.
+ * At a window boundary the CAS atomically resets the counter to 1.
+ *
+ * <p>The reduced epoch wraps every {@code 2^32 × windowMs} milliseconds
+ * (~13,000 years for a 100 ms window) — collision-free in practice.
+ */
+public final class FixedWindowStrategy implements RateLimitStrategy {
+
+    @Override
+    public boolean check(Bucket bucket, LimitConfig cfg, long[] out) {
+        long now       = System.currentTimeMillis();
+        long absEpoch  = now / cfg.windowMs();
+        int  epoch     = (int)(absEpoch & 0xFFFFFFFFL);  // reduced epoch, collision-safe
+
+        while (true) {
+            long packed      = bucket.slot0.get();
+            int  storedEpoch = (int)(packed >>> 32);
+            int  count       = (int)(packed & 0xFFFFFFFFL);
+
+            // Same window: increment; new window: reset to 1.
+            // Cap at limit+1 to guard against int overflow on extreme traffic.
+            int newCount = (storedEpoch == epoch)
+                    ? Math.min(count + 1, cfg.limit() + 1)
+                    : 1;
+
+            long newPacked = ((long) epoch << 32) | (newCount & 0xFFFFFFFFL);
+
+            if (bucket.slot0.compareAndSet(packed, newPacked)) {
+                out[0] = Math.max(0L, cfg.limit() - newCount);
+                out[1] = (absEpoch + 1) * cfg.windowMs() / 1000L;
+                return newCount <= cfg.limit();
+            }
+            // CAS lost — contention; re-read and retry.
+        }
+    }
+}
@@ -0,0 +1,69 @@
+package dev.relism.ext.limiter.strategy;
+
+import dev.relism.ext.limiter.Bucket;
+import dev.relism.ext.limiter.LimitConfig;
+import dev.relism.ext.limiter.RateLimitStrategy;
+
+/**
+ * Token-bucket rate limit: tokens refill continuously at a rate of
+ * {@code limit / windowMs} tokens per millisecond, up to a maximum of {@code limit} tokens.
+ * Each request consumes one token. Burst traffic is absorbed until the bucket empties.
+ *
+ * <h3>Implementation</h3>
+ * <ul>
+ *   <li>{@link Bucket#slot0} — current token count scaled by {@value #SCALE}
+ *       (allows sub-token precision without floating-point). Starts at 0; treated as
+ *       {@code maxScaled} when {@link Bucket#slot1} is 0 (first call → bucket starts full).</li>
+ *   <li>{@link Bucket#slot1} — last-refill timestamp in ms. 0 = not yet initialised.</li>
+ * </ul>
+ *
+ * <p>Each request CAS-loops on {@code slot0}; {@code slot1} is updated best-effort after a
+ * successful CAS. The resulting inaccuracy is bounded by the nanoseconds between the CAS
+ * and the {@code set} — negligible and self-correcting for rate limiting purposes.
+ */
+public final class TokenBucketStrategy implements RateLimitStrategy {
+
+    /** Fixed-point scale factor. Stored tokens = actual tokens × SCALE. */
+    static final long SCALE = 1_000L;
+
+    @Override
+    public boolean check(Bucket bucket, LimitConfig cfg, long[] out) {
+        long now       = System.currentTimeMillis();
+        long maxScaled = (long) cfg.limit() * SCALE;
+        // Refill rate: limit tokens per windowMs → (limit * SCALE) / windowMs scaled-tokens per ms.
+        // Minimum 1 to ensure progress even for very large windows.
+        long rfPerMs   = Math.max(1L, maxScaled / cfg.windowMs());
+
+        while (true) {
+            long lastMs    = bucket.slot1.get();
+            long rawTokens = bucket.slot0.get();
+
+            // When slot1 == 0 the bucket has never been used: treat as one full window elapsed
+            // so the bucket starts completely full.
+            long elapsed       = (lastMs == 0L) ? cfg.windowMs() : Math.max(0L, now - lastMs);
+            long currentTokens = Math.min(maxScaled, rawTokens + elapsed * rfPerMs);
+
+            if (currentTokens < SCALE) {
+                // Not enough for one token — compute when the next token arrives.
+                long needed   = SCALE - currentTokens;
+                long msToNext = (needed + rfPerMs - 1) / rfPerMs; // ceiling division
+                out[0] = 0L;
+                out[1] = (now + msToNext) / 1000L;
+                // Best-effort: advance the refill baseline so the next call gets a fresh elapsed.
+                bucket.slot0.compareAndSet(rawTokens, currentTokens);
+                bucket.slot1.compareAndSet(lastMs, now);
+                return false;
+            }
+
+            long newTokens = currentTokens - SCALE;
+            if (bucket.slot0.compareAndSet(rawTokens, newTokens)) {
+                // Consumed successfully. Update refill baseline best-effort.
+                bucket.slot1.set(now);
+                out[0] = newTokens / SCALE;
+                out[1] = now / 1000L;
+                return true;
+            }
+            // CAS lost — another thread consumed a token concurrently; re-read and retry.
+        }
+    }
+}