Feature/dependency injection

[regyssilveira]

feat: Contextual Dependency Injection (Request Scope) & Graceful Shutdown

🎯 Descrição

Este Pull Request introduz duas melhorias arquiteturais cruciais na evolução técnica do framework Horse: o Gerenciamento e Injeção de Dependências Contextuais (Request Scope) e a infraestrutura de Desligamento Suave (Graceful Shutdown) com propriedades de telemetria integradas, garantindo compatibilidade multiplataforma nativa (Delphi XE+ e Lazarus/FPC no Windows e Linux).

---

🟢 Funcionalidades Entregues

1. Injeção de Dependência Contextual (Request Scope)

• Propriedade Services em THorseRequest: Introduzido um container local Inversion of Control (IoC) thread-safe acoplado ao ciclo da requisição ativa.
• Modo Direto (Add) e Preguiçoso (AddFactory): Permite registrar instâncias físicas pertencentes ou delegates de fábrica (fábricas Lazy Loading) que só instanciam objetos quando requisitados via Resolve.
• Descarte 100% Automático: O container gerencia o tempo de vida (doOwnsValues := True) e descarta fisicamente todas as instâncias de serviços ao término do pipeline HTTP da requisição, prevenindo memory leaks sem exigir blocos manuais try..finally nas rotas.

2. Desligamento Suave (Graceful Shutdown)

• Interrupção Coordenada de Conexões: Permite que instâncias de servidores interrompam a escuta de novos sockets físicos imediatamente ao solicitar encerramento, mas aguardem as conexões concorrentes ativas concluírem suas respostas sob um tempo limite (timeout) de segurança.
• Propriedades de Observabilidade e Telemetria: Adicionadas as propriedades públicas estáticas de classe THorse.ActiveRequests (quantidade física de conexões concorrentes ativas) e THorse.IsShuttingDown (sinalizador lógico de readiness/liveness probes de Kubernetes ou Load Balancers).

---

🛠️ Modificações Realizadas

• src/Horse.Commons.pas: Declaração dos delegates de fábrica genéricos e clássicos THorseServiceFactory e THorseServiceFactory<T: class>.
• src/Horse.Core.Context.pas: Criação da unit gerenciadora do escopo de injeção THorseRequestContext utilizando dicionários genéricos e encapsulamento dinâmico de factories.
• src/Horse.Request.pas: Exposição da propriedade Services sob demanda e descarte determinístico nos métodos Clear (pool de requests) e Destroy.
• src/Horse.Core.pas e src/Horse.pas: Adicionada telemetria atômica e thread-safe de controle de concorrência com funções intrínsecas da CPU.
• src/Horse.Provider.Console.pas: Implementação do laço de encerramento cooperativo no provedor Indy.

---

🧪 Validação e Cobertura de Testes

Toda a implementação foi assegurada por testes rigorosos de integração multiplataforma compilando com sucesso e passando de forma limpa sob o detector de memory leaks ReportMemoryLeaksOnShutdown := True:

1. tests/src/tests/Tests.Integration.DependencyInjection.pas: Validação de injeção direta de instância, resolução de tipo, execução postergada de factories e descarte de RAM pós-requisicao.
2. tests/src/tests/Tests.Integration.GracefulShutdown.pas: Validação de escoamento ativo de requisições lentas em encerramentos assíncronos.
3. Matriz de Compilação Cruzada: Testes executados com 100% de aprovação em 24 combinações de compiladores (Delphi 10 Seattle até 13 Florence) e provedores de transporte (Default/Indy, Radix, HttpSys e IOCP).
4. Linux / FPC: Compatibilidade atestada no Linux compilando nativamente para formato ELF 64-bit via dcclinux64 e rodando sob os testes FPC Lazarus em containers Docker Ubuntu (tests/Dockerfile.tests-lazarus).

---

📚 Documentação e Exemplos

Adicionamos demonstrações didáticas de uso prático e documentações completas nos dois idiomas suportados:

• Documentação dedicada de IoC:
  • doc/dependency-injection.pt-BR.md (Português)
  • doc/dependency-injection.md (Inglês)
• Exemplos Console:
  • samples/delphi/console_dependency_injection/ConsoleDependencyInjection.dpr
  • samples/lazarus/console_dependency_injection/ConsoleDependencyInjection.lpr
• Atualização de Diretrizes locais para IAs: Atualizamos o AGENTS.md e incluímos as habilidades de IA em doc/skills/horse-dependency-injection/SKILL.md orientando novos robôs a adotarem as melhores práticas do request-scope.