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