@seedgrid/ai-toolkit 0.0.0-stage → 0.3.0

package/seedgridKB/SeedGrid/Extensions/realtime/Visao-geral.md

@@ -0,0 +1,105 @@
+---
+tags: [seedgrid, extension, realtime]
+fonte: java/seedgrid-quarkus-ext-realtime
+branch: main
+commit: 8f13639b3c
+analisado-em: 2026-10-14
+---
+
+# Realtime (Quarkus) — visão geral
+
+Avisos em tempo real para o **usuário logado** através do **SeedGrid Pulse** (serviço externo de publish/subscribe). A extension entrega ao front um token curto de conexão ao Pulse e repassa ao Pulse todo `SgUserEvent` da plataforma, sem código de negócio no host.
+
+- Configuração: [[SeedGrid/Extensions/realtime/Configuracao|Configuração do realtime]]
+- Exemplos: [[SeedGrid/Extensions/realtime/Exemplos|Exemplos do realtime]]
+- Enums: a extension não define enums (nem Java nem de contrato com o Pulse).
+- Porte Rust (crate `seedgrid-rust-crate-realtime`): [[SeedGrid/Extensions/realtime/Rust|Porte Rust]]
+
+## Funcionalidades (Confirmado)
+
+| Funcionalidade | Onde |
+|---|---|
+| `POST /realtime/connect` (autenticado): emite o token de conexão do usuário **da sessão** (nunca do corpo do request) | `RealtimeController#connect()` |
+| Bean injetável `RealtimePublisher` (`publishToUser`, `issueConnectToken`, `isEnabled`) | `RealtimePublisher` |
+| Observer de `SgUserEvent` (`seedgrid-commons`) em `TransactionPhase.AFTER_SUCCESS` → publica para o usuário | `SgUserEventObserver#onUserEvent` |
+| Rate limit de emissão de token por usuário (janela fixa de 1 min, em memória, por instância) | `ConnectRateLimiter#tryAcquire` |
+| "Nunca derruba quem chama": desligado = no-op; Pulse fora do ar = log WARN e segue | `RealtimePublisher#publishToUser` |
+
+## Módulos Maven e coordenadas (Confirmado — `pom.xml`)
+
+| Módulo | groupId | artifactId | Versão |
+|---|---|---|---|
+| parent | `br.com.seedgrid` | `seedgrid-realtime-parent` | `2026.10.08` |
+| runtime | `br.com.seedgrid` | `seedgrid-realtime` | `2026.10.08` |
+| deployment | `br.com.seedgrid` | `seedgrid-realtime-deployment` | `2026.10.08` |
+
+Parent: `br.com.seedgrid:seedgrid-parent:2026.07.02`. `quarkus-extension.properties` exige Quarkus `[3.30,)`. Status no `quarkus-extension.yaml`: `preview`.
+
+## Dependências
+
+| Dependência | Versão | Observação |
+|---|---|---|
+| `br.com.seedgrid:seedgrid-commons` | `2026.10.08` | Só `SgUserEvent` e `CurrentUserProvider`; exclui `quarkus-hibernate-orm` e `quarkus-hibernate-orm-panache` (a extension não tem banco). |
+| `br.com.seedgrid:seedgrid-pulse-publisher` | `2026.10.0` | SDK do Pulse (`PulsePublisher`, `ConnectToken`, `IssueConnectTokenInput`, `PublishMessageInput`). |
+| `quarkus-arc`, `quarkus-rest-jackson`, `quarkus-security` | BOM | — |
+
+Requisito implícito (Inferência, pelo uso de `CurrentUserProvider` e `@Authenticated`): o host precisa de um mecanismo de autenticação e de um `CurrentUserProvider` que devolva o `publicId` do usuário (no ecossistema SeedGrid, o `JwtCurrentUserProvider` do `seedgrid-security`, segundo o javadoc de `TestCurrentUserProvider`).
+
+## Arquitetura e fluxo
+
+```mermaid
+flowchart LR
+    P[Processo do host / outra extension] -- "Event&lt;SgUserEvent&gt;.fire()" --> O[SgUserEventObserver<br/>AFTER_SUCCESS]
+    O --> RP[RealtimePublisher.publishToUser]
+    RP -- "publishAsync (x-api-key = project key)" --> PULSE[(SeedGrid Pulse)]
+    F[Front logado] -- "POST /realtime/connect" --> C[RealtimeController]
+    C --> RL[ConnectRateLimiter]
+    C --> RP2[RealtimePublisher.issueConnectToken]
+    RP2 --> PULSE
+    C -- "token pct_..., expiresAt, connectUrl, channels" --> F
+    F -- "WebSocket com o token" --> PULSE
+```
+
+- O `RealtimePublisher` monta o `PulsePublisher` uma vez, no construtor: só se `seedgrid.realtime.enabled=true` **e** houver `pulse.base-url` e `pulse.project-key` não vazios. Caso contrário fica desligado (com log ERROR se estava ligado mas incompleto). (Confirmado — `RealtimePublisher#connect`)
+- `SgUserEventObserver` só publica depois do commit; se a transação desfizer, não publica. (Confirmado)
+- O Pulse fingido nos testes expõe `POST /api/v1/connect-tokens` e `POST /api/v1/messages`, e o header usado é `x-api-key`. (Confirmado em `RealtimeEnabledTest`; são detalhes do SDK do Pulse, não desta extension.)
+
+## API pública e pontos de integração
+
+### Endpoint REST
+
+| Método | Path | Segurança | Respostas |
+|---|---|---|---|
+| `POST` | `/realtime/connect` (sob o root path REST do host, se houver) | `@Authenticated` | `200 {enabled:false}` (desligado); `200 {enabled:true, token, expiresAt, connectUrl, channels}`; `401` sem usuário (inclusive o UUID zerado `00000000-0000-0000-0000-000000000000` do provider padrão); `429` com `Retry-After` (segundos); `503` se o Pulse falhar |
+
+`RealtimeConnectResponse` usa `@JsonInclude(NON_NULL)`; `expiresAt` é epoch em **segundos**; `channels` ausente = todos os da conta. (Confirmado)
+
+### Beans / eventos
+
+| Símbolo | Tipo | Uso |
+|---|---|---|
+| `br.com.seedgrid.realtime.services.RealtimePublisher` | `@ApplicationScoped`, unremovable | `publishToUser(String channel, String event, String userPublicId, Map<String,Object> data)`; `issueConnectToken(String userPublicId)` (lança `IllegalStateException` se desligado); `isEnabled()` |
+| `br.com.seedgrid.commons.events.SgUserEvent` | evento CDI (do commons) | `new SgUserEvent(userPublicId, channel, event, data)` — observado pela extension |
+| `br.com.seedgrid.realtime.configs.RealtimeConfig` | `@ConfigMapping` | ver [[SeedGrid/Extensions/realtime/Configuracao|Configuração]] |
+
+O deployment (`SeedgridRealtimeProcessor`) registra a feature `seedgrid-realtime`, o `ConfigMappingBuildItem` e torna `RealtimePublisher`, `ConnectRateLimiter` e `SgUserEventObserver` unremovable.
+
+## Migrations
+
+Nenhuma (a extension não tem banco). (Confirmado)
+
+## Testes existentes (não executados)
+
+| Teste | O que cobre |
+|---|---|
+| `runtime/src/test/.../RealtimeEnabledTest` | 401 sem sessão; token do usuário da sessão com a project key; `subject` do request ignorado; 503 com Pulse fora; `SgUserEvent` vira publicação; erro do Pulse não chega a quem disparou |
+| `runtime/src/test/.../RealtimeDisabledTest` | desligado: `{enabled:false}` e nenhuma chamada ao Pulse |
+| `runtime/src/test/.../services/ConnectRateLimiterTest` | limite por usuário, reabertura da janela, `0` desliga |
+| `FakePulse` (WireMock) / `TestCurrentUserProvider` | infraestrutura de teste |
+
+## Limitações
+
+- O rate limit é **em memória e por instância**: com N réplicas o limite efetivo por usuário é até N × `connect-rate-per-minute` (Inferência a partir de `ConnectRateLimiter`, que usa `ConcurrentHashMap` local). As janelas antigas não são removidas do mapa (Inferência: não há limpeza no código).
+- A configuração é lida uma vez na construção do `RealtimePublisher` (bean `@ApplicationScoped`); mudar config exige reinício (Inferência).
+- `data` deve carregar apenas identificadores, nunca conteúdo (recomendação do README; não há validação no código).
+- O `NO_USER` (UUID zerado) é uma convenção do `DefaultCurrentUserProvider` do commons; outros providers que devolvam outro sentinela não são tratados (Inferência).

