# Como funciona

A unicep tem duas peças:

- **Provider**: o adaptador de um serviço de CEP. Faz a chamada HTTP e converte a resposta para o
  objeto `Address`.
- **`Unicep`**: recebe uma lista de providers, coloca um circuit breaker em cada um e tenta um
  por um até alguém responder.

![Seu app chama o Unicep, que tenta o Provider 1, depois o Provider 2 e assim por diante, cada um com o seu circuit breaker, e devolve sempre o mesmo objeto Address.](/diagrams/flow-pt.svg)

## O caminho de uma consulta

1. O CEP é validado (`01310100` ou `01310-100`). Se for inválido, lança `InvalidCepError` sem
   fazer nenhuma requisição.
2. Se o [cache](/docs/core#cache) estiver ligado e o CEP já estiver nele, o endereço volta na
   hora.
3. Os providers são tentados na ordem em que você os passou. Quem estiver com o circuito aberto
   é pulado.
4. Cada tentativa tem um timeout. Com [retry](/docs/core#retry) ligado, o mesmo provider é
   repetido antes de passar para o próximo.
5. O primeiro que responder vence, e o resultado traz o nome dele em `provider`.

## Circuit breaker

Cada provider tem o seu circuit breaker, que conta as falhas **seguidas**:

| Estado | O que significa |
| --- | --- |
| `closed` | Normal. As requisições passam. |
| `open` | Depois de `failureThreshold` falhas seguidas (3 por padrão), o provider é pulado sem fazer requisição. |
| `half-open` | Passado `resetTimeoutMs` (30 segundos por padrão), uma requisição de teste decide se o circuito fecha ou abre de novo. |

Assim, um serviço fora do ar não atrasa as consultas: a unicep vai direto para o próximo.

## O que conta como falha

| O que aconteceu | Conta no circuit breaker? | O que a unicep faz |
| --- | --- | --- |
| Erro de rede, timeout, HTTP 5xx ou 429, resposta inválida | Sim | Tenta o próximo provider |
| "CEP não encontrado" | Não | Tenta o próximo provider, porque a cobertura muda entre serviços |
| Cancelamento por `AbortSignal` | Não | Para e rejeita com o motivo do cancelamento |

Se todos os que responderam disseram "não encontrado", o erro é `CepNotFoundError`. Se nenhum
conseguiu responder, é `AllProvidersFailedError`, com um erro por provider. Veja
[Erros](/docs/errors).

## Estado dos circuitos

```ts
unicep.status();
// [
//   { name: 'viacep', circuit: 'closed' },
//   { name: 'brasilapi', circuit: 'open' },
//   ...
// ]
```

É o que a [página de status](/status) usa para mostrar cada provider em tempo real.