Quem desenvolve APIs robustas e de alta performance no Delphi utilizando o framework Horse sabe que a velocidade e a simplicidade sempre foram os pilares do projeto. No entanto, à medida que os sistemas crescem e migram para arquiteturas de microsserviços baseadas em contêineres e Kubernetes, duas necessidades tornam-se críticas: observabilidade em tempo real (APM) e a capacidade de rodar múltiplos servidores isolados no mesmo processo (Multi-Instance) de forma segura.

Neste artigo, vamos explorar a nova feature do ecossistema do Horse: a introdução de Lifecycle Hooks do Servidor, Hooks Nativos de Telemetria e o suporte completo a Lifecycle de Múltiplas Instâncias Isoladas.

O que mudou na Arquitetura do Horse?

Anteriormente, o Horse operava fortemente acoplado a variáveis globais de estado (Singletons). Ao estender o framework ou plugar ferramentas de APM (como Prometheus, OpenTelemetry ou Datadog), os desenvolvedores precisavam implementar middlewares customizados que geravam overhead no heap devido à constante alocação e desalocação de objetos em cada requisição HTTP.

A nova atualização resolve isso introduzindo infraestrutura nativa diretamente no núcleo do Horse:

• Isolamento Multi-Instance real: Cada instância de THorseInstance agora controla independentemente o seu ciclo de vida físico e lógico, permitindo criar servidores paralelos em portas diferentes sem compartilhamento de estado colateral.
• Lifecycle Hooks do Servidor: Hooks como BeforeListen, AfterListen, BeforeStop e AfterStop agora são executados de forma estruturada nas instâncias lógicas e físicas.
• Hooks de Telemetria de Alta Precisão: O novo hook AddOnTelemetry utiliza TStopwatch interno baseado em contadores de performance do hardware para rastrear o tempo exato de execução da rota com overhead de nanossegundos.

Quais são os Ganhos Reais para a sua Aplicação?

1. Observabilidade Segura e sem Overhead

Diferente de middlewares comuns, o gancho de telemetria é executado fora do pipeline tradicional de rotas HTTP, direto no encerramento lógico da requisição. Todos os callbacks registrados em AddOnTelemetry são isolados internamente por blocos try-except automáticos. Isso garante que, se o seu coletor de APM falhar ou ficar indisponível, a requisição do cliente nunca será afetada e o servidor continuará respondendo normalmente.

2. Resiliência no Startup

Se qualquer inicialização crítica falhar no gancho BeforeListen (como uma conexão obrigatória com o banco de dados que caiu), a exceção é propagada corretamente para o escopo chamador e o estado de Running da instância é limpo imediatamente. Isso impede servidores “zumbis” de continuarem ativos sem estarem escutando conexões físicas.

3. Thread-Safety em Servidores Concorrentes

Middlewares e monitoramentos agora podem rodar de forma isolada em instâncias dedicadas. Por exemplo, você pode expor uma instância do Horse na porta 9000 para sua API principal de negócios e outra na porta 9001 apenas para expor métricas do Prometheus e Health Checks (probes do Kubernetes), eliminando o risco de colisão de contexto.

Middlewares de Telemetria: A Outra Opção do Ecossistema

Além de registrar callbacks personalizados diretamente via ganchos nativos no código da sua aplicação, você pode optar por utilizar **Middlewares de Telemetria** pré-construídos do ecossistema do Horse. Esta é a abordagem ideal se você deseja soluções prontas para plug-and-play:

• Middlewares de Log (ex: Logger / OctetStream): Permitem interceptar e registrar o tráfego HTTP de forma padronizada.
• Coletores de Métricas (ex: Prometheus): Middlewares dedicados que acumulam estatísticas de latência e contagem de requisições por rota, expondo-as de forma nativa para que o Prometheus raspe (scrape) os dados periodicamente.

