Middleware no nível da aplicação
Uma rota declara seu próprio middleware em use:. Esse é o lugar certo para uma preocupação que pertence a uma única rota. Preocupações transversais — CORS, headers de resposta seguros, um limite de tamanho de corpo — pertencem a toda rota. Copiá-las em cada defineRoute é uma violação de DRY, e uma rota que você esquece de atualizar é uma rota sem elas.
createApp recebe uma cadeia opcional middlewares para exatamente isso. Ela roda antes do use: de cada rota.
import { bodyLimit, cors, secureHeaders } from '@katajs-framework/core'
import { createApp } from './context'
import * as users from './modules/users/users.route'
import * as echo from './modules/echo/echo.route'
const app = createApp({
modules: [users, echo],
middlewares: [cors(), secureHeaders(), bodyLimit({ maxSize: 8 * 1024 })],
})A cadeia compartilha exatamente o mesmo contrato Middleware<R> que o middleware de rota usa — mesmo pipeline em runtime, mesmo store scoped por requisição. Qualquer middleware que funcione no use: de uma rota funciona aqui sem alterações. Veja a ADR-0012 para a decisão.
Ordenação
A cadeia efetiva de qualquer rota é a cadeia global seguida pela cadeia própria da rota, cada uma na ordem declarada (do array):
effective = [...config.middlewares, ...route.use]| Fase | O que roda |
|---|---|
| 1. Cadeia global | config.middlewares, em ordem — mais externa |
| 2. Cadeia da rota | route.use, em ordem |
| 3. Validação de input | envelope 422 em caso de falha |
| 4. Handler | route.handler |
| 5. Validação de output | strict/log conforme a ADR-0009 |
Esta é a cebola padrão. Um middleware global envolve todo o pipeline da rota: o código antes do next() roda antes de qualquer middleware de rota, e o código após o next() roda depois do handler.
Duas propriedades se transferem do middleware de rota verbatim, porque um global é apenas um elemento anterior do mesmo array:
- Curto-circuito. Um global pode
returnumaResponsepara parar a requisição. Ele pula todo global posterior, toda a cadeiause:e o handler. A resposta retornada ainda recebe o headerx-request-ide é logada como qualquer outro desfecho. - Scoped slots. Um scoped slot que um middleware global
provides:é legível viac.getem todo handler — o global roda antes do handler e escreve no mesmo store por requisição que o handler lê. UmauthMiddlewareglobal comprovides: ['currentUser']tornac.get('currentUser')válido em toda rota sem que essa rota o liste emuse:.
O kata verify lê essa cadeia do mesmo jeito que o runtime a executa. A regra kata/scoped-slot-not-provided percorre [...config.middlewares, ...route.use] em ordem por rota, então um provedor global satisfaz as leituras de todas as rotas, e um middleware global que ele próprio lê um slot que nada à sua frente fornece é um erro. Os built-ins abaixo resolvem pelo manifesto provides.json que o @katajs-framework/core publica — cors() numa cadeia é uma entrada provides: [], não uma incógnita — então declará-los não custa cobertura de verificação. Uma entrada que a regra não consegue ler é reportada como uma supressão em vez de passar em silêncio.
Um global roda para toda rota
Não há opt-out por rota. Um middleware na cadeia global roda para toda rota, inclusive as que não precisam dele. Escolher e ordenar a cadeia é sua responsabilidade. Se uma preocupação for genuinamente específica de uma rota, mantenha-a no use: daquela rota.
Built-ins
Três middlewares de hardening de primeira parte vêm da entrada core do @katajs-framework/core. Cada um é uma factory de Middleware<R>, declara provides: [] e define headers de resposta (ou rejeita uma requisição) sem tocar no corpo da resposta.
cors
function cors<R extends Registry = Registry>(options?: CorsOptions): Middleware<R>Um wrapper fino sobre o cors do Hono. CorsOptions espelha as opções do Hono — origin, allowMethods, allowHeaders, exposeHeaders, maxAge, credentials — veja a documentação de CORS do Hono.
import { cors } from '@katajs-framework/core'
createApp({
modules: [users],
middlewares: [cors({ origin: 'https://app.example.com', credentials: true })],
})O preflight é respondido automaticamente
cors() faz o trabalho inteiro onde quer que você o declare — por rota ou na cadeia global: além de definir os headers Access-Control-Allow-* nas respostas reais, o runtime auto-registra um responder OPTIONS sintético para o path dele, conforme a ADR-0020. Não registre CORS uma segunda vez. Veja Preflight de CORS abaixo para entender como funciona.
secureHeaders
function secureHeaders<R extends Registry = Registry>(
options?: SecureHeadersOptions,
): Middleware<R>Um wrapper fino sobre o secureHeaders do Hono. Sem opções, ele aplica a baseline endurecida do Hono — X-Content-Type-Options: nosniff, X-Frame-Options: SAMEORIGIN, Strict-Transport-Security e mais — e remove X-Powered-By. SecureHeadersOptions espelha as opções do Hono (xFrameOptions, strictTransportSecurity, contentSecurityPolicy, referrerPolicy, …); passe false para um header individual para desativá-lo. Veja a documentação de secure-headers do Hono.
import { secureHeaders } from '@katajs-framework/core'
createApp({
modules: [users],
middlewares: [secureHeaders({ contentSecurityPolicy: { defaultSrc: ["'self'"] } })],
})bodyLimit
function bodyLimit<R extends Registry = Registry>(
options?: BodyLimitOptions,
): Middleware<R>O runtime do Kata lê o corpo da requisição via c.req.json() sem guarda de tamanho. Adicione bodyLimit para rejeitar payloads grandes demais antes que sejam bufferizados e parseados. O limite é imposto via o header Content-Length (caminho rápido) e, quando ausente, pela medição do corpo em streaming.
type BodyLimitOptions = {
maxSize?: number // bytes; defaults to DEFAULT_MAX_BODY_SIZE (1 MiB)
onError?: (c: Context) => Response | Promise<Response>
}maxSize tem como padrão DEFAULT_MAX_BODY_SIZE — 1024 * 1024 (1 MiB), exportado de @katajs-framework/core. Quando o limite é excedido, o onError padrão retorna HTTP 413 com o envelope de erro unificado do kata (ADR-0008):
{ "error": "payload_too_large", "message": "Request body exceeds the maximum allowed size" }import { bodyLimit } from '@katajs-framework/core'
createApp({
modules: [users],
middlewares: [bodyLimit({ maxSize: 8 * 1024 })], // 8 KiB
})Adaptando um middleware do Hono
Os três built-ins não são especiais: cada um é um middleware comum do Hono envolvido para encaixar no contrato Middleware<R> do Kata. Entender por que o wrapper é necessário explica uma restrição real sobre o que pode entrar em uma cadeia.
Aqui está o problema. O Kata constrói sua resposta no fim da cadeia de uma rota e a retorna desacoplada de c.res. Um middleware normal do Hono que define headers de resposta depois do seu próprio next() — secureHeaders é um deles — espera escrever esses headers em c.res no caminho de volta. Mas a essa altura o Kata já tirou um snapshot da resposta, então esses headers simplesmente seriam descartados.
O wrapper contorna isso mudando quando o middleware do Hono roda. Ele executa o middleware envolvido até a conclusão primeiro, entregando-lhe um next inerte, de modo que todo header que ele define caia em c.res antes de o Kata construir a resposta — então ele continua a própria cadeia do Kata. E se o middleware envolvido der curto-circuito com uma Response (um 413, um preflight de CORS 204), essa resposta é retornada e a cadeia para.
O porém: esse adaptador — fromHono, usado internamente pelos três built-ins — é correto apenas para middlewares que definem headers de resposta ou rejeitam uma requisição. Um transformador de resposta — compressão, ETag — precisa observar o corpo final, o que ele nunca consegue de um next() inerte rodado antes da própria cadeia do Kata. (Esta é a mesma restrição sob a qual o middleware de rota vive; veja o aviso de c.header em Middleware.)
fromHonoTransform
Para esse caso mais restrito — um middleware do Hono que transforma a resposta — existe um segundo adaptador, opt-in (ADR-0020):
import { fromHonoTransform } from '@katajs-framework/core'
import { compress } from 'hono/compress'
defineRoute({
method: 'GET',
path: '/report',
use: [fromHonoTransform(compress())],
// ...
})Diferente do fromHono, ele conecta um next real: chamá-lo deixa a própria cadeia e o handler do Kata rodarem até o fim primeiro, coloca a Response resultante onde o middleware envolvido a lê e — quando o middleware a substitui, como compress() e etag() fazem — envia essa substituição de volta como a resposta do Kata. O trade-off é uma restrição: para ver o corpo final, a entrada precisa envolver tudo o que vem depois dela, então precisa ser a primeira entrada da sua cadeia efetiva — um global anterior, ou outra entrada de use: antes dela, e o kata lança um erro na inicialização em vez de silenciosamente descartar a transformação. O fromHono continua sendo o padrão para todo o resto — middlewares que definem headers e que rejeitam requisições.
Para middlewares que você escreve por conta própria — populando um scoped slot a partir de um cookie de sessão ou API key, adicionando camadas de autorização — não envolva um middleware do Hono com nenhum dos dois adaptadores. Use defineMiddleware e escreva no store scoped com c.set diretamente. Veja Middleware para o padrão de preenchimento de slots e Auth com JWT para o caminho específico de auth.
Preflight de CORS
Antes de qualquer requisição cross-origin não-simples, o navegador envia um preflight — OPTIONS no mesmo path, com Access-Control-Request-Method. O Kata registra um handler apenas para o método declarado de uma rota e não tem rota OPTIONS implícita, então um preflight nunca corresponderia — e o preflight é uma propriedade do path, não da cadeia de um único método, então nenhum middleware por rota sozinho conseguiria respondê-lo. O runtime fecha essa lacuna por conta própria (ADR-0020): ao construir o app, ele percorre a cadeia efetiva de cada rota — os middlewares globais mais o use: próprio da rota — e, para cada path cuja cadeia carrega um cors() em qualquer ponto, auto-registra uma rota OPTIONS <path> real que roda apenas aquele cors().
Declarar cors() é, portanto, a história completa de CORS, seja global ou por rota:
const app = createApp({
modules: [users],
middlewares: [cors({ origin: 'https://app.example.com', credentials: true })],
})
// OPTIONS /users → 204 + Access-Control-Allow-* — nada mais a registrar.defineRoute({
method: 'POST',
path: '/items',
use: [cors()],
// ...
})
// OPTIONS /items → também 204, mesmo que cors() esteja declarado só nesta rota.Se mais de uma rota compartilha um path — GET /items e POST /items, ambas com cors() — o kata registra um único responder OPTIONS /items e reporta os dois métodos em Access-Control-Allow-Methods, a menos que você já tenha fixado allowMethods você mesmo nas CorsOptions.
Três propriedades decorrem de como o preflight é respondido:
- Livre de auth. O responder sintético roda apenas o
cors()que o disparou — nunca a cadeiause:própria da rota, nunca nenhum outro global. Um guard de JWT na rota protegida nunca vê, e portanto nunca responde 401 ao, preflight sem credenciais. - Observável. O
204passa pelo mesmo pipeline de resposta que qualquer outro desfecho: ecoa ox-request-ide produz a linha de log por requisição. - Opt-in. Um path sem nenhum
cors()em sua cadeia efetiva não recebe rotaOPTIONSsintética; um preflight contra ele cai na decisão normal de requisição sem correspondência —405com headerAllownum path declarado,404caso contrário.
E não registre também o cors do Hono nativamente no app retornado (app.use('*', honoCors(...))) — uma versão anterior deste guia mostrava isso como contorno, mas hoje isso registra CORS duas vezes e divide sua política de borda em dois lugares sem ganho algum: a resposta de preflight é idêntica sem ele.
Veja também
- Middleware — o contrato
Middleware<R>,provides:e o preenchimento de scoped slots. - Referência: middleware — assinaturas exatas dos built-ins e seus tipos de opções.
- ADR-0012 — por que a cadeia global estende a cadeia manual de rotas em vez de
app.use. - ADR-0020 — por que o framework responde ao preflight de CORS por conta própria e como funciona a costura do
fromHonoTransform.