@seedgrid/ai-toolkit 0.3.0 → 0.3.1

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

@@ -1,93 +1,93 @@
----
-tags: [seedgrid, extension, audit, rust, configuracao]
-fonte: rust/seedgrid-rust-crate-audit
-branch: main
-commit: be738a2d1e
-analisado-em: 2026-10-14
----
-
-# audit — Configuração Rust
-
-Visão do crate: [[SeedGrid/Extensions/audit/Rust|Porte Rust do audit]] · Java: [[SeedGrid/Extensions/audit/Configuracao|Configuração do audit (Java)]].
-
-## Cabeçalho
-| Item | Valor |
-|---|---|
-| Struct | `AuditConfig` (+ `MongoConfig`, `JpaConfig`, enum `AuditPersistenceStrategy`) — `rust/seedgrid-rust-crate-audit/src/config.rs` |
-| Mecanismo | `AuditConfig::from_env()` lê `std::env::var`; ou struct construída pelo host (`AuditConfig::default()` / literal) |
-| Prefixo Java equivalente | `seedgrid.audit` (`@ConfigMapping` em `AuditConfig.java`) |
-| Quem chama `from_env` | `AuditPlatform::assemble` (`src/platform.rs`) e o host (ex.: exemplo `seedgrid-audit-example`) |
-| Leitura | uma vez, quando `from_env()` é chamado (no boot do host); sem recarga |
-
-Regras gerais do helper `opt(name)` (`src/config.rs`): valor é `trim()`ado e string vazia vale como ausente. `SEEDGRID_AUDIT_ENABLED` e `AUDIT_STRATEGY` não passam por `opt` (sem trim no `enabled`).
-
-## Variáveis de ambiente
-
-### Ativação e estratégia
-| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
-|---|---|---|---|---|---|---|---|---|---|
-| `SEEDGRID_AUDIT_ENABLED` | bool | `true`/`false` (parse `bool` do Rust, sensível a maiúsculas) | `true` | Não | `false` torna `Auditor::record` no-op e faz `AuditPlatform::assemble` devolver `Ok(None)`. Valor inválido → `true` | liga/desliga auditoria | — | `from_env()` | decl.: `config.rs` → `AuditConfig::from_env`; consumo: `state.rs` (`if !self.config.enabled`), `platform.rs` → `AuditPlatform::assemble` |
-| `AUDIT_STRATEGY` (Java: `seedgrid.audit.persistence.strategy`, via `${AUDIT_STRATEGY:...}`) | enum `AuditPersistenceStrategy` | `JPA`, `POSTGRES`, `POSTGRESQL` → `Jpa`; `MONGODB`, `MONGO` → `Mongodb` (case-insensitive, trim) | derivado da feature: `Jpa` com `postgres` (também quando ambas ou nenhuma); `Mongodb` só com `mongodb` sem `postgres` | Não | valor desconhecido → default da feature. `AuditState::postgres/mongodb` falham (`AuditError::Config`) se a estratégia não casar com o backend | escolhe backend no `AuditPlatform`; valida construtor | `MONGODB` sem a feature `mongodb` → `assemble` loga erro e devolve `Ok(None)` | `from_env()` | `config.rs` → `default_strategy`, `AuditPersistenceStrategy::parse`; `state.rs` → `validate_strategy`; `platform.rs` |
-
-### Relacional (JPA/Postgres)
-| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
-|---|---|---|---|---|---|---|---|---|---|
-| `SEEDGRID_AUDIT_DB_URL` (Java: `seedgrid.audit.jpa.jdbc.url`) | `Option<String>` | `jdbc:postgresql:...`, `postgres://...`, `postgresql://...` | — | Condicional: só se o host usar `pg_connection_url()` | `AuditConfig::pg_connection_url()` remove `jdbc:`; outro formato → `AuditError::Config` | método público; nenhum chamador no workspace | `AuditPlatform` usa o `PgPool` recebido do host | `from_env()` | `config.rs` → `pg_connection_url` |
-
-### MongoDB
-| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
-|---|---|---|---|---|---|---|---|---|---|
-| 🔒 `SEEDGRID_AUDIT_MONGODB_URI` (Java: `seedgrid.audit.mongodb.connection-string`, via `${SEEDGRID_AUDIT_MONGODB_URI:...}`) | `Option<String>` (sempre `Some` após `from_env`) | URI MongoDB | `DEFAULT_MONGODB_URI` = `mongodb://<usuario>:<SEGREDO:mongo-dev>@localhost:27017` (credenciais de dev embutidas, redigidas aqui) | Condicional: estratégia `Mongodb` | URI usada por `effective_mongo_uri()`; falha de conexão → auditoria no-op (`Ok(None)`) | `AuditPlatform::assemble_mongo` | requer feature `mongodb` | `from_env()` | `config.rs` → `DEFAULT_MONGODB_URI`, `effective_mongo_uri`; `platform.rs` |
-| `SEEDGRID_AUDIT_MONGODB_DATABASE` (Java: `seedgrid.audit.mongodb.database`) | `Option<String>` | nome de banco | sem padrão no config; `AuditPlatform` usa `seedgrid_audit` quando ausente | Não | nome do banco Mongo | `AuditPlatform::assemble_mongo` | — | `from_env()` | `config.rs`; `platform.rs` |
-
-Mapeamento Java ↔ env: **Confirmado** para `AUDIT_STRATEGY`, `SEEDGRID_AUDIT_DB_URL` e `SEEDGRID_AUDIT_MONGODB_URI` (expressões `${...}` em `java/seedgrid-quarkus-ext-audit/*/runtime/src/main/resources/META-INF/microprofile-config.properties`). `SEEDGRID_AUDIT_MONGODB_DATABASE` corresponde à conversão padrão MicroProfile de `seedgrid.audit.mongodb.database` (**Confirmado** pela regra, sem hífen ambíguo). `SEEDGRID_AUDIT_ENABLED` é uma opção só do Rust.
-
-## Structs (construção pelo host)
-| Campo | Tipo | `Default` | Notas |
-|---|---|---|---|
-| `AuditConfig.enabled` | `bool` | `true` | |
-| `AuditConfig.strategy` | `AuditPersistenceStrategy` | `default_strategy()` | `#[default]` do enum é `Jpa`, mas `AuditConfig::default()` usa `default_strategy()` |
-| `AuditConfig.mongodb` | `MongoConfig { database, connection_string }` | ambos `None` | com `None`, `effective_mongo_uri()` cai no `DEFAULT_MONGODB_URI` |
-| `AuditConfig.jpa.jdbc_url` | `Option<String>` | `None` | usado só por `pg_connection_url()` |
-
-## Features Cargo
-| Feature | Padrão | Efeito |
-|---|---|---|
-| `postgres` | sim | habilita `sqlx`, `postgres.rs`, `migrate`, `MIGRATOR`, `AuditPlatform`, `AuditState::postgres`; muda `default_strategy()` para `Jpa` |
-| `mongodb` | não | habilita `mongodb`/`bson`, `mongodb.rs`, `AuditState::mongodb`; sem `postgres`, `default_strategy()` vira `Mongodb` |
-
-## Configuração não-env (código)
-- Autorização de leitura: `AuditStateBuilder::read_authorizer(...)` — default `DenyAllAuditReadAuthorizer` (403). Não há variável de ambiente.
-- Escopo de leitura, request context e contribuidores: via builder (`src/state.rs`).
-
-## Somente testes / exemplos
-| Variável | Onde | Finalidade |
-|---|---|---|
-| `AUDIT_IT_PG_URL` | `tests/pg_metadata_it.rs` | Postgres para IT `#[ignore]` |
-| `AUDIT_IT_MONGO_URI` | `tests/mongo_metadata_it.rs` | Mongo para IT `#[ignore]` |
-| `DATABASE_URL` | `examples/seedgrid-audit-example/src/main.rs` | conexão do exemplo (lida pelo exemplo, não pela crate) |
-| `DOCKER_HOST`, `TESTCONTAINERS_RYUK_DISABLED` | `.env.example` do exemplo | Testcontainers/Podman |
-
-## Configuração mínima (`.env`)
-```dotenv
-# Postgres (feature default): a conexão é do host; a crate só precisa disto se quiser desligar
-SEEDGRID_AUDIT_ENABLED=true
-```
-
-## Configuração completa comentada
-```dotenv
-SEEDGRID_AUDIT_ENABLED=true            # false => Auditor no-op
-AUDIT_STRATEGY=JPA                     # JPA|POSTGRES|POSTGRESQL|MONGODB|MONGO
-SEEDGRID_AUDIT_DB_URL=jdbc:postgresql://<host>:5432/<db>   # só via pg_connection_url()
-# Mongo (feature mongodb + AUDIT_STRATEGY=MONGODB)
-SEEDGRID_AUDIT_MONGODB_URI=mongodb://<usuario>:<SEGREDO:audit-mongo>@<host>:27017
-SEEDGRID_AUDIT_MONGODB_DATABASE=seedgrid_audit
-```
-
-## Receitas
-- **Postgres (padrão)**: compile com a feature default, crie o `PgPool`, `seedgrid_audit::migrate(&pool)`, `AuditState::postgres(pool, AuditConfig::from_env())?`, registre um `AuditReadAuthorizer` que valide `LOG_READ`.
-- **MongoDB**: `default-features = false, features = ["mongodb"]`, `AUDIT_STRATEGY=MONGODB` (ou deixe o default da feature), `SEEDGRID_AUDIT_MONGODB_URI` e `SEEDGRID_AUDIT_MONGODB_DATABASE`.
-- **Desligar**: `SEEDGRID_AUDIT_ENABLED=false`.
-
-## Dúvidas e lacunas
-- `SEEDGRID_AUDIT_DB_URL` só tem efeito se o host chamar `pg_connection_url()`; `AuditPlatform` e os construtores usam o `PgPool` do host.
+---
+tags: [seedgrid, extension, audit, rust, configuracao]
+fonte: rust/seedgrid-rust-crate-audit
+branch: main
+commit: be738a2d1e
+analisado-em: 2026-10-14
+---
+
+# audit — Configuração Rust
+
+Visão do crate: [[SeedGrid/Extensions/audit/Rust|Porte Rust do audit]] · Java: [[SeedGrid/Extensions/audit/Configuracao|Configuração do audit (Java)]].
+
+## Cabeçalho
+| Item | Valor |
+|---|---|
+| Struct | `AuditConfig` (+ `MongoConfig`, `JpaConfig`, enum `AuditPersistenceStrategy`) — `rust/seedgrid-rust-crate-audit/src/config.rs` |
+| Mecanismo | `AuditConfig::from_env()` lê `std::env::var`; ou struct construída pelo host (`AuditConfig::default()` / literal) |
+| Prefixo Java equivalente | `seedgrid.audit` (`@ConfigMapping` em `AuditConfig.java`) |
+| Quem chama `from_env` | `AuditPlatform::assemble` (`src/platform.rs`) e o host (ex.: exemplo `seedgrid-audit-example`) |
+| Leitura | uma vez, quando `from_env()` é chamado (no boot do host); sem recarga |
+
+Regras gerais do helper `opt(name)` (`src/config.rs`): valor é `trim()`ado e string vazia vale como ausente. `SEEDGRID_AUDIT_ENABLED` e `AUDIT_STRATEGY` não passam por `opt` (sem trim no `enabled`).
+
+## Variáveis de ambiente
+
+### Ativação e estratégia
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `SEEDGRID_AUDIT_ENABLED` | bool | `true`/`false` (parse `bool` do Rust, sensível a maiúsculas) | `true` | Não | `false` torna `Auditor::record` no-op e faz `AuditPlatform::assemble` devolver `Ok(None)`. Valor inválido → `true` | liga/desliga auditoria | — | `from_env()` | decl.: `config.rs` → `AuditConfig::from_env`; consumo: `state.rs` (`if !self.config.enabled`), `platform.rs` → `AuditPlatform::assemble` |
+| `AUDIT_STRATEGY` (Java: `seedgrid.audit.persistence.strategy`, via `${AUDIT_STRATEGY:...}`) | enum `AuditPersistenceStrategy` | `JPA`, `POSTGRES`, `POSTGRESQL` → `Jpa`; `MONGODB`, `MONGO` → `Mongodb` (case-insensitive, trim) | derivado da feature: `Jpa` com `postgres` (também quando ambas ou nenhuma); `Mongodb` só com `mongodb` sem `postgres` | Não | valor desconhecido → default da feature. `AuditState::postgres/mongodb` falham (`AuditError::Config`) se a estratégia não casar com o backend | escolhe backend no `AuditPlatform`; valida construtor | `MONGODB` sem a feature `mongodb` → `assemble` loga erro e devolve `Ok(None)` | `from_env()` | `config.rs` → `default_strategy`, `AuditPersistenceStrategy::parse`; `state.rs` → `validate_strategy`; `platform.rs` |
+
+### Relacional (JPA/Postgres)
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `SEEDGRID_AUDIT_DB_URL` (Java: `seedgrid.audit.jpa.jdbc.url`) | `Option<String>` | `jdbc:postgresql:...`, `postgres://...`, `postgresql://...` | — | Condicional: só se o host usar `pg_connection_url()` | `AuditConfig::pg_connection_url()` remove `jdbc:`; outro formato → `AuditError::Config` | método público; nenhum chamador no workspace | `AuditPlatform` usa o `PgPool` recebido do host | `from_env()` | `config.rs` → `pg_connection_url` |
+
+### MongoDB
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| 🔒 `SEEDGRID_AUDIT_MONGODB_URI` (Java: `seedgrid.audit.mongodb.connection-string`, via `${SEEDGRID_AUDIT_MONGODB_URI:...}`) | `Option<String>` (sempre `Some` após `from_env`) | URI MongoDB | `DEFAULT_MONGODB_URI` = `mongodb://<usuario>:<SEGREDO:mongo-dev>@localhost:27017` (credenciais de dev embutidas, redigidas aqui) | Condicional: estratégia `Mongodb` | URI usada por `effective_mongo_uri()`; falha de conexão → auditoria no-op (`Ok(None)`) | `AuditPlatform::assemble_mongo` | requer feature `mongodb` | `from_env()` | `config.rs` → `DEFAULT_MONGODB_URI`, `effective_mongo_uri`; `platform.rs` |
+| `SEEDGRID_AUDIT_MONGODB_DATABASE` (Java: `seedgrid.audit.mongodb.database`) | `Option<String>` | nome de banco | sem padrão no config; `AuditPlatform` usa `seedgrid_audit` quando ausente | Não | nome do banco Mongo | `AuditPlatform::assemble_mongo` | — | `from_env()` | `config.rs`; `platform.rs` |
+
+Mapeamento Java ↔ env: **Confirmado** para `AUDIT_STRATEGY`, `SEEDGRID_AUDIT_DB_URL` e `SEEDGRID_AUDIT_MONGODB_URI` (expressões `${...}` em `java/seedgrid-quarkus-ext-audit/*/runtime/src/main/resources/META-INF/microprofile-config.properties`). `SEEDGRID_AUDIT_MONGODB_DATABASE` corresponde à conversão padrão MicroProfile de `seedgrid.audit.mongodb.database` (**Confirmado** pela regra, sem hífen ambíguo). `SEEDGRID_AUDIT_ENABLED` é uma opção só do Rust.
+
+## Structs (construção pelo host)
+| Campo | Tipo | `Default` | Notas |
+|---|---|---|---|
+| `AuditConfig.enabled` | `bool` | `true` | |
+| `AuditConfig.strategy` | `AuditPersistenceStrategy` | `default_strategy()` | `#[default]` do enum é `Jpa`, mas `AuditConfig::default()` usa `default_strategy()` |
+| `AuditConfig.mongodb` | `MongoConfig { database, connection_string }` | ambos `None` | com `None`, `effective_mongo_uri()` cai no `DEFAULT_MONGODB_URI` |
+| `AuditConfig.jpa.jdbc_url` | `Option<String>` | `None` | usado só por `pg_connection_url()` |
+
+## Features Cargo
+| Feature | Padrão | Efeito |
+|---|---|---|
+| `postgres` | sim | habilita `sqlx`, `postgres.rs`, `migrate`, `MIGRATOR`, `AuditPlatform`, `AuditState::postgres`; muda `default_strategy()` para `Jpa` |
+| `mongodb` | não | habilita `mongodb`/`bson`, `mongodb.rs`, `AuditState::mongodb`; sem `postgres`, `default_strategy()` vira `Mongodb` |
+
+## Configuração não-env (código)
+- Autorização de leitura: `AuditStateBuilder::read_authorizer(...)` — default `DenyAllAuditReadAuthorizer` (403). Não há variável de ambiente.
+- Escopo de leitura, request context e contribuidores: via builder (`src/state.rs`).
+
+## Somente testes / exemplos
+| Variável | Onde | Finalidade |
+|---|---|---|
+| `AUDIT_IT_PG_URL` | `tests/pg_metadata_it.rs` | Postgres para IT `#[ignore]` |
+| `AUDIT_IT_MONGO_URI` | `tests/mongo_metadata_it.rs` | Mongo para IT `#[ignore]` |
+| `DATABASE_URL` | `examples/seedgrid-audit-example/src/main.rs` | conexão do exemplo (lida pelo exemplo, não pela crate) |
+| `DOCKER_HOST`, `TESTCONTAINERS_RYUK_DISABLED` | `.env.example` do exemplo | Testcontainers/Podman |
+
+## Configuração mínima (`.env`)
+```dotenv
+# Postgres (feature default): a conexão é do host; a crate só precisa disto se quiser desligar
+SEEDGRID_AUDIT_ENABLED=true
+```
+
+## Configuração completa comentada
+```dotenv
+SEEDGRID_AUDIT_ENABLED=true            # false => Auditor no-op
+AUDIT_STRATEGY=JPA                     # JPA|POSTGRES|POSTGRESQL|MONGODB|MONGO
+SEEDGRID_AUDIT_DB_URL=jdbc:postgresql://<host>:5432/<db>   # só via pg_connection_url()
+# Mongo (feature mongodb + AUDIT_STRATEGY=MONGODB)
+SEEDGRID_AUDIT_MONGODB_URI=mongodb://<usuario>:<SEGREDO:audit-mongo>@<host>:27017
+SEEDGRID_AUDIT_MONGODB_DATABASE=seedgrid_audit
+```
+
+## Receitas
+- **Postgres (padrão)**: compile com a feature default, crie o `PgPool`, `seedgrid_audit::migrate(&pool)`, `AuditState::postgres(pool, AuditConfig::from_env())?`, registre um `AuditReadAuthorizer` que valide `LOG_READ`.
+- **MongoDB**: `default-features = false, features = ["mongodb"]`, `AUDIT_STRATEGY=MONGODB` (ou deixe o default da feature), `SEEDGRID_AUDIT_MONGODB_URI` e `SEEDGRID_AUDIT_MONGODB_DATABASE`.
+- **Desligar**: `SEEDGRID_AUDIT_ENABLED=false`.
+
+## Dúvidas e lacunas
+- `SEEDGRID_AUDIT_DB_URL` só tem efeito se o host chamar `pg_connection_url()`; `AuditPlatform` e os construtores usam o `PgPool` do host.

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

@@ -1,186 +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`.
+---
+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`.