feat: add MatchedRoute and State support for telemetry

[regyssilveira]

Suporte a telemetria

Descrição

Este Pull Request introduz o suporte básico de infraestrutura no Core do Horse para viabilizar a criação de middlewares de telemetria e observabilidade distribuída externos (como horse-opentelemetry ou horse-prometheus).

Seguindo os princípios KISS e de baixo acoplamento, o Core do Horse foi modificado estritamente com o mínimo necessário para suportar o rastreamento de rotas e a propagação de contextos de requisição de forma thread-safe, mantendo a compatibilidade do compilador do Delphi XE7 em diante e do Lazarus (FPC).

---

🛠️ Alterações no Core

1. THorseRequest (src/Horse.Request.pas)

• Adição da propriedade pública MatchedRoute: string: armazena o template da rota original cadastrado no roteador (ex: /usuarios/:id). Isso é essencial para que coletores de métricas agrupem requisições sem causar explosão de cardinalidade nos bancos de dados de séries temporais (como o Prometheus).
• Adição da propriedade pública State: TObjectDictionary<string, TObject>: um dicionário de estado genérico específico por requisição. Ele permite que middlewares injetem e compartilhem objetos (como contextos de Span/Trace) durante o ciclo de vida da chamada, de forma isolada por thread.
• Integração de ambas as propriedades nos construtores, destructor e no método Clear (reciclagem no pool de requisições). A flag [doOwnsValues] garante a liberação automática de objetos no dicionário de estados, prevenindo qualquer vazamento de memória.

2. Roteadores (src/Horse.Core.Router.Radix.pas e src/Horse.Core.RouterTree.pas)

• Modificação em ambos os roteadores (Radix e Clássico) para capturar o template original da rota no registro e preencher a propriedade MatchedRoute do THorseRequest assim que o casamento da rota é executado com sucesso.

---

🧪 Testes de Unidade Adicionados

Para garantir a estabilidade das alterações e evitar regressões:

• Tests.Horse.Request.Recycle.pas: Adicionado o teste TestRequestStateAndMatchedRouteCycle que valida a correta atribuição de MatchedRoute, o armazenamento de objetos em State e a destruição/limpeza automática dos mesmos ao reciclar a requisição no pool.
• Tests.Horse.Core.Router.Radix.pas e Tests.Horse.Core.RouterTree.pas: Atualizado o teste de rotas parametrizadas para validar que o Req.MatchedRoute retorna o template original /users/:id.

---

🚀 Validação e Performance

• Compilação e Testes (Delphi): A suíte de testes passou com 100% de sucesso em múltiplos compiladores (Delphi 10 Seattle, 11 Alexandria, 12 Athens e 13 Florence) e sob vários provedores de transporte HTTP (Default, Default+Radix, HttpSys, IOCP).
• Compilação (Lazarus/FPC): Compilação validada com sucesso via compilador local FPC 3.2.2.
• Impacto em Performance: A atribuição de MatchedRoute opera apenas sobre referências de strings (custo quase nulo), e o dicionário State vazia consome apenas ciclos insignificantes de CPU durante a reciclagem, não impactando a performance de requisições que não utilizam telemetria.