Skip to content

Middlewares nativos ​

Três middlewares first-party vêm do core entry do @katajs-framework/core: cors, secureHeaders e bodyLimit. Cada um é uma factory Middleware<R> que você encaixa na cadeia use: de uma route ou na cadeia middlewares do app. Cada um declara provides: [] — não preenche nenhum scoped slot — e apenas define response headers ou rejeita a requisição; nenhum toca no response body.

A correlação de requisições (x-request-id) não é um middleware. É embutida no runtime e se aplica a toda resposta incondicionalmente. Veja Request id abaixo.

Para onde eles rodam, a ordenação em relação ao use: da route e como o preflight de CORS é respondido, veja Middleware no nível do app. Esta página é a referência de assinaturas.

ts
import { bodyLimit, cors, secureHeaders } from '@katajs-framework/core'

Os três são opt-in

Nenhum deles roda a menos que você os adicione. Um createApp novo não aplica política de CORS, nenhum header de segurança e nenhum limite de tamanho de body. O template do init e o app examples/hello adicionam os três no nível do app — copie isso como sua baseline.

cors ​

Um wrapper fino sobre o cors do Hono, moldado como um Middleware<R> do kata.

ts
function cors<R extends Registry = Registry>(options?: CorsOptions): Middleware<R>

CorsOptions é NonNullable<Parameters<typeof honoCors>[0]> — espelha exatamente as opções de CORS do Hono: origin, allowMethods, allowHeaders, exposeHeaders, maxAge e credentials. O kata não adiciona opções próprias e não aplica padrões além dos do Hono. Veja a documentação de CORS do Hono para a semântica completa das opções.

ts
import { cors } from '@katajs-framework/core'

import { createApp } from './context'
import * as users from './modules/users/users.route'

const app = createApp({
  modules: [users],
  middlewares: [cors({ origin: 'https://app.example.com', credentials: true })],
})

Chamado sem argumento, cors() passa undefined ao Hono — a política padrão do próprio Hono se aplica (Access-Control-Allow-Origin: *).

O preflight é respondido automaticamente

cors() também responde ao preflight de navegador, onde quer que você o declare: o kata não tem rota OPTIONS implícita, então o runtime auto-registra uma sintética para cada path cuja cadeia efetiva carrega um cors() — por rota ou a nível de app — rodando apenas aquele cors() num caminho livre de auth (ADR-0020). Não registre CORS uma segunda vez no app retornado. Veja Preflight de CORS.

secureHeaders ​

Um wrapper fino sobre o secureHeaders do Hono, moldado como um Middleware<R> do kata.

ts
function secureHeaders<R extends Registry = Registry>(
  options?: SecureHeadersOptions,
): Middleware<R>

SecureHeadersOptions é NonNullable<Parameters<typeof honoSecureHeaders>[0]> — espelha as opções de secure-headers do Hono: xFrameOptions, strictTransportSecurity, contentSecurityPolicy, referrerPolicy e o restante. Passe false para um header individual para desabilitá-lo. Veja a documentação de secure-headers do Hono.

Sem opções, secureHeaders() 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.

ts
import { secureHeaders } from '@katajs-framework/core'

import { createApp } from './context'
import * as users from './modules/users/users.route'

const app = createApp({
  modules: [users],
  middlewares: [secureHeaders({ contentSecurityPolicy: { defaultSrc: ["'self'"] } })],
})

bodyLimit ​

Um wrapper fino sobre o bodyLimit do Hono, moldado como um Middleware<R> do kata. O runtime do kata lê o request body via c.req.json() sem guarda de tamanho, então adicione bodyLimit para rejeitar payloads superdimensionados antes que sejam carregados em buffer e parseados. O limite é imposto via o header Content-Length (caminho rápido) e, quando não há Content-Length, medindo o body em streaming.

ts
function bodyLimit<R extends Registry = Registry>(
  options?: BodyLimitOptions,
): Middleware<R>

BodyLimitOptions é um tipo próprio do kata — não repassa o do Hono:

ts
type BodyLimitOptions = {
  /** Tamanho máximo do request body em bytes. Default: DEFAULT_MAX_BODY_SIZE (1 MiB). */
  maxSize?: number
  /**
   * Resposta retornada quando o limite é excedido. Default: HTTP 413 com o
   * error envelope unificado do kata.
   */
  onError?: (c: Context) => Response | Promise<Response>
}

Padrões ​

maxSize usa por padrão DEFAULT_MAX_BODY_SIZE, exportado de @katajs-framework/core:

ts
import { DEFAULT_MAX_BODY_SIZE } from '@katajs-framework/core'

DEFAULT_MAX_BODY_SIZE // 1024 * 1024 — 1 MiB

Quando o limite é excedido e você não fornece onError, o padrão retorna HTTP 413 com o error envelope unificado do kata (ADR-0008):

json
{
  "error": "payload_too_large",
  "message": "Request body exceeds the maximum allowed size"
}
ts
import { bodyLimit } from '@katajs-framework/core'

import { createApp } from './context'
import * as users from './modules/users/users.route'

const app = createApp({
  modules: [users],
  middlewares: [bodyLimit({ maxSize: 8 * 1024 })], // 8 KiB
})

Forneça onError para customizar a rejeição. Ele recebe o Context cru do Hono e deve retornar um Response:

ts
import { bodyLimit } from '@katajs-framework/core'

bodyLimit({
  maxSize: 8 * 1024,
  onError: (c) => c.json({ error: 'too_big' }, 413),
})

Uso em createApp ​