A grande vantagem da nova arquitetura: Mesmo quando você escolhe utilizar middlewares estruturados de terceiros, eles agora podem ser refatorados internamente para consumir o barramento nativo do AddOnTelemetry. Isso significa que esses plug-ins ganham automaticamente o benefício de thread-safety por instância, cálculo preciso de latência via TStopwatch e isolamento completo de exceções, sem que você precise reescrever uma única linha da lógica de negócios da sua API.

Como Usar: Exemplo Prático com Multi-Instance e Telemetria

Veja como é simples criar duas instâncias paralelas do Horse, registrar hooks de ciclo de vida e monitorar a telemetria das rotas com precisão:

program ConsoleTelemetry;

{$APPTYPE CONSOLE}

uses
  System.SysUtils,
  Horse;

var
  LInstanceAPI: THorseInstance;
  LInstanceMetrics: THorseInstance;

begin
  // -------------------------------------------------------------
  // Instância 1: API de Negócios (Porta 9000)
  // -------------------------------------------------------------
  LInstanceAPI := THorseInstance.Create;
  try
    // Registro de ganchos de ciclo de vida do servidor
    LInstanceAPI.AddOnBeforeListen(
      procedure(const AInstance: THorseInstance)
      begin
        Writeln('API: Estabelecendo conexões com o banco antes de escutar...');
      end);

    LInstanceAPI.AddOnAfterListen(
      procedure(const AInstance: THorseInstance)
      begin
        Writeln('API: Escutando na porta ' + AInstance.Port.ToString);
      end);

    // Registro de Telemetria nativa (segura e protegida de falhas)
    LInstanceAPI.AddOnTelemetry(
      procedure(const AReq: THorseRequest; const ARes: THorseResponse; const AExecutionTimeMS: Double)
      begin
        Writeln(Format('[TELEMETRIA API] Rota: %s | Status: %d | Latência: %.2fms',
          [AReq.PathInfo, ARes.Status, AExecutionTimeMS]));
      end);

    // Rota simples de negócios
    LInstanceAPI.Get('/ping',
      procedure(Req: THorseRequest; Res: THorseResponse; Next: TNextProc)
      begin
        Res.Send('pong');
      end);

    // Inicialização assíncrona da API de Negócios
    LInstanceAPI.Listen(9000);

    // -------------------------------------------------------------
    // Instância 2: API de Métricas / Health (Porta 9001)
    // -------------------------------------------------------------
    LInstanceMetrics := THorseInstance.Create;
    try
      LInstanceMetrics.AddOnAfterListen(
        procedure(const AInstance: THorseInstance)
        begin
          Writeln('MÉTRICAS: Servidor de observabilidade ativo na porta ' + AInstance.Port.ToString);
        end);

      // Health Check do microsserviço informando se está em Graceful Shutdown
      LInstanceMetrics.Get('/health',
        procedure(Req: THorseRequest; Res: THorseResponse; Next: TNextProc)
        begin
          if THorse.IsShuttingDown then
            Res.Send('Terminating').Status(THTTPStatus.ServiceUnavailable)
          else
            Res.Send('Healthy');
        end);

      // Inicialização síncrona da API de Métricas (mantém o console ativo)
      LInstanceMetrics.Listen(9001,
        procedure
        begin
          Writeln('Pressione ENTER para encerrar os servidores...');
        end);

      Readln;

    finally
      // Desligamento coordenado (Graceful Shutdown)
      LInstanceMetrics.StopListenGraceful(3000);
      LInstanceMetrics.Free;
    end;

  finally
    LInstanceAPI.StopListenGraceful(3000);
    LInstanceAPI.Free;
  end;
end.

Conclusão

A introdução de hooks nativos de ciclo de vida e telemetria eleva a maturidade do Delphi Horse a patamares corporativos. Ao remover o overhead no gerenciamento do tempo das conexões e garantir total isolamento de estado por instância, o Horse consolida-se como a escolha ideal para o desenvolvimento de microsserviços modernos, prontos para produção e facilmente monitoráveis.

As novas features já estão disponíveis a partir do branch de desenvolvimento principal do projeto. Não deixe de atualizar seu repositório local e testar essa evolução arquitetural em seus sistemas!