Leaky Bucket

Leak Bucket documemtation

Getting Started

This project provides a rate-limiting system based on the Leaky Bucket algorithm to control the frequency of requests, helping prevent API abuse. The following instructions will guide you on setting up the project locally for development and testing.

---

Prerequisites

Make sure the following tools are installed on your machine:

• Docker
• Docker Compose
• Node.js

---

Installation

Follow these steps to get your development environment up and running:

# Clone the repository
git clone https://github.com/yourusername/leaky-bucket.git

# Navigate into the project directory
cd leaky-bucket

# Start the application services using Docker Compose (includes database setup)
docker-compose up -d

# Run the development server
npm run start:dev

remember to fill in the .env file correctly, you can see an exemple in .env.exemple file

Once everything is set up, the application will be available at:

• Application Server: http://localhost:3000
• GraphQL Server: http://localhost:3000/graphql

---

Deployment

To deploy this project on a live system, follow these steps:

1. Ensure Docker and Docker Compose are installed on your server.
2. Pull the latest version of the project.
3. Run docker-compose up -d to start all services.
4. Configure any environment variables if needed.
5. The application will now be accessible via your domain.

---

Built With

This project utilizes the following technologies:

• Node.js
• Husky
• Docker
• Koa
• Zod
• GraphQL
• TypeScript

---

API Routes

Authentication

• POST /api/v1/authentication
  • Description: Authenticate a user and return a JWT token.
  • Request Example:

    {
      "email": "user@example.com",
      "password": "password123"
    }

  • Response:

    {
      "code": 200,
      "message": "Authentication successful",
      "data": {
        "token": "jwt_token"
     }
    }

---

Users

• POST /api/v1/users
  • Description: Create a new user.
  • Request Example:

    {
      "name": "Hebert Santos",
      "email": "hebertsantosdeveloper@gmail.com",
      "password": "20304050"
    }

  • Response:

    {
      "code": 201,
      "message": "User created successfully",
      "data": {
        "id": "user_id"
      }
    }

---

All routes from here need to pass the token in the header

Pix Key

• GET /api/v1/pix/query/{key}

  • Description: Retrieve a Pix key by its value.
  • Response:

    {
      "code": 200,
      "message": "Pix key retrieved successfully",
      "data": {
        "key": "hebertsantosdeveloper@gmail.com",
        "type": "EMAIL",
        "bank": "Inter"
      }
    }

• POST /api/v1/pix/query

  • Description: Create a new Pix key.
  • Request Example:

    {
      "key": "hebertsantosdeveloper@gmail.com",
      "type": "EMAIL",
      "bank": "Inter"
    }

  • Response:

    {
      "code": 201,
      "message": "Pix key created successfully",
      "data": {
        "type": "EMAIL",
        "key": "hebertsantosdeveloper@gmail.com"
      }
    }

  The userId and owner fields are automatically populated based on the authenticated user.

• GET /api/v1/pix/query/all

  • Description: Retrieve a list of Pix keys associated with the authenticated user.
  • Response:

    {
      "code": 200,
      "message": "Pix keys retrieved successfully",
      "data": [
        {
          "key": "hebertsantosdeveloper@gmail.com",
          "type": "EMAIL",
          "bank": "Inter"
        }
      ]
    }

• DELETE /api/v1/pix/query/{key}

  • Description: Delete a Pix key by its value.
  • Response:

    {
      "code": 200,
      "message": "Pix key deleted successfully"
    }

---

Leaky Bucket Rate Limiting

The Leaky Bucket algorithm is used to manage request frequency. It allows requests at a constant rate, while excess requests overflow. The algorithm operates as follows:

1. If the request is successful, it does not consume any tokens.
2. If the request fails, it consumes 1 token from the bucket.
3. Tokens are replenished gradually (1 token per hour).

Behavior

• Success Requests: No tokens consumed.
• Failure Requests: 1 token is consumed for each failed request.

NOTE : If you want to consume the user's tokens you can make a series of invalid requests

EXEMPLE : on the route /api/v1/pix/query enter invalid data or without any parameter, After consuming all your tokens you will be blocked, after an hour you will have a new token and so on until you reach the token limit.

Real exemple

I made a series of invalid requests, and after that:

My token will be zero:

Leaky Bucket Flow (Diagram)

graph TD
    A[HTTP Request] --> B{User authenticated?}
    B -->|No| C[401 Unauthorized]
    B -->|Yes| D[Execute endpoint]
    D --> E{Status < 400?}
    E -->|Success| F[Update bucket without deducting token]
    E -->|Failure| G[Consumes 1 token]
    G --> H{Tokens > 0?}
    H -->|Yes| I[200 OK]
    H -->|No| J[429 Too Many Requests]

Loading

---

Authors

• Hebert Santos – Initial work – @hebertzin

---

License

This project is licensed under the MIT License. See the LICENSE.md file for more details.