@quilla-be-kit/http 0.4.0 → 0.6.0

package/README.md

@@ -147,27 +147,78 @@ await runtime.run(async () => {
 
 ## Decorators
 
-### `@Controller(prefix)`
+### `@Controller(prefix, options?)`
 
-Class decorator. Every route on the class gets `prefix` prepended.
+Class decorator. Every route on the class gets `prefix` prepended. The optional
+second argument carries a controller-level **version** default (see
+[Versioning](#versioning)).
 
 ```ts
 @Controller('/users')
 class UsersController { ... }
+
+@Controller('/users', { version: '/api/v1' })   // controller-wide version default
+class UsersController { ... }
 ```
 
 ### HTTP method decorators
 
 ```ts
-@Get(path)          @GetPublic(path)
-@Post(path)         @PostPublic(path)
-@Put(path)          @PutPublic(path)
-@Patch(path)        @PatchPublic(path)
-@Delete(path)       @DeletePublic(path)
+@Get(path, options?)          @GetPublic(path, options?)
+@Post(path, options?)         @PostPublic(path, options?)
+@Put(path, options?)          @PutPublic(path, options?)
+@Patch(path, options?)        @PatchPublic(path, options?)
+@Delete(path, options?)       @DeletePublic(path, options?)
 ```
 
 The `*Public` variants mark the route as public — **auth middlewares are skipped** for these routes. The non-public variants run every registered `authMiddleware` before the handler.
 
+The optional `options` argument (`RouteOptions`) carries a per-route **version**
+override (see [Versioning](#versioning)):
+
+```ts
+@Get('/:id', { version: '/api/v2' })
+```
+
+### Versioning
+
+A version segment can be declared at three levels and is inserted
+**resource-first** into the composed path — after the module prefix, before the
+controller — so each module stays a clean future service boundary:
+
+```
+[module prefix] + [effective version] + [registration prefix] + [@Controller prefix] + [@Route path]
+```
+
+The effective version for a route resolves by precedence:
+
+```
+route option  ??  @Controller version  ??  HttpModuleMeta.version  ??  ''
+```
+
+- `HttpModuleMeta.version?` — module-wide default (see the [registry bridge](#bridge-to-componentregistryhttpmodulemeta)).
+- `@Controller(prefix, { version })` — controller-level default.
+- `@Get('/x', { version })` — per-route override (available on every method + `*Public` decorator).
+
+```ts
+@Controller('/auth', { version: '/api/v1' })   // default for the whole controller
+class AuthController {
+  @Get('/:id')                                 // → /iam/api/v1/auth/:id  (module prefix /iam)
+  async show() {}
+
+  @Get('/:id', { version: '/api/v2' })         // → /iam/api/v2/auth/:id  (route override)
+  async showV2() {}
+}
+```
+
+Version segments go through the same leading-slash / no-trailing-slash
+normalization as every other segment (`/iam` + `api/v1` → `/iam/api/v1`, no double
+slash). They are static, so they only **add** specificity and never trigger a
+false duplicate; two routes that differ only by version resolve to distinct
+paths. Version is orthogonal to `*Public` / auth — it affects the path only.
+When no version is set anywhere, composed paths are byte-identical to a service
+that never adopted versioning.
+
 ### `@AuthorizeScope(scope, mode?)`
 
 Scope-based authorization. Reads an `AuthenticatedToken` from `request.getAttribute(HttpAttributes.VERIFIED_TOKEN)` and checks the token's `scopes` against the required scope(s).
@@ -197,7 +248,7 @@ async create(req: HttpRequest): Promise<HttpResponse> {
 }
 ```
 
-On validation failure, throws `ValidationError` with `context.issues` containing the validator's raw error array (e.g. Zod issues, Joi details). `resolveHttpError` surfaces this as a 400 response with `body.error.details.issues`.
+On validation failure, throws `ValidationError` with `context.issues` containing the validator's raw error array (e.g. Zod issues, Joi details). The default error resolver (`DefaultErrorResolver`) surfaces this as a 400 response with `body.error.details.issues`. See [Response and error conventions](#response-and-error-conventions) to override the wire shape.
 
 ## Multipart / form-data
 
@@ -269,7 +320,7 @@ async export(req: HttpRequest): Promise<HttpStreamResponse> {
 
 **The real tradeoff is that binary responses lose the envelope convention — no `payload` / `metadata` wrapper around the bytes, and middleware can't introspect stream contents post-hoc.** That's intrinsic to streaming, not a flaw: logging, response shaping, and validators that read response bodies all become no-ops on the binary path. You're opting out of the standard JSON shape so the framework can hand bytes directly to the socket.
 
-Error handling caveat: a handler that throws **before** producing the response still goes through `resolveHttpError` and emits a normal JSON error envelope. A handler that throws **mid-stream** — after the response status is already committed — aborts the connection; the client sees a truncated body, not a JSON error.
+Error handling caveat: a handler that throws **before** producing the response still goes through the configured error resolver (`DefaultErrorResolver` by default) and emits a normal JSON error envelope. A handler that throws **mid-stream** — after the response status is already committed — aborts the connection; the client sees a truncated body, not a JSON error.
 
 ## `RequestValidator` adapter
 
@@ -350,7 +401,7 @@ const router = new Router({
 
 - Controllers can be registered as plain instances (no extra metadata) or wrapped in `{ controller, prefix?, middlewares? }` for per-controller prefix + middlewares.
 - Routes are sorted by **specificity** (static segments > parametric > wildcard) so `/users/healthz` matches before `/users/:id`.
-- Path composition: `[module prefix] + [registration prefix] + [@Controller prefix] + [@Route path]`, normalized to a single leading slash and no trailing slash.
+- Path composition: `[module prefix] + [effective version] + [registration prefix] + [@Controller prefix] + [@Route path]`, normalized to a single leading slash and no trailing slash. The **effective version** is resource-first and resolves `route option ?? @Controller version ?? HttpModuleMeta.version ?? ''` — see [Versioning](#versioning).
 - Duplicate routes (same method + path) throw at construction time — you catch double-registrations at startup, not under load.
 
 ### Middleware chain order
@@ -385,7 +436,8 @@ registry
   .register({
     name: 'iam',
     meta: {
-      prefix: '/api/v1',
+      prefix: '/iam',
+      version: '/api/v1',                       // module-wide default; routes/controllers can override
       controllers: [usersController, authController],
       middlewares: [iamModuleMw],
     },
@@ -394,7 +446,8 @@ registry
   .register({
     name: 'dm',
     meta: {
-      prefix: '/api/v1',
+      prefix: '/dm',
+      version: '/api/v1',
       controllers: [documentsController],
     },
   });
@@ -447,6 +500,7 @@ const server = new HonoServer({
   router,                 // HonoServer reads the execution-context provider from Router
   requestValidator,       // optional — required only if any route uses @ValidateRequest
   logger,                 // optional — used for startup/shutdown/error logs
+  conventions,            // optional — override the error / success wire shapes (see below)
   serve: honoServe,
 });
 ```
@@ -483,6 +537,99 @@ Defaults applied when `cors` is set:
 
 If you need non-default values, omit `cors` and wire `hono/cors` yourself inside the `serve` callback, or raise an issue.
 
+### Response and error conventions
+
+The success/envelope shape and the error shape are both consumer-overridable through the
+optional `conventions` facade on `HonoServer`. It groups two strategies, each defaulting to a
+class that reproduces the built-in wire shape byte-for-byte — omit `conventions` and nothing
+changes.
+
+```ts
+type HttpConventions = {
+  readonly errorResolver?: ErrorResolver;           // controls the error status + body
+  readonly responseSerializer?: ResponseSerializer; // controls the JSON success/envelope body
+};
+
+interface ErrorResolver {
+  resolve(err: unknown): ResolvedHttpError;          // { httpCode, body }
+}
+interface ResponseSerializer {
+  serialize(response: HttpJsonResponse): unknown;    // return the wire body, or undefined for no body
+}
+```
+
+Defaults are exported so a custom strategy can delegate to them: `DefaultErrorResolver` (the
+status mapping — `ValidationError` → 400, `NotFoundError` → 404, …) and `DefaultResponseSerializer`
+(strips `httpCode`/`headers`, keeps `payload` / `error` / `metadata`, and returns `undefined`
+for an empty body so it becomes a bodyless response).
+
+**Custom error format** — e.g. RFC 7807 Problem Details, reusing the default status mapping:
+
+```ts
+import {
+  DefaultErrorResolver,
+  type ErrorResolver,
+  type ResolvedHttpError,
+} from '@quilla-be-kit/http';
+
+class ProblemDetailsResolver implements ErrorResolver {
+  private readonly base = new DefaultErrorResolver();
+
+  resolve(err: unknown): ResolvedHttpError {
+    const { httpCode, body } = this.base.resolve(err);   // reuse status mapping
+    return {
+      httpCode,
+      body: {
+        error: {
+          name: 'about:blank',
+          message: body.error?.message ?? 'Error',
+          details: { status: httpCode, ...(body.error?.details ?? {}) },
+        },
+      },
+    };
+  }
+}
+
+const server = new HonoServer({
+  port: 3000,
+  router,
+  serve: honoServe,
+  conventions: { errorResolver: new ProblemDetailsResolver() },
+});
+```
+
+**Custom success envelope** — e.g. rename `payload` → `data` and lift pagination to the top level:
+
+```ts
+import {
+  type HttpJsonResponse,
+  type ResponseSerializer,
+} from '@quilla-be-kit/http';
+
+class DataEnvelopeSerializer implements ResponseSerializer {
+  serialize(r: HttpJsonResponse): unknown {
+    if (r.error) return { error: r.error };
+    if (r.payload === undefined) return undefined;       // preserve the bodyless-response branch
+    const p = r.metadata?.pagination;
+    return {
+      data: r.payload,
+      ...(p ? { pagination: { page: p.page, perPage: p.limit, total: p.total } } : {}),
+    };
+  }
+}
+
+const server = new HonoServer({
+  port: 3000,
+  router,
+  serve: honoServe,
+  conventions: { responseSerializer: new DataEnvelopeSerializer() },
+});
+```
+
+The binary/stream response paths never touch the serializer — they still write bytes directly.
+On the frontend, `@quilla-fe-kit/api-client-react-query` reconciles a custom envelope with a
+`queryTransformer`, and `@quilla-fe-kit/api-client` a custom error shape with an `errorParser`.
+
 ## Other frameworks
 
 If you need Express or Fastify: open an issue. Adapter sub-paths ship as library additions when they exist, not as consumer extension points.