Add comprehensive Javadoc documentation to server components, including annotations, request/response handling, routing, and WebSocket support.

src/main/java/dev/coph/nextusweb/server/ratelimit/RateLimiter.java

@@ -1,21 +1,61 @@
 package dev.coph.nextusweb.server.ratelimit;
 
+/**
+ * Strategy interface for rate limiting. An implementation decides, per logical key, whether a
+ * single request may proceed right now.
+ *
+ * <p>Concrete strategies in this package include {@link TokenBucketLimiter},
+ * {@link LeakyBucketLimiter}, {@link FixedWindowLimiter} and {@link SlidingWindowLimiter}.
+ * Implementations are expected to be thread-safe, since the same limiter is shared across all
+ * request-handling threads.</p>
+ */
 public interface RateLimiter {
 
+    /**
+     * Attempts to consume one unit of quota for the given key at the given timestamp.
+     *
+     * @param key      the logical bucket key (for example a client IP or user identifier)
+     * @param nowNanos the current time in nanoseconds, typically {@link System#nanoTime()}
+     * @return a {@link Result} describing whether the request was allowed and the remaining
+     *         quota
+     */
     Result tryAcquire(String key, long nowNanos);
 
+    /**
+     * Immutable outcome of a {@link #tryAcquire(String, long)} call.
+     *
+     * @param allowed          whether the request may proceed
+     * @param remaining        the remaining quota in the current window/bucket
+     * @param limit            the configured limit, surfaced as {@code X-RateLimit-Limit}
+     * @param retryAfterMillis when denied, how long the caller should wait before retrying, in
+     *                         milliseconds (0 when allowed)
+     */
     record Result(
             boolean allowed,
             long remaining,
             long limit,
             long retryAfterMillis
     ) {
+        /**
+         * Creates a result representing an allowed request.
+         *
+         * @param remaining the remaining quota after this request
+         * @param limit     the configured limit
+         * @return an "allowed" result with no retry delay
+         */
         public static Result allow(long remaining, long limit) {
             return new Result(true, remaining, limit, 0);
         }
 
+        /**
+         * Creates a result representing a denied (rate-limited) request.
+         *
+         * @param limit            the configured limit
+         * @param retryAfterMillis how long to wait before retrying, in milliseconds
+         * @return a "denied" result with zero remaining quota
+         */
         public static Result deny(long limit, long retryAfterMillis) {
             return new Result(false, 0, limit, retryAfterMillis);
         }
     }
-}
+}