From 78250add03e2de06014a62d9954e7eb4db632382 Mon Sep 17 00:00:00 2001
From: ChronosX88 <chronosx88@gmail.com>
Date: Thu, 26 Dec 2019 17:41:38 +0400
Subject: [PATCH] Describe basic request ratelimit system

---
 protocol-spec/basic-request-ratelimit.md | 68 ++++++++++++++++++++++++
 1 file changed, 68 insertions(+)
 create mode 100644 protocol-spec/basic-request-ratelimit.md

diff --git a/protocol-spec/basic-request-ratelimit.md b/protocol-spec/basic-request-ratelimit.md
new file mode 100644
index 0000000..360e171
--- /dev/null
+++ b/protocol-spec/basic-request-ratelimit.md
@@ -0,0 +1,68 @@
+# Basic request ratelimit system
+
+## Introduction
+
+This extension is intended to limit the number of requests from clients per unit of time. It is based on Protocol Errors extension.
+
+## Message type identifiers
+
+None.
+
+## Use cases
+
+- Client:
+
+```json
+{
+    "id": "abcd",
+    "type": "profile:register",
+    "to": "cadmium.org",
+    "payload": {
+        "username": "spam_spam_spam",
+        "thirdPIDs": [],
+        "password": "spam"
+    }
+}
+```
+
+- Server:
+
+```json
+{
+    "id": "abcd",
+    "type": "profile:register",
+    "from": "cadmium.org",
+    "ok": false,
+    "payload": {
+        "errCode": "ratelimit_exceed",
+        "errText": "Request ratelimit exceed! Please, try again later!",
+        "errPayload": {
+            "retryAfter": 2
+        }
+    }
+}
+```
+
+## Error Identifiers
+
+### Global error identifiers
+
+- `ratelimit_exceed`
+
+## Business Rules
+
+- Server MUST count number of requests per unit of time and drop new requests after specified number of made requests with Protocol Error message.
+- Number of requests and used unit of time SHOULD be configurable on server
+
+## JSON Schema
+
+### Error payload
+
+```typescript
+interface RatelimitExceedErrorPayload {
+    /**
+     * How long after the client can retry the request (in seconds)
+     */
+    retryAfter: number
+}
+```