HTTP Pipeline

Controller examples, route loading, validation behavior, middleware, and response plugins.

HTTP Pipeline

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

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.

Runtime And Lifecycle Notes

• new Http({ port }) creates a Koa app and a find-my-way router.
• 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.
• 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.

Verification Checklist

• Controller files default-export defineController(...) or an array of controllers.
• 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.