serverest 3.2.2 → 3.3.0-beta.1

package/README.md

@@ -124,6 +124,48 @@ Em ambos os comandos de subida de ambiente local será utilizado a última vers
 
 Você pode encontrar as versões disponíveis na [lista de tags no Docker Hub](https://hub.docker.com/r/paulogoncalvesbh/serverest/tags) e na [lista de versões do NPM](https://www.npmjs.com/package/serverest).
 
+## Etapas da requisição
+
+Toda resposta das rotas `/login`, `/usuarios`, `/produtos` e `/carrinhos` informa por quais etapas do servidor a requisição passou, quanto tempo cada uma levou e qual delas interrompeu a requisição. Assim é possível entender, sem ler o código, por que a resposta foi 401 e não 400 quando o token e o body estão errados ao mesmo tempo.
+
+| Cabeçalho | Conteúdo |
+|---|---|
+| `X-ServeRest-Stages` | Todas as etapas da rota, em ordem de execução, com status, duração e detalhes |
+
+O cabeçalho é listado em `Access-Control-Expose-Headers`. Requisições `OPTIONS` (preflight de CORS) e as demais rotas (`/`, `/version`, `/swagger.json`) não possuem esse cabeçalho.
+
+Exemplo de 401 sem token em `POST /carrinhos`:
+
+```
+X-ServeRest-Stages: body;st=ok;dur=0.21, rate_limit;st=skipped, auth;st=failed;dur=0.05;reason=token_missing, schema;st=not_run, rules;st=not_run, write;st=not_run
+```
+
+Cada entrada é um nome seguido de parâmetros `;chave=valor`, separadas por vírgula. Nome e valores usam apenas letras, números, `_` e `.`.
+
+| Parâmetro | Valores | Presente quando |
+|---|---|---|
+| `st` | `ok`, `failed`, `skipped`, `not_run` | Sempre |
+| `dur` | Milissegundos com duas casas decimais | A etapa executou (`ok` ou `failed`) |
+| `reason` | `token_missing`, `bad_format`, `token_expired`, `token_invalid`, `user_not_found`, `not_admin` | A etapa `auth` falhou |
+| `item` | Índice, a partir de zero, do item em `produtos` | Uma regra falhou em um item específico |
+
+| Status | Significado |
+|---|---|
+| `ok` | Executou e deixou a requisição continuar |
+| `failed` | Executou e interrompeu a requisição. No máximo uma etapa e uma regra por resposta |
+| `skipped` | Não se aplica neste ambiente (rate limit ao executar localmente) |
+| `not_run` | Não executou porque uma etapa anterior interrompeu a requisição |
+
+As etapas são `body`, `rate_limit`, `auth`, `schema`, `read` (rotas GET), `rules` (regras de negócio e, enquanto a rota não for detalhada, também a gravação) e `write` (gravação, hoje apenas em `POST /carrinhos`). Entradas no formato `<etapa>.<regra>`, como `rules.enough_stock`, são regras da etapa citada antes do ponto: vêm logo depois dela e nunca possuem `dur`.
+
+Casos que merecem atenção:
+
+- Status 400 ou maior sem nenhuma etapa `failed` significa que a resposta veio de fora das etapas: rota inexistente (405) ou URL malformada (400).
+- Em um timeout (408) a etapa que estava executando quando o tempo acabou é a marcada como `failed`.
+- Em `POST /carrinhos` as regras `rules.product_exists` e `rules.enough_stock` são avaliadas item a item, na ordem do array, e param no primeiro item que falha. Portanto `rules.product_exists;st=ok` ao lado de `rules.enough_stock;st=failed;item=1` significa "nenhum produto inexistente até o item que falhou", e não "todos os produtos existem".
+
+Evolução: versões futuras apenas adicionam entradas, como uma etapa `write` depois de `rules` ou entradas `rules.<regra>` em mais rotas. A gramática, os nomes dos parâmetros, os valores de status e os nomes das etapas acima são estáveis; renomear ou remover algum deles é uma quebra de compatibilidade.
+
 ## Teste de carga
 
 ### IMPORTANTE

package/docs/swagger.json

@@ -52,6 +52,11 @@
                 "responses": {
                     "200": {
                         "description": "paths.login.post.responses.200.description",
+                        "headers": {
+                            "X-ServeRest-Stages": {
+                                "$ref": "#/components/headers/XServeRestStages"
+                            }
+                        },
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -62,6 +67,11 @@
                     },
                     "401": {
                         "description": "paths.login.post.responses.401.description",
+                        "headers": {
+                            "X-ServeRest-Stages": {
+                                "$ref": "#/components/headers/XServeRestStages"
+                            }
+                        },
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -99,6 +109,11 @@
                 "responses": {
                     "200": {
                         "description": "paths.usuarios.get.responses.200.description",
+                        "headers": {
+                            "X-ServeRest-Stages": {
+                                "$ref": "#/components/headers/XServeRestStages"
+                            }
+                        },
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -121,6 +136,11 @@
                 "responses": {
                     "201": {
                         "description": "paths.usuarios.post.responses.201.description",
+                        "headers": {
+                            "X-ServeRest-Stages": {
+                                "$ref": "#/components/headers/XServeRestStages"
+                            }
+                        },
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -156,6 +176,11 @@
                 "responses": {
                     "200": {
                         "description": "paths.usuariosById.get.responses.200.description",
+                        "headers": {
+                            "X-ServeRest-Stages": {
+                                "$ref": "#/components/headers/XServeRestStages"
+                            }
+                        },
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -166,6 +191,11 @@
                     },
                     "400": {
                         "description": "paths.usuariosById.get.responses.400.description",
+                        "headers": {
+                            "X-ServeRest-Stages": {
+                                "$ref": "#/components/headers/XServeRestStages"
+                            }
+                        },
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -203,6 +233,11 @@
                 "responses": {
                     "200": {
                         "description": "paths.usuariosById.delete.responses.200.description",
+                        "headers": {
+                            "X-ServeRest-Stages": {
+                                "$ref": "#/components/headers/XServeRestStages"
+                            }
+                        },
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -219,6 +254,11 @@
                     },
                     "400": {
                         "description": "paths.usuariosById.delete.responses.400.description",
+                        "headers": {
+                            "X-ServeRest-Stages": {
+                                "$ref": "#/components/headers/XServeRestStages"
+                            }
+                        },
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -253,6 +293,11 @@
                 "responses": {
                     "200": {
                         "description": "paths.usuariosById.put.responses.200.description",
+                        "headers": {
+                            "X-ServeRest-Stages": {
+                                "$ref": "#/components/headers/XServeRestStages"
+                            }
+                        },
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -263,6 +308,11 @@
                     },
                     "201": {
                         "description": "paths.usuariosById.put.responses.201.description",
+                        "headers": {
+                            "X-ServeRest-Stages": {
+                                "$ref": "#/components/headers/XServeRestStages"
+                            }
+                        },
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -303,6 +353,11 @@
                 "responses": {
                     "200": {
                         "description": "paths.produtos.get.responses.200.description",
+                        "headers": {
+                            "X-ServeRest-Stages": {
+                                "$ref": "#/components/headers/XServeRestStages"
+                            }
+                        },
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -330,6 +385,11 @@
                 "responses": {
                     "201": {
                         "description": "paths.produtos.post.responses.201.description",
+                        "headers": {
+                            "X-ServeRest-Stages": {
+                                "$ref": "#/components/headers/XServeRestStages"
+                            }
+                        },
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -371,6 +431,11 @@
                 "responses": {
                     "200": {
                         "description": "paths.produtosById.get.responses.200.description",
+                        "headers": {
+                            "X-ServeRest-Stages": {
+                                "$ref": "#/components/headers/XServeRestStages"
+                            }
+                        },
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -381,6 +446,11 @@
                     },
                     "400": {
                         "description": "paths.produtosById.get.responses.400.description",
+                        "headers": {
+                            "X-ServeRest-Stages": {
+                                "$ref": "#/components/headers/XServeRestStages"
+                            }
+                        },
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -423,6 +493,11 @@
                 "responses": {
                     "200": {
                         "description": "paths.produtosById.delete.responses.200.description",
+                        "headers": {
+                            "X-ServeRest-Stages": {
+                                "$ref": "#/components/headers/XServeRestStages"
+                            }
+                        },
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -439,6 +514,11 @@
                     },
                     "400": {
                         "description": "paths.produtosById.delete.responses.400.description",
+                        "headers": {
+                            "X-ServeRest-Stages": {
+                                "$ref": "#/components/headers/XServeRestStages"
+                            }
+                        },
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -484,6 +564,11 @@
                 "responses": {
                     "200": {
                         "description": "paths.produtosById.put.responses.200.description",
+                        "headers": {
+                            "X-ServeRest-Stages": {
+                                "$ref": "#/components/headers/XServeRestStages"
+                            }
+                        },
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -494,6 +579,11 @@
                     },
                     "201": {
                         "description": "paths.produtosById.put.responses.201.description",
+                        "headers": {
+                            "X-ServeRest-Stages": {
+                                "$ref": "#/components/headers/XServeRestStages"
+                            }
+                        },
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -538,6 +628,11 @@
                 "responses": {
                     "200": {
                         "description": "paths.carrinhos.get.responses.200.description",
+                        "headers": {
+                            "X-ServeRest-Stages": {
+                                "$ref": "#/components/headers/XServeRestStages"
+                            }
+                        },
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -565,6 +660,11 @@
                 "responses": {
                     "201": {
                         "description": "paths.carrinhos.post.responses.201.description",
+                        "headers": {
+                            "X-ServeRest-Stages": {
+                                "$ref": "#/components/headers/XServeRestStages"
+                            }
+                        },
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -575,6 +675,11 @@
                     },
                     "400": {
                         "description": "paths.carrinhos.post.responses.400.description",
+                        "headers": {
+                            "X-ServeRest-Stages": {
+                                "$ref": "#/components/headers/XServeRestStages"
+                            }
+                        },
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -616,6 +721,11 @@
                 "responses": {
                     "200": {
                         "description": "paths.carrinhosById.get.responses.200.description",
+                        "headers": {
+                            "X-ServeRest-Stages": {
+                                "$ref": "#/components/headers/XServeRestStages"
+                            }
+                        },
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -626,6 +736,11 @@
                     },
                     "400": {
                         "description": "paths.carrinhosById.get.responses.400.description",
+                        "headers": {
+                            "X-ServeRest-Stages": {
+                                "$ref": "#/components/headers/XServeRestStages"
+                            }
+                        },
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -658,6 +773,11 @@
                 "responses": {
                     "200": {
                         "description": "paths.carrinhosConcluirCompra.delete.responses.200.description",
+                        "headers": {
+                            "X-ServeRest-Stages": {
+                                "$ref": "#/components/headers/XServeRestStages"
+                            }
+                        },
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -693,6 +813,11 @@
                 "responses": {
                     "200": {
                         "description": "paths.carrinhosCancelarCompra.delete.responses.200.description",
+                        "headers": {
+                            "X-ServeRest-Stages": {
+                                "$ref": "#/components/headers/XServeRestStages"
+                            }
+                        },
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -894,6 +1019,11 @@
         "responses": {
             "EmailJaUtilizado": {
                 "description": "components.responses.EmailJaUtilizado.description",
+                "headers": {
+                    "X-ServeRest-Stages": {
+                        "$ref": "#/components/headers/XServeRestStages"
+                    }
+                },
                 "content": {
                     "application/json": {
                         "schema": {
@@ -904,6 +1034,11 @@
             },
             "ProdutoNomeDuplicado": {
                 "description": "components.responses.ProdutoNomeDuplicado.description",
+                "headers": {
+                    "X-ServeRest-Stages": {
+                        "$ref": "#/components/headers/XServeRestStages"
+                    }
+                },
                 "content": {
                     "application/json": {
                         "schema": {
@@ -914,6 +1049,11 @@
             },
             "TokenInvalido": {
                 "description": "components.responses.TokenInvalido.description",
+                "headers": {
+                    "X-ServeRest-Stages": {
+                        "$ref": "#/components/headers/XServeRestStages"
+                    }
+                },
                 "content": {
                     "application/json": {
                         "schema": {
@@ -924,6 +1064,11 @@
             },
             "RotaParaAdministradores": {
                 "description": "components.responses.RotaParaAdministradores.description",
+                "headers": {
+                    "X-ServeRest-Stages": {
+                        "$ref": "#/components/headers/XServeRestStages"
+                    }
+                },
                 "content": {
                     "application/json": {
                         "schema": {
@@ -933,6 +1078,15 @@
                 }
             }
         },
+        "headers": {
+            "XServeRestStages": {
+                "description": "components.headers.XServeRestStages.description",
+                "schema": {
+                    "type": "string",
+                    "example": "body;st=ok;dur=0.21, rate_limit;st=skipped, auth;st=failed;dur=0.05;reason=token_missing, schema;st=not_run, rules;st=not_run, write;st=not_run"
+                }
+            }
+        },
         "securitySchemes": {
             "ApiKeyAuth": {
                 "type": "apiKey",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverest",
-  "version": "3.2.2",
+  "version": "3.3.0-beta.1",
   "description": "Servidor REST local de forma rápida e simples para estudo de testes de API",
   "author": "Paulo Gonçalves <author@serverest.dev> (https://www.linkedin.com/in/paulo-goncalves/)",
   "license": "GPL-3.0",
@@ -66,6 +66,7 @@
     "moesif-nodejs": "^3.11.0",
     "morgan": "^1.10.1",
     "nedb-promises": "^6.2.3",
+    "on-headers": "^1.1.0",
     "open": "^11.0.0",
     "rate-limiter-flexible": "^9.1.0",
     "swagger-ui-express": "^5.0.1",

package/src/app.js

@@ -26,6 +26,7 @@ const moesifMiddleware = require('./middlewares/moesif-monitor-middleware')
 const { version } = require('../package.json')
 const swaggerDocument = require('../docs/swagger.json')
 const rateLimiter = require('./middlewares/rate-limiter')
+const { iniciar, etapa } = require('./utils/etapas')
 const { fetchLatestRelease } = require('./utils/github-release')
 const { buildCustomJsStr, customCss } = require('./swagger')
 const { localizeSwaggerDocument } = require('./swagger/translations')
@@ -55,13 +56,15 @@ app.set('json spaces', 4)
 // o Express passaria a ler o primeiro endereço do X-Forwarded-For, que o próprio cliente
 // pode forjar, então o número de saltos precisa ser explícito.
 app.set('trust proxy', 1)
-app.use(express.json())
-app.use(express.urlencoded({ extended: false }))
+app.use(['/login', '/usuarios', '/produtos', '/carrinhos'], iniciar)
+const parsersDoBody = express.Router()
+parsersDoBody.use(express.json(), express.urlencoded({ extended: false }))
+app.use(etapa('body', parsersDoBody))
 app.use(queryParser())
 app.use(timeout())
-app.use(cors())
+app.use(cors({ exposedHeaders: ['X-ServeRest-Stages'] }))
 app.use(moesifMiddleware)
-app.use(rateLimiter)
+app.use(etapa('rate_limit', rateLimiter))
 
 app.disable('etag')
 

package/src/controllers/carrinhos-controller.js

@@ -18,7 +18,11 @@ exports.getOne = async (req, res) => {
 }
 
 exports.post = async (req, res) => {
+  const { etapas } = res.locals
+  etapas.regras('single_cart', 'no_duplicate_product', 'product_exists', 'enough_stock')
+
   const { idUsuario, possuiCarrinho } = await service.usuarioJaPossuiCarrinho(req.headers.authorization)
+  etapas.regra('single_cart', !possuiCarrinho)
   if (possuiCarrinho) {
     return res.status(400).send({ message: constant.LIMIT_JUST_ONE_CART })
   }
@@ -26,14 +30,26 @@ exports.post = async (req, res) => {
   const { produtos } = req.body
 
   const idProdutosDuplicados = service.extrairProdutosDuplicados(produtos)
+  etapas.regra('no_duplicate_product', !idProdutosDuplicados.length)
   if (idProdutosDuplicados.length) {
     return res.status(400).send({ message: constant.CART_WITH_DUPLICATE_PRODUCT, idProdutosDuplicados })
   }
 
   const { produtosComPrecoUnitario, error } = await service.getProdutosComPrecoUnitarioOuErro(produtos)
   if (error) {
+    // As duas regras são avaliadas item a item e param no primeiro item que falha.
+    if (error.message === constant.PRODUCT_NOT_FOUND) {
+      etapas.regra('product_exists', false, { item: error.index })
+    } else {
+      etapas.regra('product_exists', true)
+      etapas.regra('enough_stock', false, { item: error.index })
+    }
     return res.status(error.statusCode).send({ message: error.message, item: error.item })
   }
+  etapas.regra('product_exists', true)
+  etapas.regra('enough_stock', true)
+
+  etapas.abrir('write')
   const precoTotal = await service.precoTotal(produtosComPrecoUnitario)
   const quantidadeTotal = await service.quantidadeTotal(produtosComPrecoUnitario)
 

package/src/middlewares/authentication-middleware.js

@@ -1,41 +1,45 @@
 'use strict'
 
+const { TokenExpiredError } = require('jsonwebtoken')
+
 const authService = require('../services/auth-service')
 const constant = require('../utils/constants')
 const usuariosService = require('../services/usuarios-service')
+const { etapa } = require('../utils/etapas')
 
-exports.checkAdm = async (req, res, next) => {
-  if (!await tokenValido(req.headers)) {
+exports.checkAdm = etapa('auth', async (req, res, next) => {
+  const motivo = await motivoDoTokenInvalido(req.headers)
+  if (motivo) {
+    res.locals.etapas.detalhar({ reason: motivo })
     return res.status(401).send({ message: constant.INVALID_TOKEN })
   }
   const tokenDecodificado = authService.verifyToken(req.headers.authorization)
   if (!await usuariosService.usuarioEhAdministrador(tokenDecodificado)) {
+    res.locals.etapas.detalhar({ reason: 'not_admin' })
     return res.status(403).send({ message: constant.REQUIRED_ADMIN })
   }
   next()
-}
+})
 
-exports.checkToken = async (req, res, next) => {
-  if (!await tokenValido(req.headers)) {
+exports.checkToken = etapa('auth', async (req, res, next) => {
+  const motivo = await motivoDoTokenInvalido(req.headers)
+  if (motivo) {
+    res.locals.etapas.detalhar({ reason: motivo })
     return res.status(401).send({ message: constant.INVALID_TOKEN })
   }
   next()
-}
+})
 
-async function tokenValido ({ authorization }) {
-  if (authorization === undefined) return false
+async function motivoDoTokenInvalido ({ authorization }) {
+  if (authorization === undefined) return 'token_missing'
 
-  const semBearer = authorization.split(' ')[0] !== 'Bearer'
-  const semToken = authorization.split(' ')[1] === undefined
-
-  if (semBearer || semToken) {
-    return false
-  }
+  const [tipo, token] = authorization.split(' ')
+  if (tipo !== 'Bearer' || !token) return 'bad_format'
 
   const tokenDecodificado = authService.verifyToken(authorization)
-  if (tokenDecodificado.email === undefined) {
-    return false
-  }
+  if (tokenDecodificado instanceof TokenExpiredError) return 'token_expired'
+  if (tokenDecodificado.email === undefined) return 'token_invalid'
 
-  return usuariosService.existeUsuario({ email: tokenDecodificado.email, password: tokenDecodificado.password })
+  const usuario = await usuariosService.existeUsuario({ email: tokenDecodificado.email, password: tokenDecodificado.password })
+  if (!usuario) return 'user_not_found'
 }

package/src/middlewares/rate-limiter.js

@@ -24,6 +24,7 @@ const limiteGlobal = new RateLimiterMemory({
 
 module.exports = async (req, res, next) => {
   if (aplicacaoExecutandoLocalmente() || ehAmbienteDeTestes) {
+    res.locals.etapas?.ignorar()
     return next()
   }
 

package/src/routes/carrinhos-route.js

@@ -6,12 +6,13 @@ const authentication = require('../middlewares/authentication-middleware')
 const controller = require('../controllers/carrinhos-controller')
 const model = require('../models/carrinhos-model')
 const validateSchema = require('../services/validateSchema-service')
+const { etapa, plano } = require('../utils/etapas')
 
 const router = express.Router()
-router.get('/', validateSchema(model.schemaGet), controller.get)
-router.get('/:id', validateSchema(model.schemaGetOne), controller.getOne)
-router.post('/', authentication.checkToken, validateSchema(model.schemaPost), controller.post)
-router.delete('/concluir-compra', authentication.checkToken, controller.concluirCompra)
-router.delete('/cancelar-compra', authentication.checkToken, controller.cancelarCompra)
+router.get('/', plano('schema', 'read'), validateSchema(model.schemaGet), etapa('read', controller.get))
+router.get('/:id', plano('schema', 'read'), validateSchema(model.schemaGetOne), etapa('read', controller.getOne))
+router.post('/', plano('auth', 'schema', 'rules', 'write'), authentication.checkToken, validateSchema(model.schemaPost), etapa('rules', controller.post))
+router.delete('/concluir-compra', plano('auth', 'rules'), authentication.checkToken, etapa('rules', controller.concluirCompra))
+router.delete('/cancelar-compra', plano('auth', 'rules'), authentication.checkToken, etapa('rules', controller.cancelarCompra))
 
 module.exports = router

package/src/routes/login-route.js

@@ -5,8 +5,9 @@ const express = require('express')
 const controller = require('../controllers/login-controller')
 const model = require('../models/login-model')
 const validateSchema = require('../services/validateSchema-service')
+const { etapa, plano } = require('../utils/etapas')
 
 const router = express.Router()
-router.post('/', validateSchema(model.schemaPost), controller.post)
+router.post('/', plano('schema', 'rules'), validateSchema(model.schemaPost), etapa('rules', controller.post))
 
 module.exports = router

package/src/routes/produtos-route.js

@@ -6,12 +6,13 @@ const authentication = require('../middlewares/authentication-middleware')
 const controller = require('../controllers/produtos-controller')
 const model = require('../models/produtos-model')
 const validateSchema = require('../services/validateSchema-service')
+const { etapa, plano } = require('../utils/etapas')
 
 const router = express.Router()
-router.get('/', validateSchema(model.schemaGet), controller.get)
-router.get('/:id', validateSchema(model.schemaGetOne), controller.getOne)
-router.post('/', authentication.checkAdm, validateSchema(model.schemaPost), controller.post)
-router.delete('/:id', authentication.checkAdm, validateSchema(model.schemaDelete), controller.delete)
-router.put('/:id', authentication.checkAdm, validateSchema(model.schemaPut), controller.put)
+router.get('/', plano('schema', 'read'), validateSchema(model.schemaGet), etapa('read', controller.get))
+router.get('/:id', plano('schema', 'read'), validateSchema(model.schemaGetOne), etapa('read', controller.getOne))
+router.post('/', plano('auth', 'schema', 'rules'), authentication.checkAdm, validateSchema(model.schemaPost), etapa('rules', controller.post))
+router.delete('/:id', plano('auth', 'schema', 'rules'), authentication.checkAdm, validateSchema(model.schemaDelete), etapa('rules', controller.delete))
+router.put('/:id', plano('auth', 'schema', 'rules'), authentication.checkAdm, validateSchema(model.schemaPut), etapa('rules', controller.put))
 
 module.exports = router

package/src/routes/usuarios-route.js

@@ -5,12 +5,13 @@ const express = require('express')
 const controller = require('../controllers/usuarios-controller')
 const model = require('../models/usuarios-model')
 const validateSchema = require('../services/validateSchema-service')
+const { etapa, plano } = require('../utils/etapas')
 
 const router = express.Router()
-router.get('/', validateSchema(model.schemaGet), controller.get)
-router.get('/:id', validateSchema(model.schemaGetOne), controller.getOne)
-router.post('/', validateSchema(model.schemaPost), controller.post)
-router.delete('/:id', validateSchema(model.schemaDelete), controller.delete)
-router.put('/:id', validateSchema(model.schemaPut), controller.put)
+router.get('/', plano('schema', 'read'), validateSchema(model.schemaGet), etapa('read', controller.get))
+router.get('/:id', plano('schema', 'read'), validateSchema(model.schemaGetOne), etapa('read', controller.getOne))
+router.post('/', plano('schema', 'rules'), validateSchema(model.schemaPost), etapa('rules', controller.post))
+router.delete('/:id', plano('schema', 'rules'), validateSchema(model.schemaDelete), etapa('rules', controller.delete))
+router.put('/:id', plano('schema', 'rules'), validateSchema(model.schemaPut), etapa('rules', controller.put))
 
 module.exports = router

package/src/services/validateSchema-service.js

@@ -2,6 +2,8 @@
 
 const { validate } = require('express-validation')
 
+const { etapa } = require('../utils/etapas')
+
 module.exports = schema => {
-  return validate(schema, { keyByField: false }, { abortEarly: false })
+  return etapa('schema', validate(schema, { keyByField: false }, { abortEarly: false }))
 }

package/src/swagger/translations/en.js

@@ -93,5 +93,6 @@ module.exports = {
   'components.responses.ProdutoNomeDuplicado.description': 'A product with this name already exists',
   'components.responses.TokenInvalido.description': 'Token missing, invalid or expired',
   'components.responses.RotaParaAdministradores.description': 'Route exclusive to administrators (`administrador = true`)',
+  'components.headers.XServeRestStages.description': 'Stages of the route in execution order. Each entry has `st` (`ok`, `failed`, `skipped` or `not_run`), `dur` in milliseconds when the stage ran, `reason` when `auth` fails and `item` when a rule fails on a specific item. Entries named `<stage>.<rule>` detail the rules of that stage. Full format in the project README.',
   'components.securitySchemes.ApiKeyAuth.description': 'Provide the `Authorization` value returned by the _/login_ route'
 }

package/src/swagger/translations/es.js

@@ -93,5 +93,6 @@ module.exports = {
   'components.responses.ProdutoNomeDuplicado.description': 'Ya existe un producto con ese nombre',
   'components.responses.TokenInvalido.description': 'Token ausente, inválido o expirado',
   'components.responses.RotaParaAdministradores.description': 'Ruta exclusiva para administradores (`administrador = true`)',
+  'components.headers.XServeRestStages.description': 'Etapas de la ruta en orden de ejecución. Cada entrada tiene `st` (`ok`, `failed`, `skipped` o `not_run`), `dur` en milisegundos cuando la etapa se ejecutó, `reason` cuando `auth` falla e `item` cuando una regla falla en un ítem específico. Las entradas `<etapa>.<regla>` detallan las reglas de la etapa. Formato completo en el README del proyecto.',
   'components.securitySchemes.ApiKeyAuth.description': 'Indica el valor de `Authorization` devuelto por la ruta _/login_'
 }

package/src/swagger/translations/pt-BR.js

@@ -93,5 +93,6 @@ module.exports = {
   'components.responses.ProdutoNomeDuplicado.description': 'Já existe produto com esse nome',
   'components.responses.TokenInvalido.description': 'Token ausente, inválido ou expirado',
   'components.responses.RotaParaAdministradores.description': 'Rota exclusiva para administradores (`administrador = true`)',
+  'components.headers.XServeRestStages.description': 'Etapas da rota em ordem de execução. Cada entrada tem `st` (`ok`, `failed`, `skipped` ou `not_run`), `dur` em milissegundos quando a etapa executou, `reason` quando `auth` falha e `item` quando uma regra falha em um item específico. Entradas `<etapa>.<regra>` detalham as regras da etapa. Formato completo no README do projeto.',
   'components.securitySchemes.ApiKeyAuth.description': 'Informe o valor de `Authorization` retornado na rota _/login_'
 }

package/src/utils/etapas.js

@@ -0,0 +1,98 @@
+'use strict'
+
+const onHeaders = require('on-headers')
+
+const emMilissegundos = nanossegundos => (Number(nanossegundos) / 1e6).toFixed(2)
+
+class Registro {
+  constructor () {
+    this.entradas = []
+    this.regrasDeclaradas = new Map()
+    this.aberta = undefined
+  }
+
+  planejar (nomes) {
+    nomes.forEach(nome => this.entradas.push({ nome, st: 'not_run', detalhes: {} }))
+  }
+
+  abrir (nome) {
+    this.fechar('ok')
+    this.aberta = this.entradas.find(entrada => entrada.nome === nome)
+    this.aberta.inicio = process.hrtime.bigint()
+  }
+
+  fechar (st) {
+    if (!this.aberta) return
+    this.aberta.st = st
+    this.aberta.dur = emMilissegundos(process.hrtime.bigint() - this.aberta.inicio)
+    this.aberta = undefined
+  }
+
+  ignorar () {
+    this.aberta.st = 'skipped'
+    this.aberta = undefined
+  }
+
+  detalhar (objeto) {
+    Object.assign(this.aberta.detalhes, objeto)
+  }
+
+  regras (...nomes) {
+    const novas = nomes.map(nome => {
+      const entrada = { nome: `${this.aberta.nome}.${nome}`, st: 'not_run', detalhes: {} }
+      this.regrasDeclaradas.set(nome, entrada)
+      return entrada
+    })
+    this.entradas.splice(this.entradas.indexOf(this.aberta) + 1, 0, ...novas)
+  }
+
+  regra (nome, passou, detalhes) {
+    const entrada = this.regrasDeclaradas.get(nome)
+    entrada.st = passou ? 'ok' : 'failed'
+    Object.assign(entrada.detalhes, detalhes)
+  }
+
+  // A etapa ainda aberta quando os headers são escritos é a que produziu a resposta.
+  finalizar (statusCode) {
+    this.fechar(statusCode >= 400 ? 'failed' : 'ok')
+  }
+
+  stages () {
+    return this.entradas
+      .map(({ nome, st, dur, detalhes }) => [
+        nome,
+        `st=${st}`,
+        ...(dur === undefined ? [] : [`dur=${dur}`]),
+        ...Object.entries(detalhes).map(([chave, valor]) => `${chave}=${valor}`)
+      ].join(';'))
+      .join(', ')
+  }
+}
+
+exports.iniciar = (req, res, next) => {
+  // O cors responde o preflight antes do rate limiter, então não há etapa a relatar.
+  if (req.method === 'OPTIONS') return next()
+  const registro = res.locals.etapas = new Registro()
+  registro.planejar(['body', 'rate_limit'])
+  onHeaders(res, () => {
+    registro.finalizar(res.statusCode)
+    res.setHeader('X-ServeRest-Stages', registro.stages())
+  })
+  next()
+}
+
+// Exatamente três parâmetros: com quatro o Express trataria o retorno como error handler.
+exports.etapa = (nome, middleware) => (req, res, next) => {
+  const registro = res.locals.etapas
+  if (!registro) return middleware(req, res, next)
+  registro.abrir(nome)
+  return middleware(req, res, erro => {
+    registro.fechar(erro ? 'failed' : 'ok')
+    next(erro)
+  })
+}
+
+exports.plano = (...nomes) => (req, res, next) => {
+  res.locals.etapas.planejar(nomes)
+  next()
+}