Feature/route level middlewares

[regyssilveira]

Pull Request: Feat/Route-level Middleware Chains & Documentation Refactoring

📋 Descrição

Este Pull Request introduz o suporte nativo a Cadeias de Middlewares por Rota (Route-level Middleware Chains) de forma declarativa e 100% retrocompatível. Além disso, reestrutura e atualiza toda a documentação técnica e Habilidades de IA (Agent Skills) do framework.

---

🛠️ Alterações Realizadas

1. Core e Roteador (Cadeias de Middlewares por Rota)

• THorseCore: Adicionado o método RegisterRouteMiddleware e novas sobrecargas para todos os verbos HTTP (All, Get, Post, Put, Delete, Patch, Head, Query) aceitando a cadeia de middlewares.
• Open Array (array of THorseCallback): Implementado no lugar de TArray<T> para permitir a compilação perfeita com inicializadores literais de colchetes [...] em compiladores antigos (como Delphi 10 Seattle e 11 Alexandria).
• Roteador Fluente e Grupos: Interfaces IHorseCoreRoute<T>, THorseCoreRoute<T> e THorseCoreGroupRoute<T> sincronizadas para refletir o parâmetro array of THorseCallback preservando o encadeamento e isolamento de grupos.

2. Projeto de Exemplo (Samples)

• Criado o projeto de console ConsoleRouteMiddlewares localizado em samples/delphi/console_route_middlewares/ demonstrando o uso estático, fluente e em grupos do novo recurso.
• Projeto integrado no arquivo de grupo de projetos global samples/delphi/Samples.groupproj.

3. Reestruturação e Enriquecimento da Documentação

• Diagrama Mermaid: Adicionado diagrama de pipeline e precedência de requisição (Global ➔ Grupo ➔ Rota ➔ Handler) no índice global (doc/index.md e doc/index.pt-BR.md).
• Roteamento (routing.md): Documentação do novo recurso de middlewares específicos de rotas com exemplos práticos.
• Request & Response (request-response.md): Inclusão de seções avançadas sobre Chunked Transfer Encoding e boas práticas de consumo de memória para grandes uploads/downloads.
• Tuning de Kernel (epoll.md): Documentada a configuração de parâmetros de kernel (sysctl.conf) recomendada em produção para o reactor epoll sob tráfego massivo.
• IA Agent Skills: Atualizadas as habilidades de IA (doc/skills/horse-routing/SKILL.md e doc/skills/horse-middlewares/SKILL.md) com as novas diretrizes do fluxo em cebola.

---

🧪 Testes de Validação Executados

1. Suíte de Testes no Windows (DUnitX / Console)

Testamos todas as combinações de provedores em 4 compiladores com 100% de aprovação:

• Delphi 10 Seattle: SUCESSO (Todos os testes passaram)
• Delphi 11 Alexandria: SUCESSO (Todos os testes passaram)
• Delphi 12 Athens: SUCESSO (Todos os testes passaram)
• Delphi 13 Florence: SUCESSO (Todos os testes passaram)

2. Testes de Integração no Linux (Docker / Lazarus FPC)

• Validação sob o reactor epoll do Linux: SUCESSO
• Resultado: INTEGRATION TEST: SUCCESS (ALL MIDDLEWARES)