README

horse-schema-validation

Middleware de validação de esquemas de dados de entrada (JSON/Payload) para o framework Horse.

Ele intercepta as requisições HTTP antes de chegarem aos controladores principais, validando a estrutura do corpo da requisição (Req.Body) contra um esquema predefinido no padrão JSON Schema. Se a validação falhar, ele interrompe imediatamente o ciclo de vida da requisição levantando a exceção oficial do framework (EHorseCallbackInterrupted), respondendo com status 400 Bad Request e detalhando cada um dos erros encontrados.

⚙️ Instalação

A instalação deve ser feita utilizando o gerenciador de pacotes boss4d:

boss install horse-schema-validation

⚡️ Ciclo de Vida da Requisição

• Fase recomendada: preValidation ou preParsing.
• Comportamento: Interceptador puro. Caso o payload seja inválido, a execução é abortada gerando status 400 Bad Request com cabeçalho Content-Type: application/json contendo a lista das violações.

📐 Diretivas JSON Schema Suportadas

O validador nativo recursivo oferece suporte para as principais regras da especificação JSON Schema (Draft 4/7):

• Validação de Tipos (type): string, number, integer, boolean, object, array, null.
• Objetos:
  • properties (validação recursiva das chaves de um objeto).
  • required (definição de chaves obrigatórias).
• Strings:
  • minLength / maxLength (comprimento de caracteres).
  • pattern (validação por Expressão Regular).
  • format (validação dedicada a formato de "email").
• Números:
  • minimum / maximum (limites de intervalo numérico).
• Arrays:
  • items (validação recursiva do esquema de cada elemento do array).

📖 Exemplo Prático (Delphi)

uses
  System.SysUtils,
  Horse,
  Horse.SchemaValidation;

const
  USER_SCHEMA =
    '{' +
    '  "type": "object",' +
    '  "properties": {' +
    '    "name": {' +
    '      "type": "string",' +
    '      "minLength": 3,' +
    '      "maxLength": 50' +
    '    },' +
    '    "age": {' +
    '      "type": "integer",' +
    '      "minimum": 18' +
    '    },' +
    '    "email": {' +
    '      "type": "string",' +
    '      "format": "email"' +
    '    }' +
    '  },' +
    '  "required": ["name", "email"]' +
    '}';

begin
  // Adiciona a validação de esquema na rota específica via string JSON ou TJSONObject
  THorse.Use('/users', SchemaValidation(USER_SCHEMA));
  
  THorse.Post('/users',
    procedure(Req: THorseRequest; Res: THorseResponse)
    begin
      Res.Send('Usuário criado com sucesso!').Status(201);
    end);

  THorse.Listen(9000);
end.

🗂️ Estrutura de Retorno em Falhas de Validação (400 Bad Request)

Quando o payload enviado não obedece ao esquema, a resposta da requisição é enviada no formato abaixo contendo o caminho do campo e a mensagem detalhada:

{
  "error": "Erro de validação de esquema",
  "errors": [
    {
      "field": "name",
      "message": "O campo deve conter no mínimo 3 caracteres"
    },
    {
      "field": "age",
      "message": "O valor deve ser maior ou igual a 18"
    },
    {
      "field": "email",
      "message": "O formato do e-mail é inválido"
    }
  ]
}

🧪 Testes Automatizados

O projeto conta com testes unitários e de integração desenvolvidos com DUnitX e RESTRequest4Delphi na pasta tests/. Para rodar os testes execute a partir da linha de comando:

cd tests
boss install
dcc32.exe -E. -I..\src;modules\horse\src;modules\RESTRequest4Delphi\src -U..\src;modules\horse\src;modules\RESTRequest4Delphi\src;"C:\Program Files (x86)\Embarcadero\Studio\23.0\lib\win32\release" -NSSystem;Winapi Tests.dpr
.\Tests.exe

📄 Licença

Este projeto está licenciado sob a Apache License 2.0.