package/seedgridKB/SeedGrid/Extensions/resilience/Configuracao-Rust.md

@@ -0,0 +1,68 @@
+---
+tags: [seedgrid, extension, resilience, rust, configuracao]
+fonte: rust/seedgrid-rust-crate-resilience
+branch: main
+commit: be738a2d1e
+analisado-em: 2026-10-14
+---
+
+# resilience — Configuração Rust
+
+Visão do crate: [[SeedGrid/Extensions/resilience/Rust|Porte Rust do resilience]] · Java: [[SeedGrid/Extensions/resilience/Configuracao|Configuração do resilience (Java)]].
+
+## Cabeçalho
+| Item | Valor |
+|---|---|
+| Mecanismo | (1) structs-"anotação" `SeedGridCircuitBreaker` e `SeedGridRateLimit` com `Default` (= defaults das anotações Java); (2) overrides por nome lidos de uma `ConfigSource` injetada (`src/config.rs`) |
+| Variáveis de ambiente | **nenhuma** — `grep` por `env::var` em `src/` não encontra nada (**Confirmado**) |
+| `ConfigSource` disponíveis | `EmptyConfigSource` (nenhuma chave) e `MapConfigSource` (mapa tipado). **Não existe** implementação baseada em ambiente no workspace |
+| Uso real no workspace | security (`src/ratelimit.rs`) e `seedgrid-runtime` (exemplo/teste) usam `EmptyConfigSource` → os overrides abaixo **não têm efeito** a menos que o host implemente `ConfigSource` |
+| Leitura | a cada `try_acquire` / `resolve` (sem cache) |
+| Equivalente Java | `Config#getOptionalValue` em `RateLimitService.java` e `CircuitBreakerConfigResolver.java`; mesmas chaves |
+
+Os overrides só são consultados quando a "anotação" tem `config_key` (rate limit) ou `name` (circuit breaker) não vazio.
+
+## Overrides de rate limit — `seedgrid.ratelimit.{configKey}.*`
+| Propriedade | Tipo (`ConfigValue`) | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `seedgrid.ratelimit.{configKey}.enabled` | `Bool` | `true`/`false` | `true` | Não | `false` libera sem tocar o cache (kill switch) | `RateLimitService::try_acquire` | — | por chamada | `src/ratelimiter/service.rs` → `is_enabled` |
+| `seedgrid.ratelimit.{configKey}.permits` | `Long` | > 0 | `SeedGridRateLimit.permits` (5) | Não | permits por janela; ≤ 0 → panic | `resolve_permits` | `burst-capacity` | por chamada | idem |
+| `seedgrid.ratelimit.{configKey}.window` | `Duration` | > 0 | `window` × `window_unit` (30 s) | Não | tamanho da janela | `resolve_window_ms` | — | por chamada | idem |
+| `seedgrid.ratelimit.{configKey}.min-spacing` | `Duration` | ≥ 0 | `min_spacing` × `min_spacing_unit` (0) | Não | espaçamento mínimo entre chamadas | `resolve_min_spacing_ms` | — | por chamada | idem |
+| `seedgrid.ratelimit.{configKey}.burst-capacity` | `Long` | ≥ 0 (0 = usa `permits`) | `burst_capacity` (0) | Não | capacidade do token bucket | `resolve_burst_capacity` | `algorithm` | por chamada | idem |
+| `seedgrid.ratelimit.{configKey}.algorithm` | `Str` | `FIXED_WINDOW`, `SLIDING_WINDOW`, `TOKEN_BUCKET` (`trim`, maiúsculas, `-`→`_`); outro → **panic** | `algorithm` (`FIXED_WINDOW`) | Não | escolhe a estratégia | `resolve_algorithm` / `parse_algorithm` | — | por chamada | idem |
+
+`configKey`s usados no workspace (fixos em código): `export-create` (backup, 10/hora), `billing-checkout` (30/min), `billing-portal` (30/min), `billing-webhook` (300/min); a security define os seus em `rust/seedgrid-rust-crate-security/src/ratelimit.rs` (fora deste escopo).
+
+## Overrides de circuit breaker — `seedgrid.circuitbreaker.{name}.*`
+| Propriedade | Tipo | Valores aceitos | Padrão (`SeedGridCircuitBreaker::default`) | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `seedgrid.circuitbreaker.{name}.enabled` | `Bool` | bool | `true` | Não | `false` desliga o circuito | `CircuitBreakerConfigResolver::is_enabled` | — | por chamada | `src/circuitbreaker/config_resolver.rs` |
+| `.sliding-window-size` | `Int` | inteiro | `100` | Não | slots da janela (em `TIME_BASED`, segundos) | `resolve` | `window-type` | idem | idem |
+| `.window-type` | `Str` | `COUNT_BASED`, `TIME_BASED` (normalizado); outro → **panic** | `COUNT_BASED` | Não | tipo de janela | `resolve` / `parse_window_type` | — | idem | idem |
+| `.failure-rate-threshold` | `Double` | % | `50.0` | Não | abre ao atingir a taxa de falha | `resolve` | `minimum-number-of-calls` | idem | idem |
+| `.slow-call-duration` | `Duration` | duração (→ ms) | `0` (desligado) | Não | limiar de chamada lenta | `resolve` | `slow-call-rate-threshold` | idem | idem |
+| `.slow-call-rate-threshold` | `Double` | % | `100.0` | Não | abre pela taxa de lentidão | `resolve` | — | idem | idem |
+| `.minimum-number-of-calls` | `Int` | inteiro | `20` | Não | mínimo antes de avaliar | `resolve` | — | idem | idem |
+| `.open-state-duration` | `Duration` | duração (→ ms) | `30000` ms | Não | tempo em OPEN antes de HALF_OPEN | `resolve` | — | idem | idem |
+| `.permitted-calls-in-half-open` | `Int` | inteiro | `10` | Não | sondagens em HALF_OPEN | `resolve` | — | idem | idem |
+
+`record_exceptions` (padrão `["Exception"]`), `ignore_exceptions` e `fallback_method` existem só na struct (referências de código).
+
+## Defaults de `SeedGridRateLimit`
+`permits=5`, `window=30`, `window_unit=Seconds`, `algorithm=FixedWindow`, `burst_capacity=0`, `min_spacing=0`, `min_spacing_unit=Millis`, `identity=IpIdentityResolver`, `group=""`, `scope=Method`, `emit_headers=true`, `config_key=""` (`src/ratelimiter/config.rs`).
+
+## Features Cargo
+Nenhuma.
+
+## Configuração mínima (programática)
+```rust
+let source = MapConfigSource::new()
+    .with("seedgrid.ratelimit.billing-checkout.permits", ConfigValue::Long(60))
+    .with("seedgrid.ratelimit.billing-checkout.window", ConfigValue::Duration(Duration::from_secs(60)));
+let service = RateLimitService::new(cache, Arc::new(source));
+```
+
+## Receitas
+- **Desligar um rate limit em produção**: `seedgrid.ratelimit.<configKey>.enabled = Bool(false)` numa `ConfigSource` do host.
+- **Ler overrides do ambiente**: implementar `ConfigSource` no host (ex.: mapear `SEEDGRID_RATELIMIT_<KEY>_PERMITS`) — não fornecido pela crate.

