Endpoints HTTP

Uma entrada http.endpoint associa um método e um caminho HTTP a uma função handler Lua.

Classificação: referência de configuração e API. Os blocos YAML são fragmentos do registro que pressupõem a existência das entradas de servidor, roteador, middleware, função e políticas de segurança referenciadas. Os blocos Lua se concentram nos contratos do handler e identificam explicitamente as chamadas pertencentes à aplicação.

Definição

- name: get_user
  kind: http.endpoint
  meta:
    router: app:api_router
  method: GET
  path: /users/{id}
  func: app.users:get_user

Configuração

Métodos HTTP

Métodos compatíveis:

Nomes de métodos são em maiúsculas; method é obrigatório, e qualquer valor fora desse conjunto é rejeitado como erro de configuração.

Endpoints Agnósticos de Método

method: "*" registra o caminho para todos os métodos HTTP, e o handler lê o método real com req:method():

- name: proxy
  kind: http.endpoint
  method: "*"
  path: /proxy/{path...}
  func: proxy_handler

Para um endpoint normal, o roteador também registra um handler OPTIONS no mesmo caminho, para que o middleware de CORS possa responder a um preflight sem executar o endpoint. Um endpoint * não recebe esse handler: ele já corresponde a OPTIONS. O middleware do roteador ainda o envolve, então um middleware de CORS configurado responde a um preflight permitido com 204 antes de o endpoint executar; qualquer outra requisição OPTIONS chega à própria função do endpoint, que deve respondê-la.

Parâmetros de caminho

Use a sintaxe {param} para parâmetros de URL:

- name: get_user
  kind: http.endpoint
  meta:
    router: api
  method: GET
  path: /users/{id}
  func: get_user

- name: get_user_post
  kind: http.endpoint
  meta:
    router: api
  method: GET
  path: /users/{user_id}/posts/{post_id}
  func: get_user_post

Acesse-os no handler:

local http = require("http")

local function handler()
    local req, req_err = http.request()
    if req_err then return nil, req_err end
    local user_id, user_err = req:param("user_id")
    if user_err then return nil, user_err end
    local post_id, post_err = req:param("post_id")
    if post_err then return nil, post_err end
    return {user_id = user_id, post_id = post_id}
end

Caminhos curinga

Use {path...} para corresponder a todos os segmentos de caminho restantes:

- name: file_handler
  kind: http.endpoint
  method: GET
  path: /files/{path...}
  func: serve_file

Esse segmento catch-all faz a rota corresponder a requisições como /files/docs/readme.md. A cauda capturada é lida como qualquer outro parâmetro, sob o nome sem os pontos finais:

local req = http.request()
local tail = req:param("path")  -- "docs/readme.md"

Função handler

As funções de endpoint obtêm os objetos de requisição e resposta pelo módulo http:

local http = require("http")
local funcs = require("funcs")

local function handler()
    local req, req_err = http.request()
    if req_err then return nil, req_err end
    local res, res_err = http.response()
    if res_err then return nil, res_err end

    local user_id, param_err = req:param("id")
    if param_err then return nil, param_err end

    local user, call_err = funcs.call("app.users:get_user", user_id)
    if call_err then return nil, call_err end

    local type_err = res:set_content_type(http.CONTENT.JSON)
    if type_err then return nil, type_err end
    local status_err = res:set_status(http.STATUS.OK)
    if status_err then return nil, status_err end
    local write_err = res:write_json(user)
    if write_err then return nil, write_err end
    return true
end

return { handler = handler }

Objeto Request

Objeto Response

Padrão de API JSON

Um handler de API JSON pode analisar o corpo da requisição, rejeitar entradas inválidas e escrever um resultado JSON:

local http = require("http")
local funcs = require("funcs")

local function handler()
    local req, req_err = http.request()
    if req_err then return nil, req_err end
    local res, res_err = http.response()
    if res_err then return nil, res_err end

    local data, err = req:body_json()
    if err then
        local status_err = res:set_status(http.STATUS.BAD_REQUEST)
        if status_err then return nil, status_err end
        local write_err = res:write_json({error = "Invalid JSON"})
        if write_err then return nil, write_err end
        return true
    end

    local result, process_err = funcs.call("app.api:process_request", data)
    if process_err then return nil, process_err end

    local status_err = res:set_status(http.STATUS.OK)
    if status_err then return nil, status_err end
    local write_err = res:write_json(result)
    if write_err then return nil, write_err end
    return true
end

return { handler = handler }

Respostas de erro

local http = require("http")
local funcs = require("funcs")

local function api_error(res, status, code, message)
    local status_err = res:set_status(status)
    if status_err then return nil, status_err end
    local write_err = res:write_json({
        error = {
            code = code,
            message = message
        }
    })
    if write_err then return nil, write_err end
    return true
end

local function handler()
    local req, req_err = http.request()
    if req_err then return nil, req_err end
    local res, res_err = http.response()
    if res_err then return nil, res_err end

    local user_id, param_err = req:param("id")
    if param_err then return nil, param_err end
    local user, err = funcs.call("app.users:get_user", user_id)

    if err then
        if errors.is(err, errors.NOT_FOUND) then
            return api_error(res, http.STATUS.NOT_FOUND, "USER_NOT_FOUND", "User not found")
        end
        return api_error(res, http.STATUS.INTERNAL_ERROR, "INTERNAL_ERROR", "Server error")
    end

    local status_err = res:set_status(http.STATUS.OK)
    if status_err then return nil, status_err end
    local write_err = res:write_json(user)
    if write_err then return nil, write_err end
    return true
end

return { handler = handler }

Exemplos

Endpoints CRUD

entries:
  - name: users_router
    kind: http.router
    meta:
      server: gateway
    prefix: /api/users
    middleware:
      - cors
      - compress

  - name: list_users
    kind: http.endpoint
    meta:
      router: users_router
    method: GET
    path: /
    func: app.users:list

  - name: get_user
    kind: http.endpoint
    meta:
      router: users_router
    method: GET
    path: /{id}
    func: app.users:get

  - name: create_user
    kind: http.endpoint
    meta:
      router: users_router
    method: POST
    path: /
    func: app.users:create

  - name: update_user
    kind: http.endpoint
    meta:
      router: users_router
    method: PUT
    path: /{id}
    func: app.users:update

  - name: delete_user
    kind: http.endpoint
    meta:
      router: users_router
    method: DELETE
    path: /{id}
    func: app.users:delete

Endpoint protegido

O middleware de autorização é configurado no roteador pai, não no endpoint. O middleware de pós-match, como endpoint_firewall, é executado depois da correspondência da rota e se aplica a todos os endpoints sob o roteador:

O middleware de autorização é configurado no roteador pai, não no endpoint. Middleware pós-match (como endpoint_firewall) executa após o match de rota e se aplica a todos os endpoints sob o roteador:

- name: admin_router
  kind: http.router
  meta:
    server: gateway
  prefix: /admin
  middleware:
    - cors
    - token_auth
  post_middleware:
    - endpoint_firewall
  post_options:
    endpoint_firewall.action: "admin"

- name: admin_endpoint
  kind: http.endpoint
  meta:
    router: admin_router
  method: POST
  path: /settings
  func: app.admin:update_settings

Veja também

• Roteador - Agrupamento de rotas
• Módulo HTTP - API de requisição e resposta
• Middleware - Processamento de requisições