@hile/http

Build Koa HTTP APIs with file-system controllers, middleware, response plugins, and Zod validation.

@hile/http

Build Koa HTTP APIs with file-system controllers, middleware, response plugins, and Zod validation.

Choose This Package When

User asks for	Use	Also read
Create an HTTP endpoint or Koa middleware	@hile/http	HTTP API, HTTP, Model, and TypeORM
Run Next.js and API controllers on one port	@hile/http-next	HttpNext, HttpNext fullstack
Preserve HTTP semantics across a Micro call	@hile/http-over-micro	HTTP over Micro, Messaging and Micro

Use When

Use @hile/http for Koa-based APIs, middleware, manual routes, file-system controllers, Zod validation, and response plugins.

Do Not Use When

• Do not use it for Next.js pages; use @hile/http-next when Next.js and API routes share a port.
• Do not assume Zod validation mutates/coerces Koa context data. It validates only.

Install

pnpm add @hile/http

Imports

import { Http, defineController, createControllerMetadata, defineResponsePlugin } from '@hile/http'
import { z } from 'zod'

Copy-Paste Example

import { defineController } from '@hile/http'

export default defineController('GET', async () => {
  return { ok: true }
})

File route examples:

src/controllers/index.controller.ts -> /
src/controllers/users/index.controller.ts -> /users
src/controllers/users/[id].controller.ts -> /users/:id
src/controllers/assets/[...paths].controller.ts -> /assets/*

The catch-all declaration is required: /assets/logo.svg and /assets/icons/logo.svg match, while /assets does not. The controller reads the portable declaration name rather than find-my-way’s internal wildcard key:

// src/controllers/assets/[...paths].controller.ts
import { defineController } from '@hile/http'

export default defineController('GET', (ctx) => ({ path: ctx.params.paths }))

ctx.params.paths is icons/logo.svg for /assets/icons/logo.svg. Dynamic names must be unique across the complete route and cannot be __proto__, prototype, or constructor. Static routes win over [id], and [id] wins over [...paths]. Routes with the same structure but different parameter names conflict during loading. A configured prefix may use native /:tenant or bracket-style /[tenant] parameters and is compiled separately from portable file segments. Use http.route() when deliberately registering native find-my-way syntax by hand; native syntax is not accepted in file names.

More Examples

import { z } from 'zod'
import { createControllerMetadata, defineController } from '@hile/http'

const bodySchema = z.object({
  username: z.string().min(1),
  age: z.number().int().nonnegative(),
})

export default defineController(
  createControllerMetadata({
    method: 'POST',
    schema: { body: bodySchema },
  }),
  async (ctx) => {
    const body = bodySchema.parse(ctx.request.body)
    return { created: true, user: body }
  },
)

The second parse is intentional when you need parsed/coerced data. Hile’s controller validation does not write safeParse().data back to ctx.request.body.

Trusted reverse proxy

Http does not trust forwarded headers by default. When the listener is reachable only through a controlled reverse proxy, enable Koa’s proxy semantics explicitly and bound the number of proxy IPs that may be read:

const http = new Http({
  port: 3000,
  proxy: true,
  maxIpsCount: 1,
})

The edge proxy must replace, not append untrusted input to, X-Forwarded-Proto and the configured client-IP header. It must send X-Forwarded-Proto: https after TLS termination so ctx.protocol, ctx.secure, and Secure Cookie handling reflect the public connection. Keep the Hile listener inaccessible to untrusted direct clients: proxy: true trusts these headers and is not itself a network trust boundary.

Use proxyIpHeader only when the deployment uses a client-IP header other than X-Forwarded-For. maxIpsCount bounds the proxy chain read from that header; set it to the known number of trusted hops instead of relying on Koa’s unbounded default.

HttpProps composes Koa’s complete constructor options with Hile’s port and find-my-way options. Koa settings such as env, subdomainOffset, keys, asyncLocalStorage, proxy, proxyIpHeader, and maxIpsCount are passed through without a Hile-owned mirror or a second Hile-specific option contract.

Runtime And Lifecycle Notes

• new Http({ port }) creates a Koa app from the complete HttpProps object and a find-my-way router.
• proxy defaults to false. When enabled, proxyIpHeader and maxIpsCount are passed to Koa before any middleware or controller handles requests.
• http.use(middleware) registers Koa middleware before listen().
• http.listen() returns a close function.
• http.load(directory, options) scans *.controller.{ts,js,tsx,jsx,mjs} by suffix.
• .d.ts declarations and .js.map source maps are never controller routes.
• File loading is atomic: invalid syntax, import failure, invalid exports, or conflicts unregister the routes already acquired by that batch.
• defineController() supports method-only, method-plus-middlewares, and metadata-plus-Zod forms.
• Response plugins transform handler return values and set ctx.body when the final result is not undefined.

Anti-Patterns

• Setting ctx.body and returning a value from the same controller.
• Loading controllers after starting only because an old example does it; prefer load before listen in new code.
• Using old validation examples that assume Zod coercion rewrote ctx.query.
• Enabling proxy on a listener that untrusted clients can reach directly, or allowing an edge proxy to preserve client-supplied forwarded headers.

Verification Checklist

• Controller files default-export defineController(...) or an array of controllers.
• Required catch-all controllers use [...name].controller.ts, keep it as the final segment, and read the slash-joined value from ctx.params.name.
• Controllers return response values.
• Boot service awaits http.load() before http.listen().
• Zod schemas are used for validation, and parsed data is explicitly parsed when needed.
• Reverse-proxy deployments replace forwarded headers, protect the direct listener, and set maxIpsCount to the known proxy-hop count.

Related Recipes

HTTP API + Model + TypeORM

Complete Example

Controller:

// src/controllers/users/[id].controller.ts
import { randomUUID } from 'node:crypto'
import { createExecutionContext, createInvocationContext } from '@hile/context'
import { defineController } from '@hile/http'
import { loadModel } from '@hile/model'
import { getUser } from '../../models/users/get-user.model'

export default defineController('GET', async (ctx) => {
  const invocation = createInvocationContext(
    createExecutionContext({ requestId: randomUUID() }),
    new AbortController().signal,
  )
  return loadModel(getUser, { userId: String(ctx.params.id) }, invocation)
})

Model:

// src/models/users/get-user.model.ts
import { defineModel } from '@hile/model'
import typeormService from '@hile/typeorm'
import { User } from '../../entities/user.entity'

export const getUser = defineModel({
  services: [typeormService] as const,
  async main([ds], input: { userId: string }) {
    const user = await ds.getRepository(User).findOneBy({ id: input.userId })
    if (!user) return { found: false }
    return { found: true, user }
  },
})

Boot file:

// src/services/http.boot.ts
import { defineService } from '@hile/core'
import { Http } from '@hile/http'

export default defineService('http', async (shutdown) => {
  const http = new Http({ port: Number(process.env.HTTP_PORT ?? 3000) })
  await http.load(new URL('../controllers', import.meta.url).pathname)
  const close = await http.listen()
  shutdown(close)
  return http
})

Package config:

{
  "type": "module",
  "scripts": {
    "dev": "hile start --dev --env-file .env",
    "start": "hile start --env-file .env.prod"
  },
  "hile": {
    "auto_load_packages": ["@hile/typeorm"]
  }
}

Package-Local AI Guide

This package also ships AI.md in npm so agents can read accurate examples after installation.