horse-websocket

Horse WebSocket Coding Skill

This skill provides guidelines and patterns for developers and AI agents implementing, debugging, or maintaining WebSocket endpoints in the Horse framework.

🟢 Request Upgrade Pattern

To upgrade an HTTP request to a WebSocket connection, always call Res.UpgradeToWebSocket(AOnConnectCallback) inside the route handler.

Delphi Syntax (Anonymous Procedure / Closure)

THorse.Get('/ws',
  procedure(Req: THorseRequest; Res: THorseResponse)
  begin
    Res.UpgradeToWebSocket(
      procedure(const AConn: IHorseWebSocketConnection)
      begin
        AConn.OnMessage := procedure(const AConnection: IHorseWebSocketConnection; const AText: string)
        begin
          AConnection.SendText('Received: ' + AText);
        end;
      end);
  end);

Lazarus/FPC Syntax (Object Methods)

Always use regular object methods or class procedures for callbacks in Lazarus/FPC to ensure compatibility:

type
  TWebSocketController = class
  public
    class procedure HandleWS(Req: THorseRequest; Res: THorseResponse);
    class procedure OnConnect(const AConn: IHorseWebSocketConnection);
    class procedure OnMessage(const AConnection: IHorseWebSocketConnection; const AText: string);
  end;

class procedure TWebSocketController.HandleWS(Req: THorseRequest; Res: THorseResponse);
begin
  Res.UpgradeToWebSocket(OnConnect);
end;

class procedure TWebSocketController.OnConnect(const AConn: IHorseWebSocketConnection);
begin
  AConn.OnMessage := OnMessage;
end;

class procedure TWebSocketController.OnMessage(const AConnection: IHorseWebSocketConnection; const AText: string);
begin
  AConnection.SendText('Received: ' + AText);
end;

🟢 Broadcasts and Session Management

Use THorseWebSocketManager for thread-safe operations across multiple connections.

• Broadcast to all: THorseWebSocketManager.Broadcast('/ws', 'Hello all!');
• Broadcast excluding sender: THorseWebSocketManager.Broadcast('/ws', 'Hello others!', AConnection);