Cache e modo offline¶
Os quatro degraus¶
Uma chamada a get_param percorre, nesta ordem, até algum degrau responder:
- Cache do parâmetro — chaveado por
app:param. O mais barato. - Cache global do app — o mapa inteiro, preenchido por
get_all_params. Um acerto aqui promove o valor ao cache do parâmetro. - Circuit breaker — se há erro recente registrado para essa aplicação, a rede é pulada e a resposta vem do TinyDB.
- A rede —
GETna API. Sucesso grava cache e TinyDB; falha arma o breaker e cai no local.
get_all_params percorre a mesma cadeia sem o degrau 2, que é ele próprio.
Validade do cache¶
Governada por cache_duration, em segundos. O default depende de como a
instância foi criada — 300 pelo construtor, 3600 por get_instance.
Não há invalidação remota. Um valor alterado no servidor chega quando o cache
expira, ou quando alguém chama clear_cache. Se você precisa de propagação
rápida, o que se ajusta é cache_duration — não existe push.
Um valor negativo em CACHE_DURATION vira 0, e não o fallback. Zero
significa cache sempre inválido: toda leitura vai à rede.
O circuit breaker¶
O que o arma¶
- Timeout
- Erro de conexão
404tratado como parâmetro inexistente- Qualquer erro inesperado, incluindo
5xx
O último item merece destaque: erro HTTP arma o cooldown junto com erro de rede.
Sem isso, a biblioteca martelaria um servidor que está devolvendo 500 a cada
leitura.
Quanto dura¶
api_error_cooldown, em segundos. Quando não configurado, cai para
cache_duration — que era o valor implícito antes de a variável existir.
Por que essa variável foi criada
Com get_instance, cache_duration é 3600. Antes de api_error_cooldown
existir, um único 500 transitório prendia o cliente em dado local por
uma hora. Se você usa get_instance e se importa com recuperação rápida,
configure API_ERROR_COOLDOWN para algo na casa de dezenas de segundos.
O que o desarma¶
- Uma requisição bem-sucedida.
clear_cachepara aquela aplicação — incondicionalmente.
As duas semânticas são deliberadamente diferentes: o desarme por sucesso é
guardado por compare-and-swap, o desarme por clear_cache não. Uniformizar as
duas reintroduz uma corrida de desarme precoce que já foi corrigida.
O arquivo local¶
Um TinyDB por instância. Escrito a cada leitura bem-sucedida da API; lido quando a rede falha ou o breaker está armado.
O arquivo local não é um cache pré-aquecido
Ele só contém o que já foi lido com sucesso alguma vez. Numa máquina
nova, com a API fora do ar desde o começo, ele está vazio e get_param
devolve None. O modo offline sobrevive a uma queda; não substitui a
primeira leitura.
Quando a leitura falha¶
Todos os caminhos de falha convergem para _handle_api_error, que tenta o
TinyDB e devolve o que houver — ou None.
| Situação | Resultado |
|---|---|
| Parâmetro nunca lido, API fora | None |
| Parâmetro já lido, API fora | O último valor conhecido |
| Parâmetro apagado no servidor | 404, breaker armado, valor local ainda devolvido |
| Chave de custódia errada | None, com erro no log |
A terceira linha tem uma consequência prática: apagar um parâmetro no servidor não o remove imediatamente dos clientes que já o tinham lido. Eles continuam devolvendo o valor local enquanto o breaker estiver armado.
Concorrência¶
A biblioteca é usada por várias threads e o estado é protegido por três locks distintos:
| Lock | Protege |
|---|---|
_lock_singleton |
O dicionário de instâncias do multiton |
_token_lock |
Renovação do token — separado para evitar reentrância |
_state_lock |
Caches e marcas de erro |
Leituras tiram um snapshot sob lock e processam fora dele, para não segurar o lock durante trabalho que não precisa dele.
Resíduo aceito de propósito¶
O compare-and-swap do cliente resolve empate de timestamp em favor de escrever. Não é descuido: a assimetria de custo entre escrever de novo e perder uma escrita favorece escrever. Está documentado no ponto do código e não deve ser "corrigido" à primeira vista.