Describe basic request ratelimit system

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
+}
+```