Skip to content

Hono — Checklist

OWNER: urszula, maxim ALSO_USED_BY: sandro, boris, yoanna LAST_VERIFIED: 2026-03-26 GE_STACK_VERSION: 4.12.x

Overview

Machine-parseable checklists for API endpoint quality, security, and performance. Run through these before any PR that adds or modifies Hono endpoints. Items grow organically and are NEVER removed.

API ENDPOINT CHECKLIST (per route)

  • [ ] CHECK: Route handler returns a Response on every code path IF_SKIPPED: TypeScript error in strict mode, runtime hang if missed
  • [ ] CHECK: Request body validated with zValidator('json', schema) IF_SKIPPED: Unvalidated input reaches business logic
  • [ ] CHECK: Path params validated with zValidator('param', schema) IF_SKIPPED: Invalid UUIDs or IDs cause DB errors
  • [ ] CHECK: Query params validated with zValidator('query', schema) using z.coerce for numbers IF_SKIPPED: String "10" passed where number expected, silent type mismatch
  • [ ] CHECK: Response wrapped in { data: T } envelope IF_SKIPPED: Frontend/agent consumers break on inconsistent response shape
  • [ ] CHECK: Success status code matches verb (200 GET/PUT, 201 POST, 204 DELETE) IF_SKIPPED: RPC client and agent consumers parse wrong status
  • [ ] CHECK: Validation errors return 422 with { error: "VALIDATION_ERROR", issues } body IF_SKIPPED: Consumers cannot distinguish validation from other 4xx errors
  • [ ] CHECK: Route uses kebab-case plural nouns in URL path IF_SKIPPED: Inconsistent API surface across services

SECURITY CHECKLIST (per service)

  • [ ] CHECK: app.onError() is configured with the GE error handler IF_SKIPPED: Stack traces leak to clients on unhandled errors
  • [ ] CHECK: Auth middleware applied to /api/*, NOT to /health IF_SKIPPED: k3s probes fail (CrashLoopBackOff) or API is unauthenticated
  • [ ] CHECK: CORS origin is an explicit allowlist, NOT '*' IF_SKIPPED: Any domain can call the API with credentials
  • [ ] CHECK: Rate limiter is applied to /api/* IF_SKIPPED: DoS vector, token burn if agents hammer endpoint
  • [ ] CHECK: Internal service token uses INTERNAL_API_TOKEN env var IF_SKIPPED: Hardcoded token in source code, secret leak
  • [ ] CHECK: Error responses do NOT include stack traces or internal paths IF_SKIPPED: Information disclosure vulnerability
  • [ ] CHECK: Request ID propagated via X-Request-ID header IF_SKIPPED: Cannot trace requests across services in k3s
  • [ ] CHECK: No process.env access in route handlers (use config injection) IF_SKIPPED: Untestable code, env coupling

PERFORMANCE CHECKLIST (per service)

  • [ ] CHECK: Hono app uses AppEnv generic for typed context IF_SKIPPED: Runtime type assertions needed, slower dev velocity
  • [ ] CHECK: Route files use method chaining for RPC type inference IF_SKIPPED: hc client loses type information, manual types needed
  • [ ] CHECK: Database queries use parameterized Drizzle queries (no raw SQL) IF_SKIPPED: SQL injection vector, no query plan caching
  • [ ] CHECK: /health endpoint returns without DB or external calls IF_SKIPPED: Health check fails when DB is slow, pod killed unnecessarily
  • [ ] CHECK: Streaming endpoints have try/catch inside callback IF_SKIPPED: Unhandled error crashes the Node.js process
  • [ ] CHECK: Streaming endpoints use stream.onAbort() for cleanup IF_SKIPPED: Resource leaks (DB connections, event listeners)
  • [ ] CHECK: No synchronous blocking in middleware or handlers IF_SKIPPED: Event loop blocked, all concurrent requests stall

DEPLOYMENT CHECKLIST (per service)

  • [ ] CHECK: Entrypoint uses @hono/node-server (NOT Bun/Deno serve) IF_SKIPPED: Service fails to start in k3s Node.js container
  • [ ] CHECK: Port reads from process.env.PORT with fallback IF_SKIPPED: Port conflict in k3s, container fails to bind
  • [ ] CHECK: Dockerfile copies package.json and runs npm ci --production IF_SKIPPED: Dev dependencies in production image, bloated container
  • [ ] CHECK: Container image rebuilt via build script before deploy IF_SKIPPED: Running stale code, kubectl cp FORBIDDEN ADDED_FROM: ge-memory-2026-02, container image rebuild mandate
  • [ ] CHECK: k8s manifest has liveness probe on /health IF_SKIPPED: Dead pod stays in rotation, serves errors
  • [ ] CHECK: k8s manifest has readiness probe on /health IF_SKIPPED: Pod receives traffic before app is ready

Cross-References

READ_ALSO: wiki/docs/stack/hono/index.md READ_ALSO: wiki/docs/stack/hono/pitfalls.md READ_ALSO: wiki/docs/stack/hono/middleware.md READ_ALSO: wiki/docs/stack/hono/patterns.md