# Use a integração Upstash Rate Limiting

**Upstash Rate Limiting** permite que você controle o tráfego de entrada diretamente no edge da rede, evitando gargalos, gerenciando picos de tráfego e protegendo suas aplicações contra possíveis ameaças, como DDoS, fuzzing ou ataques de força bruta.

Com essa integração, baseada em uma function, você pode definir:

- **Limiting requests** e **window limit**, incluindo janelas de limites específicas para diferentes períodos do dia.
- Uma configuração de **penalty** que analisa a validade de cada requisição.
   - Se a requisição não for válida, ela é bloqueada e é retornado um código de status `403 Forbidden` ao usuário.
   - Se a requisição for válida, ela é somada e, caso atinja o limite de taxa definido, é interrompida e é retornado um código de status `429 Too Many Requests` ao usuário.

A Upstash Rate Limiting é integrada à biblioteca `upstash/ratelimit` e fornece uma contabilidade global do limite de taxa, somando todas as requisições recebidas em toda a rede, em vez de contar separadamente para cada edge location.

---

## Pré-requisitos

Para começar a usar esta integração, você precisa:

- Criar uma [conta no Upstash](https://console.upstash.com/).
- Criar um banco de dados global para obter a melhor latência de edge disponível no [console do Upstash](https://console.upstash.com/).

---

## Obtenha a integração

Para instalar a integração:

1. Acesse o [Azion Console](/pt-br/documentacao/produtos/guias/como-acessar-o-azion-console/) > **Marketplace**.
2. Na página inicial do Marketplace, selecione o card da integração.
3. Na página da integração, clique no botão **Install**, localizado no canto inferior da direita.

Você receberá uma mensagem indicando que sua integração foi instalada com sucesso.

Em seguida, você precisará concluir as etapas explicadas abaixo para instanciar a função e configurar um firewall.

---

## Configure a integração

### Configure uma regra no Firewall

Para instanciar a integração **Upstash Rate Limiting**, siga os passos:

1. No **Products menu**, selecione **Firewall** na seção **Secure**.
2. Clique no botão **+ Firewall**.
3. Dê um nome fácil de lembrar ao seu firewall.
4. Ative a opção **Functions** na seção **Modules**.
5. Clique no botão **Save**.

Pronto. Você instanciou um firewall para sua função.

### Configure uma função no Firewall

Ainda na página do **Firewall**:

1. Selecione a aba **Functions Instances** e siga estas etapas:
2. Clique no botão **+ Function Instance**.
3. Dê um nome fácil de lembrar à sua instância.
4. No menu suspenso, selecione a função **Upstash Rate Limiting**.
	- Esta ação irá carregar a aba **Arguments**.
5. Na guia **Arguments**, você passará suas credenciais do Upstash e suas variáveis:

```bash
{
  "upstash_redis_rest_url": "https://your-database.upstash.io",
  "upstash_redis_rest_token": "Your upstash token",
 "rate_limit_prefix": "my_rate_limit",
  "rate_limit_key_metadata": [
	"remote_addr"
  ],
  "rate_limit_key_header": [
	"x-a-custom-header"
  ],
  "rate_limit_key_hostname": true,
  "rate_limit_repenalize": true,
  "rate_limits": [	
	{
  	      "algorithm": "sliding_window",
  	      "requests": 2,
  	      "interval": "20 s",
  	      "start": "00:00",
  	      "end": "12:00",
  	      "penalty_in_seconds": 45
	},
	{
  	      "algorithm": "fixed_window",
  	      "requests": 3,
  	      "interval": "120 s",
  	      "start": "12:01",
  	      "end": "23:00",

	},
       {
  	    "algorithm": "token_bucket",
  	    "refil_rate": 5,
  	    "max_tokens": 5,
  	    "interval": "10 s",
           "start": "23:01",
            "penalty_in_seconds": 55
	}
  ]
}
```

Onde:

| Variável | Descrição |
| ---- | ---- |
| `upstash_redis_rest_url` | A URL do seu banco de dados no Upstash que armazenará os dados |
| `upstash_redis_rest_token` | Seu token de acesso à API do Upstash |
| `rate_limit_prefix` | Define um prefixo a ser usado em todas as chaves de rate limit. Essa variável é crucial para evitar sobreposições entre diferentes instâncias da função |
| `rate_limit_key_metadata` | Define quais variáveis de metadados serão usadas para gerar a chave de rate limit na plataforma da Azion |
| `rate_limit_key_header` | Define quais variáveis de metadados serão usadas para gerar a chave de rate limit na plataforma da Azion |
| `rate_limit_key_hostname` | Se `true`, a URL será usada para gerar a chave de rate limit |
| `rate_limit_repenalize` | Se `true`, o tempo de penalidade é recalculado toda vez que um usuário penalizado faz uma requisição |
| `rate_limits` | Define as janelas de limites como um objeto. Você deve adicionar **pelo menos um objeto** |
| `algorithm` | Define o algoritmo de rate limit a ser aplicado. Valores possíveis: `fixed_window`, `sliding_window`, `token_bucket`. [Leia mais](#importante) |
| `requests` | Número máximo de requisições até atingir o rate limit |
| `interval` | Intervalo de tempo da janela de limite. Esta variável segue o padrão Upstash: `XXXX y`, onde `X` é o numeral e `y` é a unidade, que pode ser `s` para segundos ou `m` para minutos. Exemplo: `120 s` |
| `start` e `end` | Essas variáveis definem a janela de tempo. Usam o formato de 24 horas e o fuso horário UTC. [Leia mais](#importante)  |
| `penalty_in_seconds` | Tempo de penalidade (bloqueio que retorna o código de status `403`) a que os usuários estarão sujeitos após violarem o limite de taxa. [Leia mais](#importante) |

:::note
A chave para rate limiting é composta pela combinação de todas essas variáveis. Neste exemplo de código, a chave final seria:
`my_rate_limit + IP do usuário + Valor do X-a-custom-header + Hostname usado na requisição`.

Exemplo:
`my_rate_limit_127.0.0.1_Valor_azion.com`
:::

6. Clique no botão **Save**.

#### Importante

- Esta integração permite definir diferentes janelas de limites para diferentes períodos do dia. Exemplo: você pode definir um limite de `10 requisições/minuto` de `00:00` a `12:00` e outro de `15 requisições/minuto` de `12:01` a `23:59`.

- Esta integração suporta três valores possíveis para `algorithm`:

   - `fixed_window` divide o tempo em durações/janelas fixas.
   - `sliding_window` é construído em cima da janela fixa, mas usa uma janela variável. Exemplo: você deseja definir um limite de taxa de `10 requisições` por `1 minuto` e, em seguida, divide o tempo em fatias de `1 minuto`, como no algoritmo de `fixed_window`.
   - `token_bucket` define o número máximo de tokens para preencher um bucket e o intervalo em que o bucket será limpo. Cada requisição remove um token e, se não houver token para receber, a requisição será rejeitada.

- O `token_bucket` inclui valores diferentes, onde:
   - `max_tokens` define o número de tokens (ou chaves) que esse limite de taxa permitirá.
   - `refil_rate` define o número de buckets que serão "limpados" em cada intervalo de tempo.

```bash
"algorithm": "token_bucket",
  	    "refil_rate": 5,
  	    "max_tokens": 5,
  	    "interval": "10 s",
           "start": "23:01",
            "penalty_in_seconds": 55
```

Neste exemplo, a cada `10 segundos`, `5 buckets` são limpados, de um máximo de `5 buckets` "ocupados".

- Se o `start` não estiver definido, o valor padrão será `00:00`. Se o `end` não estiver definido, o valor padrão será `23:59`. Em caso de sobreposições entre os limites de taxa, o limite que estiver primeiro nos **Args** será considerado.

- Quando a variável `penalty_in_seconds` não é preenchida, o limite da tarifa não se aplica a uma penalidade, comportando-se como um limite de tarifa *simples*.

### Configure o Rules Engine

Para concluir, você deve configurar uma regra no **Rules Engine** para definir os critérios (**criteria**) e o comportamento (**behavior**) para executar a função.

Ainda na página do **Firewall**:

1. Selecione a aba **Rules Engine**.
2. Clique no botão **+ Rule Engine**.
3. Dê um nome fácil de lembrar à sua nova regra.
4. Selecione um *criteria* (critério) para executar a integração.
  - Exemplo: if `Host` *matches* `yourdomain.com`.
5. Abaixo, selecione um *behavior* (comportamento) para os *criteria* (critérios). Neste caso, será **Run Function**.
   - Selecione a função adequada de acordo com o nome que você deu na etapa de instanciação.
6. Clique no botão **Save**.

Agora, no Console, você deve configurar seu domínio para que ele seja protegido pelo seu firewall.

7. No **Products menu**, selecione **Workloads**.
8. Clique no domínio que você deseja proteger com sua função **Upstash Rate Limiting**.
9. Na seção **Settings**, clique no seletor de `Firewall` e escolha o firewall que você acabou de criar.
10. Clique no botão **Save**.

Pronto. Agora, **Upstash Rate Limiting** está em execução e protegendo seus domínios.

---