package/seedgridKB/SeedGrid/Extensions/resilience/Configuracao.md

@@ -0,0 +1,186 @@
+---
+tags: [seedgrid, extension, resilience, configuracao]
+fonte: java/seedgrid-quarkus-ext-resilience
+branch: main
+commit: eff41304f8
+analisado-em: 2026-10-14
+---
+
+# Configuração — SeedGrid Resilience (Quarkus)
+
+Voltar: [[SeedGrid/Extensions/resilience/Visao-geral|Visão geral do resilience]] · [[SeedGrid/Extensions/resilience/Exemplos|Exemplos]] · [[SeedGrid/Extensions/resilience/Rust|Porte Rust]]
+
+## 1. Cabeçalho
+
+| Item | Valor |
+|---|---|
+| Prefixos | `seedgrid.ratelimit.{configKey}.*` e `seedgrid.circuitbreaker.{name}.*` (segmento dinâmico vindo da anotação) |
+| Classes que leem config | `runtime/.../ratelimiter/services/RateLimitService.java` (`CONFIG_PREFIX = "seedgrid.ratelimit."`) e `runtime/.../circuitbreaker/configs/CircuitBreakerConfigResolver.java` (`CONFIG_PREFIX = "seedgrid.circuitbreaker."`) |
+| Mecanismo | `org.eclipse.microprofile.config.Config` injetado por construtor + `config.getOptionalValue(prefixo + chave, Tipo.class)` com chave montada por concatenação. **Não há** `@ConfigMapping`, `@ConfigRoot`, `@ConfigProperty`, `ConfigProvider.getConfig()`, `META-INF/microprofile-config.properties` nem `application.properties` em `src/main` do runtime. O deployment (`SeedgridResilienceCoreProcessor`) só registra a feature; não há `*BuildTimeConfig`/`*RuntimeConfig` nem `@IfBuildProperty`/`@LookupIfProperty`. **Confirmado** (grep + leitura de todos os `.java`). |
+| Fase | **Runtime**. Lidas **a cada invocação** do método anotado (sem cache local). **Inferência**: alterações em uma fonte de config dinâmica seriam percebidas sem reinício; com `application.properties` estático, valem do boot em diante. |
+| Precedência | Atributo da anotação = padrão; property (quando a anotação tem `configKey`/`name` não vazio) = override. Sem `configKey`/`name`, **nenhuma** property é lida. |
+| MicroProfile Fault Tolerance | Não usado; chaves `<classe>/<método>/<Anotação>/<param>` não têm efeito nesta extension. |
+
+**Variáveis de ambiente (Inferência)**: as leituras são por nome exato via `Config#getOptionalValue`; a fonte de env do SmallRye procura o nome exato, depois com não alfanuméricos trocados por `_`, depois em maiúsculas. Logo `seedgrid.ratelimit.login.permits` ↔ `SEEDGRID_RATELIMIT_LOGIN_PERMITS` e `seedgrid.ratelimit.forgot-password.enabled` ↔ `SEEDGRID_RATELIMIT_FORGOT_PASSWORD_ENABLED`. Como a busca parte do nome (não da env), não há ambiguidade na leitura; mas `configKey` `forgot-password` e `forgot.password` colidiriam na mesma env. Não testado no repositório.
+
+Legenda da coluna *Padrão*: "atributo X da anotação" significa que, sem a property, vale o valor informado na anotação; entre parênteses o default declarado na própria anotação.
+
+## 2. Propriedades da extension
+
+### 2.1 Rate limit — `seedgrid.ratelimit.{configKey}.*`
+
+`{configKey}` = `SeedGridRateLimit#configKey()` (texto livre; cada valor é um limiter independente no que diz respeito à config — o contador no cache é definido pela chave `rl:...`, ver [[SeedGrid/Extensions/resilience/Visao-geral|Visão geral]]).
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `seedgrid.ratelimit.{configKey}.enabled` | `Boolean` | `true` \| `false` | `true` (fixo no código) | Não | `false` desliga o limiter: `tryAcquire` retorna `allow` sem tocar no cache (headers ainda emitidos com `permits`/janela da anotação se `emitHeaders=true`) | Kill switch por limiter | Só lida se `configKey` não vazio | Runtime (por chamada) | Declaração/consumo: `RateLimitService#isEnabled(String)` chamado em `#tryAcquire` |
+| `seedgrid.ratelimit.{configKey}.permits` | `Long` | inteiro `> 0` (senão `IllegalArgumentException("permits must be > 0")` na chamada) | atributo `permits` da anotação (`5`) | Não | Requisições permitidas por janela; no token bucket é a taxa de reposição por janela e a capacidade quando `burst-capacity` = 0 | Ajustar limite sem recompilar | `window`; `burst-capacity` | Runtime | `RateLimitService#resolvePermits` / `#validateConfig` |
+| `seedgrid.ratelimit.{configKey}.window` | `java.time.Duration` | ISO-8601 (`PT30S`, `PT1M`, `PT1H`) — confirmado pelo README e teste; outros formatos (ex.: `30s`) **não confirmado**. Deve resultar em `> 0` ms | atributo `window` × `windowUnit` (`30` × `SECONDS`) | Não | Tamanho da janela (substitui `window`+`windowUnit`); também TTL das chaves no cache | Ajustar janela | `permits` | Runtime | `RateLimitService#resolveWindowMs` |
+| `seedgrid.ratelimit.{configKey}.algorithm` | `String` → `RateLimitAlgorithm` | `fixed-window`, `sliding-window`, `token-bucket` ou os nomes do enum (`FIXED_WINDOW`, `SLIDING_WINDOW`, `TOKEN_BUCKET`) — [[SeedGrid/Extensions/resilience/Enums#RateLimitAlgorithm|RateLimitAlgorithm]]; case-insensitive, `-`→`_`. Valor inválido → `IllegalArgumentException` na chamada | atributo `algorithm` (`FIXED_WINDOW`) | Não | Seleciona estratégia `FixedWindowAlgorithm` / `SlidingWindowAlgorithm` / `TokenBucketAlgorithm` | Trocar algoritmo em produção | `burst-capacity` só afeta token bucket; `min-spacing` não afeta fixed window | Runtime | `RateLimitService#resolveAlgorithm` / `#resolveStrategy` |
+| `seedgrid.ratelimit.{configKey}.burst-capacity` | `Long` | `>= 0` (negativo → `IllegalArgumentException`) | atributo `burstCapacity` (`0`) | Não | Capacidade do bucket; `0` = usa `permits` | Permitir rajadas | Efetivo só com `token-bucket` | Runtime | `RateLimitService#resolveBurstCapacity`; consumo em `TokenBucketAlgorithm#doAcquire` |
+| `seedgrid.ratelimit.{configKey}.min-spacing` | `java.time.Duration` | ISO-8601 (`PT1S`, `PT0.2S`); `>= 0` | atributo `minSpacing` × `minSpacingUnit` (`0` × `MILLIS`; se `minSpacing>0` mas < 1 ms, vira 1 ms) | Não | Intervalo mínimo entre chamadas permitidas da mesma chave | Anti-martelada | **Ignorado** por `FIXED_WINDOW`; aplicado por `SLIDING_WINDOW` e `TOKEN_BUCKET` | Runtime | `RateLimitService#resolveMinSpacingMs`; consumo em `SlidingWindowAlgorithm`/`TokenBucketAlgorithm` |
+
+Atributos **somente na anotação** (sem property): `identity`, `group`, `scope`, `emitHeaders`, `configKey`, `windowUnit`, `minSpacingUnit`. **Confirmado** (`RateLimitService` não lê outras chaves).
+
+### 2.2 Circuit breaker — `seedgrid.circuitbreaker.{name}.*`
+
+`{name}` = `SeedGridCircuitBreaker#name()`. Sem `name`, o circuito usa a assinatura do método como nome e **nenhuma** property é lida.
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `seedgrid.circuitbreaker.{name}.enabled` | `Boolean` | `true` \| `false` | `true` (fixo no código) | Não | `false`: interceptor chama o método direto, sem estado nem fallback | Kill switch por circuito | Só lida se `name` não vazio | Runtime (por chamada) | `CircuitBreakerConfigResolver#isEnabled`; consumo `CircuitBreakerInterceptor#around` |
+| `seedgrid.circuitbreaker.{name}.sliding-window-size` | `Integer` | inteiro `> 0` (**Inferência**: 0/negativo quebraria o ring buffer; sem validação explícita) | atributo `slidingWindowSize` (`100`) | Não | Tamanho do ring buffer; em `TIME_BASED` também é a duração da janela **em segundos**. Mudar o valor descarta o estado salvo | Ajustar janela de métricas | `window-type`, `minimum-number-of-calls` | Runtime | `CircuitBreakerConfigResolver#resolve`; consumo `CacheBackedCircuitBreakerStore#addToRing/#evaluateThresholds/#deserialize` |
+| `seedgrid.circuitbreaker.{name}.window-type` | `String` → `SlidingWindowType` | `count-based`, `time-based` (ou `COUNT_BASED`/`TIME_BASED`) — [[SeedGrid/Extensions/resilience/Enums#SlidingWindowType|SlidingWindowType]]; case-insensitive, `-`→`_` | atributo `windowType` (`COUNT_BASED`) | Não | Janela por contagem ou por tempo | Escolher semântica da janela | `sliding-window-size` | Runtime | `CircuitBreakerConfigResolver#resolve`; consumo `CacheBackedCircuitBreakerStore#evaluateThresholds` |
+| `seedgrid.circuitbreaker.{name}.failure-rate-threshold` | `Double` | percentual (0–100; sem validação) | atributo `failureRateThreshold` (`50.0`) | Não | Abre quando `falhas*100/total >= valor` | Sensibilidade a falhas | `minimum-number-of-calls` | Runtime | `CircuitBreakerConfigResolver#resolve`; `CacheBackedCircuitBreakerStore#evaluateThresholds` |
+| `seedgrid.circuitbreaker.{name}.slow-call-duration` | `java.time.Duration` | ISO-8601 (`PT2S`) | atributo `slowCallDurationThresholdMs` (`0` = desligado) | Não | Chamada com duração `>=` valor conta como lenta; `0` desativa a regra de lentidão | Detectar degradação | Necessária (>0) para `slow-call-rate-threshold` ter efeito | Runtime | `CircuitBreakerConfigResolver#resolve` (→ `slowCallDurationThresholdMs`); `CacheBackedCircuitBreakerStore#doRecord/#evaluateThresholds` |
+| `seedgrid.circuitbreaker.{name}.slow-call-rate-threshold` | `Double` | percentual (0–100) | atributo `slowCallRateThreshold` (`100.0`) | Condicional (só tem efeito se `slow-call-duration` > 0) | Abre quando `lentas*100/total >= valor` | Abrir por lentidão | `slow-call-duration` | Runtime | `CircuitBreakerConfigResolver#resolve`; `CacheBackedCircuitBreakerStore#evaluateThresholds` |
+| `seedgrid.circuitbreaker.{name}.minimum-number-of-calls` | `Integer` | inteiro `>= 0` | atributo `minimumNumberOfCalls` (`20`) | Não | Mínimo de chamadas na janela antes de avaliar thresholds | Evitar abrir com amostra pequena | Se > `sliding-window-size`, o circuito nunca abre (**Inferência**: `totalFilled` ≤ tamanho do buffer) | Runtime | `CircuitBreakerConfigResolver#resolve`; `CacheBackedCircuitBreakerStore#evaluateThresholds` |
+| `seedgrid.circuitbreaker.{name}.open-state-duration` | `java.time.Duration` | ISO-8601 (`PT30S`) | atributo `openStateDurationMs` (`30000` ms) | Não | Tempo em `OPEN` antes de ir a `HALF_OPEN`; base do `retryAfterMs`; TTL do estado = `max(2×valor, 1h)` | Tempo de recuperação | `permitted-calls-in-half-open` | Runtime | `CircuitBreakerConfigResolver#resolve`; `CacheBackedCircuitBreakerStore#doAllowCall/#save` |
+| `seedgrid.circuitbreaker.{name}.permitted-calls-in-half-open` | `Integer` | inteiro `> 0` | atributo `permittedCallsInHalfOpen` (`10`) | Não | Nº de sondas em `HALF_OPEN`; todas precisam ter sucesso para fechar | Recuperação gradual | `open-state-duration` | Runtime | `CircuitBreakerConfigResolver#resolve`; `CacheBackedCircuitBreakerStore#doAllowCall/#doRecord` |
+
+Atributos **somente na anotação**: `recordExceptions` (default `{Exception.class}`), `ignoreExceptions` (default `{}`), `fallbackMethod` (default `""`), `name`. **Confirmado** (Javadoc de `CircuitBreakerConfigResolver` e código).
+
+Total de propriedades públicas da extension: **15** (6 rate limit + 9 circuit breaker), todas com segmento dinâmico.
+
+## 3. Propriedades de frameworks/bibliotecas
+
+| Propriedade | Situação | Observação | Origem |
+|---|---|---|---|
+| `quarkus.redis.hosts` | Recomendada (quando usar `seedgrid-cache-redis`) | Conexão do Redis usado pelo provider de cache | `README.adoc` § "Configuração do Redis" |
+| `quarkus.redis.password` 🔒 | Recomendada (se o Redis exigir) | Use `<SEGREDO:redis-password>` | `README.adoc` |
+| `quarkus.redis.timeout` | Opcional | Exemplo no README: `PT5S` | `README.adoc` |
+| `quarkus.redis.max-pool-size` | Opcional | Exemplo no README: `10` | `README.adoc` |
+
+A extension não define nem exige nenhuma propriedade `quarkus.*`/`mp.*`/`smallrye.*` em código. A seleção/configuração do provider de cache (Redis/Valkey/Dragonfly) pertence à lib cache — ver [[SeedGrid/Extensions/cache/Configuracao|Configuração do cache]].
+
+## 4. Propriedades usadas só em testes
+
+Nenhum `application.properties` com conteúdo (o de `integration-tests/src/main/resources` está vazio). Os testes unitários mockam `Config` com estas chaves (instâncias das propriedades da seção 2):
+
+| Chave | Teste |
+|---|---|
+| `seedgrid.ratelimit.checkout.permits`, `.enabled`, `.window`, `.algorithm` (`token-bucket`), `.burst-capacity` | `runtime/src/test/.../RateLimitServiceConfigOverrideTest` |
+| `seedgrid.circuitbreaker.payments.enabled`, `.sliding-window-size`, `.window-type` (`time-based`), `.failure-rate-threshold`, `.slow-call-duration`, `.slow-call-rate-threshold`, `.minimum-number-of-calls`, `.open-state-duration`, `.permitted-calls-in-half-open` | `runtime/src/test/.../CircuitBreakerConfigResolverTest` |
+
+Os ITs (`RedisTestBase`) montam o Redis via Testcontainers programaticamente (sem properties).
+
+## 5. Aliases, obsoletas, renomeações
+
+- `algorithm` e `window-type` aceitam tanto kebab-case quanto o nome do enum (normalização `trim().toUpperCase().replace('-', '_')`). **Confirmado**.
+- `window`/`min-spacing`/`slow-call-duration`/`open-state-duration` substituem pares da anotação (`window`+`windowUnit`, `minSpacing`+`minSpacingUnit`, `slowCallDurationThresholdMs`, `openStateDurationMs`) — nomes diferentes entre anotação e property.
+- Nenhuma propriedade obsoleta encontrada.
+
+## 6. Configuração mínima
+
+Nenhuma property é obrigatória: as anotações já trazem os valores. Para estado compartilhado entre instâncias, adicione um provider de cache distribuído e sua conexão:
+
+```properties
+# Provider seedgrid-cache-redis no classpath
+quarkus.redis.hosts=redis://<host>:6379
+quarkus.redis.password=<SEGREDO:redis-password>
+```
+
+## 7. Configuração completa comentada
+
+```properties
+# ===== Rate limit: um bloco por configKey usado em @SeedGridRateLimit(configKey = "...") =====
+# liga/desliga o limiter (padrão true)
+seedgrid.ratelimit.<configKey>.enabled=true
+# requisições por janela (> 0)
+seedgrid.ratelimit.<configKey>.permits=<n>
+# janela ISO-8601 (> 0), ex.: PT1M
+seedgrid.ratelimit.<configKey>.window=<duration>
+# fixed-window | sliding-window | token-bucket
+seedgrid.ratelimit.<configKey>.algorithm=<algoritmo>
+# capacidade do bucket (>= 0; 0 = usa permits) — só token-bucket
+seedgrid.ratelimit.<configKey>.burst-capacity=<n>
+# intervalo mínimo entre chamadas (ISO-8601) — ignorado em fixed-window
+seedgrid.ratelimit.<configKey>.min-spacing=<duration>
+
+# ===== Circuit breaker: um bloco por name usado em @SeedGridCircuitBreaker(name = "...") =====
+# liga/desliga o circuito (padrão true)
+seedgrid.circuitbreaker.<name>.enabled=true
+# tamanho da janela (nº de chamadas; em time-based também = segundos)
+seedgrid.circuitbreaker.<name>.sliding-window-size=<n>
+# count-based | time-based
+seedgrid.circuitbreaker.<name>.window-type=<tipo>
+# % de falhas para abrir
+seedgrid.circuitbreaker.<name>.failure-rate-threshold=<percentual>
+# duração a partir da qual a chamada é lenta (ISO-8601); omitir/0 desliga
+seedgrid.circuitbreaker.<name>.slow-call-duration=<duration>
+# % de chamadas lentas para abrir (exige slow-call-duration > 0)
+seedgrid.circuitbreaker.<name>.slow-call-rate-threshold=<percentual>
+# mínimo de chamadas antes de avaliar
+seedgrid.circuitbreaker.<name>.minimum-number-of-calls=<n>
+# tempo aberto antes do half-open (ISO-8601)
+seedgrid.circuitbreaker.<name>.open-state-duration=<duration>
+# sondas no half-open
+seedgrid.circuitbreaker.<name>.permitted-calls-in-half-open=<n>
+
+# ===== Cache distribuído (lib seedgrid-cache-redis) =====
+quarkus.redis.hosts=redis://<host>:6379
+quarkus.redis.password=<SEGREDO:redis-password>
+```
+
+## 8. Receitas
+
+**Desligar um limiter em produção** (método com `configKey = "forgot-password"`):
+```properties
+seedgrid.ratelimit.forgot-password.enabled=false
+```
+
+**Afrouxar o login temporariamente** (`configKey = "login"`):
+```properties
+seedgrid.ratelimit.login.permits=200
+seedgrid.ratelimit.login.window=PT30S
+```
+
+**Trocar para token bucket com rajada e espaçamento** (`configKey = "export-create"`):
+```properties
+seedgrid.ratelimit.export-create.algorithm=token-bucket
+seedgrid.ratelimit.export-create.burst-capacity=3
+seedgrid.ratelimit.export-create.min-spacing=PT1S
+```
+
+**Circuito mais sensível, com detecção de lentidão** (`name = "payments"`):
+```properties
+seedgrid.circuitbreaker.payments.failure-rate-threshold=25
+seedgrid.circuitbreaker.payments.minimum-number-of-calls=5
+seedgrid.circuitbreaker.payments.slow-call-duration=PT2S
+seedgrid.circuitbreaker.payments.slow-call-rate-threshold=80
+seedgrid.circuitbreaker.payments.open-state-duration=PT10S
+```
+
+**Janela por tempo de 20 s**:
+```properties
+seedgrid.circuitbreaker.payments.window-type=time-based
+seedgrid.circuitbreaker.payments.sliding-window-size=20
+```
+
+## 9. Dúvidas e lacunas
+
+- Formatos de `Duration` além de ISO-8601 (ex.: `30s`): dependem do conversor registrado no Quarkus; **não confirmado** nesta extension.
+- Variáveis de ambiente: mapeamento descrito é **Inferência** (regra SmallRye), sem teste no repositório.
+- Sem validação no boot: chaves com erro de digitação são silenciosamente ignoradas; valores inválidos (`algorithm`, `window-type`, `permits<=0`) só falham na chamada.
+- `sliding-window-size` e `permitted-calls-in-half-open` não têm validação de positivo.
+- Não há propriedade global (ex.: desligar todos os limiters ou escolher store) — apenas por `configKey`/`name`.

package/seedgridKB/SeedGrid/Extensions/resilience/Enums.md

@@ -0,0 +1,96 @@
+---
+tags: [seedgrid, extension, resilience, enum]
+fonte: java/seedgrid-quarkus-ext-resilience
+branch: main
+commit: eff41304f8
+analisado-em: 2026-10-14
+---
+
+# SeedGrid Resilience — Enums
+
+Todos os enums ficam em `runtime/src/main/java/br/com/seedgrid/resilience/core/runtime/`. Enums de teste não foram considerados. Visão geral: [[SeedGrid/Extensions/resilience/Visao-geral|Visão geral]]; propriedades: [[SeedGrid/Extensions/resilience/Configuracao|Configuração]]; equivalentes Rust: [[SeedGrid/Extensions/resilience/Rust|Rust]].
+
+## Índice
+
+| Enum | Pacote/arquivo | Usado em | Público? |
+|---|---|---|---|
+| [[#RateLimitAlgorithm]] | `ratelimiter.enums` | `@SeedGridRateLimit#algorithm`, propriedade `seedgrid.ratelimit.{configKey}.algorithm` | Sim |
+| [[#KeyScope]] | `circuitbreaker.enums` (pacote do CB, mas só o rate limit usa) | `@SeedGridRateLimit#scope` | Sim |
+| [[#SlidingWindowType]] | `circuitbreaker.enums` | `@SeedGridCircuitBreaker#windowType`, `CircuitBreakerConfig`, propriedade `seedgrid.circuitbreaker.{name}.window-type` | Sim |
+| [[#CircuitState]] | `circuitbreaker.enums` | `CircuitDecision#state()` (retorno do SPI `CircuitBreakerStore#allowCall`), estado persistido no cache | Sim |
+
+## RateLimitAlgorithm
+
+Arquivo: `ratelimiter/enums/RateLimitAlgorithm.java` — FQN `br.com.seedgrid.resilience.core.runtime.ratelimiter.enums.RateLimitAlgorithm`.
+
+| Valor | Significado | Efeito / onde é tratado | Observações |
+|---|---|---|---|
+| `FIXED_WINDOW` | Janela fixa (default da anotação) | `RateLimitService#resolveStrategy` → `FixedWindowAlgorithm` | **Confirmado** |
+| `TOKEN_BUCKET` | Balde de tokens | → `TokenBucketAlgorithm`; `burstCapacity` só tem efeito aqui | **Confirmado** |
+| `SLIDING_WINDOW` | Janela deslizante | → `SlidingWindowAlgorithm` | **Confirmado** |
+
+- Campos/métodos: nenhum (enum puro). `switch` exaustivo sem `default` em `resolveStrategy`.
+- Serialização: não é persistido nem exposto em JSON. Na config é lido como `String` e convertido por `RateLimitAlgorithm.valueOf(v.trim().toUpperCase().replace('-', '_'))` — aceita `token-bucket`, `Token_Bucket` etc.; valor inválido lança `IllegalArgumentException` **na chamada** (não no boot). Só é lido quando a anotação tem `configKey`.
+- Usado em: [[SeedGrid/Extensions/resilience/Configuracao|`seedgrid.ratelimit.{configKey}.algorithm`]]; anotação `@SeedGridRateLimit`.
+- Todas as constantes são tratadas.
+
+## KeyScope
+
+Arquivo: `circuitbreaker/enums/KeyScope.java` — FQN `br.com.seedgrid.resilience.core.runtime.circuitbreaker.enums.KeyScope`.
+
+| Valor | Significado | Efeito / onde é tratado | Observações |
+|---|---|---|---|
+| `METHOD` | Limite por método (default) | `RateLimitService#buildKey`: `scopePart` = `methodSignature` (`Classe#metodo(tipos)`) | **Confirmado** |
+| `CLASS` | Limite compartilhado por classe | `scopePart` = `invocation.getTarget().getClass().getName()` | **Confirmado**; é a classe do alvo (pode ser subclasse/proxy CDI — **Inferência**) |
+| `GROUP` | Limite compartilhado por grupo lógico | `scopePart` = `ann.group()`; se vazio/blank cai em `methodSignature` | **Confirmado** |
+
+- Campos/métodos: nenhum.
+- Serialização: não é lido da config (só atributo da anotação); entra apenas na chave de cache `rl:{tenant}[:{operation}]:{scopePart}:{identity}`.
+- Observação: o enum vive no pacote `circuitbreaker.enums`, mas o circuit breaker não o usa.
+
+## SlidingWindowType
+
+Arquivo: `circuitbreaker/enums/SlidingWindowType.java` — FQN `br.com.seedgrid.resilience.core.runtime.circuitbreaker.enums.SlidingWindowType`.
+
+| Valor | Significado | Efeito / onde é tratado | Observações |
+|---|---|---|---|
+| `COUNT_BASED` | Janela por contagem (default) | `CacheBackedCircuitBreakerStore#evaluateThresholds`: sem corte temporal (`windowStart = Long.MIN_VALUE`) | **Confirmado** |
+| `TIME_BASED` | Janela por tempo | `windowStart = now - slidingWindowSize*1000`; `slidingWindowSize` vira **segundos**; entradas com timestamp `<= windowStart` são ignoradas | **Confirmado** |
+
+- Campos/métodos: nenhum. O código só compara com `TIME_BASED`; qualquer outro valor se comportaria como `COUNT_BASED`.
+- Serialização: não é persistido no estado do cache. Na config: `String` → `valueOf(v.trim().toUpperCase().replace('-', '_'))`; inválido → `IllegalArgumentException` na chamada. Só é lido quando a anotação tem `name` preenchido (`CircuitBreakerConfigResolver#resolve`).
+- Usado em: [[SeedGrid/Extensions/resilience/Configuracao|`seedgrid.circuitbreaker.{name}.window-type`]]; `@SeedGridCircuitBreaker#windowType`; `CircuitBreakerConfig`.
+
+## CircuitState
+
+Arquivo: `circuitbreaker/enums/CircuitState.java` — FQN `br.com.seedgrid.resilience.core.runtime.circuitbreaker.enums.CircuitState`.
+
+| Valor | Significado | Efeito / onde é tratado | Observações |
+|---|---|---|---|
+| `CLOSED` (ordinal 0) | Chamadas passam; métricas gravadas | `doAllowCall` permite; `doRecord` grava no ring e avalia limiares | Estado inicial e fallback de ordinal inválido. **Confirmado** |
+| `OPEN` (ordinal 1) | Chamadas negadas | `doAllowCall`: se `elapsed >= openStateDurationMs` → `HALF_OPEN`, senão `deny(restante)`; `doRecord` ignora resultados | **Confirmado** |
+| `HALF_OPEN` (ordinal 2) | Sondagem com até `permittedCallsInHalfOpen` chamadas | permite até o limite, depois `deny(0)`; falha → `OPEN`; `permittedCallsInHalfOpen` sucessos → `CLOSED` (zera o ring) | **Confirmado** |
+
+- Campos/métodos: nenhum.
+- Persistência: **por ordinal** — `circuitState.ordinal()` (int de 4 bytes) no blob binário do cache (`serialize`/`deserialize`); ordinal fora de 0..2 → `CLOSED`. **Reordenar ou inserir constantes quebra estados já gravados e a compatibilidade com o Rust** (ver [[SeedGrid/Extensions/resilience/Rust|Rust]]). Sem JSON, sem tabela SQL/CHECK.
+- Exposição: `CircuitDecision#state()` retorna `CLOSED`/`HALF_OPEN` em `allow` e sempre `OPEN` em `deny`; nenhum código do módulo lê `state()` (o interceptor usa só `allowed()` e `retryAfterMs()`).
+
+```mermaid
+stateDiagram-v2
+    [*] --> CLOSED
+    CLOSED --> OPEN: limiar de falha/lentidão
+    OPEN --> HALF_OPEN: openStateDuration expirou (próxima chamada)
+    HALF_OPEN --> OPEN: qualquer falha
+    HALF_OPEN --> CLOSED: permittedCallsInHalfOpen sucessos
+```
+
+A transição `CLOSED → OPEN` está em `CacheBackedCircuitBreakerStore` (`s.circuitState = CircuitState.OPEN` após `evaluateThresholds`).
+
+## Internos
+
+Nenhum enum interno em `src/main`; os 4 acima são públicos. Enum do JDK no contrato: `java.time.temporal.ChronoUnit` em `@SeedGridRateLimit#windowUnit` (default `SECONDS`) e `#minSpacingUnit` (default `MILLIS`).
+
+## Notas Rust
+
+- Grafia em PascalCase (`Closed`, `HalfOpen`, `CountBased`…); valor de string inválido causa `panic!`.
+- `TimeUnit` aceita só `Millis`, `Seconds`, `Minutes`, `Hours`.