http

Framework de manipulação HTTP

Importação

_ <- fat.http

Route

Uma rota é uma estrutura usada para mapear métodos HTTP para certos padrões de caminho, especificando qual código deve ser executado quando uma requisição é recebida. Cada rota pode definir um comportamento diferente para cada método HTTP (POST, GET, PUT, DELETE).

Construtor

cada método implementado recebe um HttpRequest como argumento e deve retornar um objeto HttpResponse

HttpRequest

Um HttpRequest representa uma mensagem de requisição HTTP. Isso é o que seu servidor recebe de um cliente quando ele faz uma requisição ao seu servidor.

Construtor

os items params e body podem ser omitidos dependendo da requisição recebida

HttpResponse

Um HttpResponse representa uma mensagem de resposta HTTP. Isso é o que um servidor envia de volta ao cliente em resposta a uma requisição HTTP.

para respostas em modo cliente, body será provido como Text se um tipo MIME textual for encontrado nos headers, caso contrário, será fornecido como Chunk

Construtor

Métodos

body: Any e wait: Number são sempre parâmetros opcionais, sendo que caso body não se enquadre como Text ou Chunk será automaticamente convertido para JSON no processo de envio e wait é o tempo máximo de espera e o padrão é 30.000ms (30 segundos)

verifySSL está habilitado por padrão para o modo cliente

setSSL pode não estar disponível, caso o sistema não tenha a biblioteca OpenSSL

Notas de uso

Modo cliente

Em HttpResponse.body, você pode precisar decodificar explicitamente uma resposta JSON para Scope usando o método fromJSON. Para postar um tipo nativo como JSON, você pode codificá-lo usando o método toJSON; no entanto, isso não é estritamente necessário, pois será feito implicitamente. Ambos os métodos estão disponíveis na biblioteca fat.recode.

Se os cabeçalhos não forem definidos, o cabeçalho Content-Type padrão para Chunk será application/octet-stream, para Text será text/plain; charset=UTF-8 e para outros tipos, será application/json; charset=UTF-8 (devido à conversão implícita).

Você pode definir cabeçalhos de solicitação personalizados da seguinte forma:

http <- fat.http

url = ...
token = ...
body = ...

http.setHeaders([
  "Accept: application/json; charset=UTF-8"
  "Content-Type: application/json; charset=UTF-8"
  "Authorization: Bearer " + token  # cabeçalhos personalizado
])

http.post(url, body)

definir cabeçalhos substituirá completamente a lista anterior pela nova lista

Ao realizar solicitações assíncronas, você pode precisar chamar setHeaders, setName e configurar verifySSL dentro de cada Worker, já que essas configurações são locais para cada thread.

Modo servidor

Lidando com respostas HTTP

O servidor FatScript lida automaticamente com os códigos de status HTTP comuns, como 200, 400, 404, 405, 408, 500 e 501. Sendo 200 o padrão ao construir um objeto HttpResponse.

Além dos códigos de status retornados de forma automática, você também pode retornar explicitamente outros códigos de status, como 201, 202, 203, 204, 205, 301, 401 e 403, especificando o código de status no objeto HttpResponse, por exemplo: HttpResponse(status = 401). Para todos os códigos mencionadas aqui, o servidor fornece corpos de resposta padrão em texto simples. No entanto, você tem a opção de substituir esses valores padrão e fornecer seus próprios corpos de resposta personalizados, quando necessário.

Ao lidar automaticamente com esses códigos de status e fornecer corpos de resposta padrão, o servidor FatScript simplifica o processo de desenvolvimento, ao mesmo tempo em que permite que você tenha controle sobre o conteúdo da resposta quando necessário.

não pertencendo a nenhum dos códigos anteriores, o servidor irá retornar o código 500

Veja um exemplo de um simples servidor HTTP de arquivos:

_ <- fat.std

# adapte para o local do conteúdo
directory = '/home/user/contentFolder'

# restrito a algumas extensões somente
mediaTypesByExtension = {
  htm = html = 'text/html'
  js = 'application/javascript'
  json = 'application/json'
  css = 'text/css'
  md = 'text/markdown'
  xml = 'application/xml'
  csv = 'text/csv'
  txt = 'text/plain'
  svg = 'image/svg+xml'
  rss = 'application/rss+xml'
  atom = 'application/atom+xml'
  png = 'image/png'
  jpg = jpeg = 'image/jpeg'
  gif = 'image/gif'
  ico = 'image/x-icon'
  webp = 'image/webp'
  woff = 'font/woff'
  woff2 = 'font/woff2'
}

routes: List/Route = [
  Route(
    '*'
    get = (request: HttpRequest): HttpResponse -> {
      path = file.resolve(directory + request.path)  # sanitized path
      type = path & path.startsWith(directory)       # jailed access
        ? mediaTypesByExtension(path.split('.')(-1))

      path.isEmpty => HttpResponse(status = 404)  # not found
      type.isEmpty => HttpResponse(status = 403)  # forbidden
      _            => HttpResponse(
        status = 200
        headers = [ 'Content-Type: {type}' ]
        body = file.readBin(path)
      )
    }
  )
]

http.listen(8080, routes, msMax = 3000)

use http.listen(0, routes) para iniciar um servidor com um número de porta atribuído automaticamente e verifique a porta efetiva atribuída ao servidor através do comando embutido $port

Segurança e Comportamento de Timeout

O servidor FatScript espera que os clientes enviem requisições completas (cabeçalhos e corpo) de forma rápida. Conexões que pausam no meio da requisição ou enviam dados lentamente podem ser encerradas antecipadamente por razões de desempenho e segurança. Esse comportamento é intencional e ajuda a proteger o servidor contra clientes lentos ou não responsivos que poderiam travá-lo completamente.

As fases de interação com o cliente são controladas por meio do parâmetro opcional msMax (padrão: 5000 ms), que pode ser definido na chamada de listen.

O timeout msMax se aplica de forma independente a diferentes etapas de cada requisição:

• Tempo permitido para que a requisição inicial chegue após a conexão ser aceita
• Tempo permitido para envio da resposta ao cliente
• Para requisições com Expect: 100-continue, um novo tempo de msMax é acrescentado após o envio do 100 Continue, aguardando o início do corpo da requisição

Cada uma dessas fases é protegida separadamente com o valor de msMax – elas não compartilham uma contagem regressiva global.

Importante:

• O tempo de processamento no servidor (ou seja, a execução do seu código FatScript) não é limitado por msMax e não conta para o timeout.
• Quando o servidor envia a resposta, a saída geralmente é armazenada em buffer pelo sistema operacional, então clientes lentos ao consumir a resposta não serão desconectados automaticamente por causa do msMax, a menos que o buffer se esgote.

O suporte HTTPS embutido é destinado a implantações leves, testes locais ou ambientes controlados. Para uso em produção, é altamente recomendado colocar o servidor FatScript atrás de um proxy reverso (como Nginx, Caddy ou HAProxy), que cuidará da terminação SSL, reforço de segurança e controle de concorrência.

Devido à sua arquitetura monothread e bloqueante, o servidor embutido não é recomendado para uploads de arquivos grandes, distribuição de downloads pesados ou cargas com alta concorrência.