cadmium-docs-legacy/protocol-spec/basic-request-ratelimit.md

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:

{
    "id": "abcd",
    "type": "profile:register",
    "to": "cadmium.org",
    "payload": {
        "username": "spam_spam_spam",
        "thirdPIDs": [],
        "password": "spam"
    }
}

• Server:

{
    "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
        }
    }
}

Errors

Global errors

• 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

interface RatelimitExceedErrorPayload {
    /**
     * How long after the client can retry the request (in seconds)
     */
    retryAfter: number
}