README

R4Policy Engine — motor declarativo de políticas de resiliência (Retry, Circuit Breaker, Rate Limiter, Bulkhead...)
inspirado em Resilience4j e integrado ao ecossistema R4PHP da Resilience4u.

Visão Geral

O R4Policy Engine permite definir e avaliar políticas de resiliência a partir de arquivos YAML ou JSON —
criando chains compostas de Retry, Circuit Breaker, Timeout e outros comportamentos.

Ele é o componente de Policy Evaluation da iniciativa Resilience4u,
e pode ser usado de forma standalone ou acoplado ao r4php.

Estrutura e Conceitos

+ src/
  ├── CLI/                 # Comandos CLI (validate, dump, diff)
  ├── Evaluator/           # Avaliação e encadeamento de políticas
  ├── Loader/              # Carregadores YAML e JSON
  ├── Model/               # PolicyDefinition e Registry
  ├── Telemetry/           # Métricas e instrumentação (R4Telemetry-ready)
  └── R4PolicyEngine.php   # Núcleo de execução

Principais entidades:

Classe	Responsabilidade
`R4PolicyEngine`	Gerencia registro, carregamento e avaliação de políticas
`PolicyDefinition`	Representação imutável de uma política declarada
`PolicyEvaluator`	Cria chains de execução resiliente com base nas definições
`YamlPolicyLoader` / `JsonPolicyLoader`	Faz o parsing de arquivos de configuração
`TelemetryBridge`	Ponto de integração com `R4Telemetry`

Instalação

composer require resilience4u/r4policy-engine

Uso via CLI

O r4policy inclui um CLI pronto (baseado em Symfony Console) para validar, inspecionar e comparar arquivos de políticas.

Validar um arquivo

./bin/r4policy validate policies.yaml

Saída esperada:

OK - policies.yaml is valid.

Listar políticas carregadas

./bin/r4policy dump policies.yaml

Exemplo de saída:

Loaded policies:
- user_api [retry]
- send_email [circuit_breaker]

Comparar dois arquivos (diff)

./bin/r4policy diff old.yaml new.yaml

Exemplo:

~ changed user_api
+ added   payment_gateway
- removed legacy_service

Testes e Cobertura

Executar toda a suíte de testes com cobertura HTML:

composer test

ou diretamente:

./vendor/bin/phpunit --colors=always --coverage-html build/coverage

A cobertura atual atinge ~82% das linhas, com cenários de integração e CLI totalmente testados.

Design

Inspirado em Resilience4j e Hystrix
Totalmente modular, extensível e framework-agnostic
Integrável com Resiliente\R4PHP (implementações de políticas concretas)
Telemetria desacoplada via TelemetryBridge

Roadmap (v0.2+)

Adicionar suporte a TimeLimiter e Bulkhead
Exportar métricas para R4Telemetry
Adicionar schema validation no loader
Suporte a políticas compostas e encadeamentos dinâmicos

resilience4u / r4policy-engine

Maintainers

Details