A mesma factory funciona na cadeia use: de uma route e na cadeia middlewares do app. Como cada uma declara provides: [], nenhuma route precisa listá-la. O app examples/hello aplica os três no nível do app:

ts
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],
  // Roda antes do `use:` próprio de cada route.
  middlewares: [cors(), secureHeaders(), bodyLimit({ maxSize: 8 * 1024 })],
})

A cadeia global roda antes do use: próprio de cada route. Para a tabela completa de ordenação e as regras de short-circuit / scoped slot, veja Middleware no nível do app.

Por-route em vez de global

Uma preocupação que pertence a uma única route fica no use: daquela route:

ts
defineRoute({
  method: 'POST',
  path: '/upload',
  use: [bodyLimit({ maxSize: 5 * 1024 * 1024 })], // 5 MiB, somente esta route
  input: { body: UploadBody },
  output: UploadResult,
  handler: (c) => /* ... */,
})

A ordem do use: decide qual checagem roda primeiro

use: faz short-circuit na ordem do array — o primeiro middleware a retornar um Response vence, e tudo depois dele (incluindo o resto do use:, a validação de input e o handler) é pulado. Coloque bodyLimit antes de um middleware de auth e uma requisição não autenticada superdimensionada responde 413, não 401:

ts
defineRoute({
  method: 'POST',
  path: '/upload',
  use: [bodyLimit({ maxSize: 256 * 1024 }), requireAuth], // 413 vence de 401
  input: { body: UploadBody },
  output: UploadResult,
  handler: (c) => /* ... */,
})

Um body de 300 KiB sem credenciais nunca chega ao requireAuth — o bodyLimit o rejeita primeiro. Inverta a ordem para autenticar antes de impor o limite de tamanho. Nenhuma das ordens é "errada" por si só; deixar isso por inferência é que é. Escolha uma de propósito e saiba o que um chamador não autenticado aprende com a resposta de qualquer forma — veja Middleware para a regra geral de short-circuit.

Por que precisam de um wrapper ​

Esses três são middlewares comuns do Hono adaptados ao modelo de resposta do kata. O kata monta sua resposta no fim da cadeia de uma route e a retorna desacoplada de c.res, então um middleware do Hono que define headers depois do seu próprio next() — como o secureHeaders — de outra forma seria descartado. O adapter interno roda o middleware do Hono até o fim primeiro (com um next inerte) para que todo header que ele define esteja em c.res antes de o kata fazer o snapshot da resposta, e então continua a cadeia do kata. Se o middleware encapsulado fizer short-circuit com um Response (um 413, um preflight de CORS 204), essa resposta é retornada e a cadeia para.

Isso torna o adapter correto para middleware que apenas define response headers ou rejeita uma requisição — não para transformadores de resposta (compressão, ETag) que precisam observar o body final. Para esses, use o fromHonoTransform:

ts
function fromHonoTransform<R extends Registry = Registry>(mw: MiddlewareHandler): Middleware<R>

Ele conecta um next real, para que o código pós-next do mw possa ler e substituir a Response final do kata. Precisa ser a primeira entrada da sua cadeia efetiva — o kata lança um erro na inicialização caso contrário. Veja Middleware no nível do app para a explicação completa.

Os dois adapters são internos para encapsular um middleware Hono cru. Para escrever seu próprio middleware diretamente contra o contexto do kata, recorra a defineMiddleware e escreva no scoped store com c.set em vez disso.

Request id ​

O kata atribui um id de correlação a toda requisição — não há middleware para adicionar e não há opt-out. O runtime reutiliza um header x-request-id de entrada bem formado (de modo que um id cunhado em um proxy de borda flui inalterado) e, caso contrário, gera um UUID novo. Um valor de entrada malformado ou superdimensionado é ignorado em favor de um id gerado. O id resolvido é ecoado no response header x-request-id de todo desfecho — incluindo short-circuits e erros 5xx — e está disponível como c.requestId dentro de middleware e handlers.

Apenas a constante do nome do header é exportada:

ts
import { REQUEST_ID_HEADER } from '@katajs-framework/core'

REQUEST_ID_HEADER // 'x-request-id'

Validação de ids de entrada

Um x-request-id de entrada só é confiável se corresponder a ^[\w.:-]{1,200}$ após o trim — suficiente para UUIDs e trace ids do W3C, mantendo de fora newlines e outros caracteres de controle (o vetor de injeção em header e log). Qualquer outra coisa é substituída por um UUID gerado.

Exports ​

Tudo nesta página vem do core entry do @katajs-framework/core:

ExportTipoNotas
corsfactory Middleware<R>encapsula cors do Hono
secureHeadersfactory Middleware<R>encapsula secureHeaders do Hono
bodyLimitfactory Middleware<R>encapsula bodyLimit do Hono
DEFAULT_MAX_BODY_SIZEnumber1024 * 1024 (1 MiB)
CorsOptionstypeespelha as opções de CORS do Hono
SecureHeadersOptionstypeespelha as opções de secure-headers do Hono
BodyLimitOptionstype{ maxSize?, onError? }
REQUEST_ID_HEADERstring'x-request-id'

Veja também ​

  • Middleware no nível do app — a cadeia middlewares, a ordenação e como o preflight de CORS é respondido.
  • Middleware — o contrato Middleware<R> e o preenchimento de scoped slot para middleware que você escreve.
  • defineMiddleware — defina seu próprio middleware.
  • JWT auth — o middleware jwtAuth de @katajs-framework/core/jwt.

Código aberto — licença a definir. Feito com Hono + Zod.