better rate limited responses

allows clients to use `ratelimit.key` and `ratelimit.seconds` to better
handle limited responses

```json
{
    "error": "You played 100 games against other bots today, please wait before challenging another bot.",
    "ratelimit": {
        "key": "bot.vsBot.day",
        "seconds": 86398
    }
}
```

Author: ornicar

modules/memo/src/main/RateLimit.scala

@@ -53,6 +53,17 @@ final class RateLimit[K](
   def zero[A](k: K, cost: Cost = 1, msg: => String = "")(op: => A)(using default: Zero[A]): A =
     apply[A](k, default.zero, cost, msg)(op)
 
+  def isLimited(k: K): Option[Instant] =
+    enforce.yes
+      .so(storage.getIfPresent(k))
+      .flatMap:
+        case (a, _) if a < credits => none
+        case (_, clearAt) if nowMillis > clearAt => none
+        case (_, clearAt) =>
+          if log then logger.info(s"$credits/$duration $k")
+          monitor.increment()
+          millisToInstant(clearAt).some
+
 object RateLimit:
 
   type ChargeWith = Cost => Unit
@@ -62,6 +73,8 @@ object RateLimit:
   enum Result:
     case Through, Limited
 
+  case class Limited(key: String, msg: String, until: Instant)
+
   trait RateLimiter[K]:
     def apply[A](k: K, default: => A, cost: Cost = 1, msg: => String = "")(op: => A): A
     def chargeable[A](k: K, default: => A, cost: Cost = 1, msg: => String = "")(op: ChargeWith => A): A

modules/web/src/main/CtrlErrors.scala

@@ -8,6 +8,15 @@ import lila.core.i18n.{ I18nKey, Translate }
 
 trait CtrlErrors extends ControllerHelpers:
 
+  given Writes[lila.memo.RateLimit.Limited] = Writes: l =>
+    Json.obj(
+      "error" -> l.msg,
+      "ratelimit" -> Json.obj(
+        "key" -> l.key,
+        "seconds" -> (l.until.toSeconds - nowSeconds).toInt.atLeast(0)
+      )
+    )
+
   def jsonError[A: Writes](err: A): JsObject = Json.obj("error" -> err)
 
   def notFoundJson(msg: String = "Not found"): Result = NotFound(jsonError(msg)).as(JSON)

modules/web/src/main/ResponseBuilder.scala

@@ -5,6 +5,8 @@ import play.api.http.*
 import play.api.libs.json.*
 import play.api.mvc.*
 
+import lila.memo.RateLimit.Limited
+
 trait ResponseBuilder(using Executor)
     extends ControllerHelpers
     with ResponseWriter
@@ -30,6 +32,7 @@ trait ResponseBuilder(using Executor)
   def JsonStrOk(str: JsonStr): Result = Ok(str).as(JSON)
   def JsonBadRequest(body: JsValue): Result = BadRequest(body).as(JSON)
   def JsonBadRequest(msg: String): Result = JsonBadRequest(jsonError(msg))
+  def JsonLimited(limited: Limited): Result = TooManyRequests(Json.toJson(limited)).as(JSON)
 
   def strToNdJson(source: Source[String, ?]): Result =
     Ok.chunked(source).as(ndJson.contentType).noProxyBuffer