@c9up/ream 0.2.16 → 0.2.18

package/src/openapi/OpenApiProvider.ts

@@ -1,11 +1,12 @@
 /**
  * `OpenApiProvider` — serves an auto-generated OpenAPI 3.1 spec + Swagger UI.
  *
- * `boot()` mounts a global middleware that, on the first GET to `/api-docs`
+ * `start()` mounts a global middleware that, on the first GET to `/api-docs`
  * (JSON) or `/docs` (Swagger UI), lazily generates the spec from the router's
- * registered routes — so every route registered during boot/start is included
- * (the spec must NOT be generated eagerly at boot, before other providers have
- * registered their routes). Opt-out via `config.openapi.enabled = false`.
+ * registered routes — so every route registered while the application starts
+ * up is included (the spec must NOT be generated eagerly, before the other
+ * providers and the preloads have registered their routes). Opt-out via
+ * `config.openapi.enabled = false`.
  *
  * @implements Story 24.4
  */
@@ -43,7 +44,17 @@ export class OpenApiProvider extends Provider {
     this.#override = options.generator
   }
 
-  override async boot(): Promise<void> {
+  /**
+   * Routes and server middleware go in `start`, not `boot`.
+   *
+   * Upstream documents that phase for exactly this, and the order is what makes
+   * it matter: providers boot, then providers START, then the preloads run —
+   * and the preloads are where an application writes its own routes and kernel.
+   * Mounted in `boot`, a framework route landed ahead of every application
+   * route, so an overlapping path was answered by the framework rather than by
+   * the app that meant to override it.
+   */
+  override async start(): Promise<void> {
     const config = this.app.config.get<OpenApiDocsConfig>('openapi') ?? {}
     if (config.enabled === false) return
 
@@ -59,10 +70,14 @@ export class OpenApiProvider extends Provider {
 
   async #buildGenerator(config: OpenApiDocsConfig): Promise<OpenApiGenerator> {
     const router = await this.app.container.make<Router>('router')
-    return new OpenApiGenerator(router, {
+    const generator = new OpenApiGenerator(router, {
       title: config.title ?? 'API',
       version: config.version ?? '1.0.0',
     })
+    // The routes already name their validators; ask each one to describe
+    // itself instead of making the app repeat the shape by hand.
+    await generator.hydrateSchemas((token) => this.app.container.make<unknown>(token))
+    return generator
   }
 }
 

package/src/rpc/RpcProvider.ts

@@ -9,8 +9,9 @@
  *       rpc.method('task.validate', handler).guard('jwt')
  *       rpc.namespace('user', UserController)
  *
- *   - `boot()` — mount `POST <config.rpc.path ?? '/rpc'>` on the core router,
+ *   - `start()` — mount `POST <config.rpc.path ?? '/rpc'>` on the core router,
  *     dispatching every request body (single or batch) to `RpcRouter.handle()`.
+ *     In `start`, which is the phase upstream documents for routes.
  *
  * @implements Story 24.1, 24.2
  */
@@ -68,7 +69,17 @@ export class RpcProvider extends Provider {
     this.#registered = true
   }
 
-  override async boot(): Promise<void> {
+  /**
+   * Routes and server middleware go in `start`, not `boot`.
+   *
+   * Upstream documents that phase for exactly this, and the order is what makes
+   * it matter: providers boot, then providers START, then the preloads run —
+   * and the preloads are where an application writes its own routes and kernel.
+   * Mounted in `boot`, a framework route landed ahead of every application
+   * route, so an overlapping path was answered by the framework rather than by
+   * the app that meant to override it.
+   */
+  override async start(): Promise<void> {
     const config = this.app.config.get<RpcConfig>('rpc')
     const path = config?.path ?? '/rpc'
     const router = await this.app.container.make<Router>('router')

package/src/storage/StaticProvider.ts

@@ -2,7 +2,7 @@
  * `StaticProvider` — serves static files from a directory.
  *
  * Opt-in: does nothing unless `config.static.root` is set (or a middleware is
- * injected for tests). When configured, `boot()` mounts a global
+ * injected for tests). When configured, `start()` mounts a global
  * `StaticMiddleware` (path-traversal + symlink-escape guarded) that serves
  * matching requests and falls through (`next()`) otherwise.
  *
@@ -30,7 +30,17 @@ export class StaticProvider extends Provider {
     this.#override = options.middleware
   }
 
-  override async boot(): Promise<void> {
+  /**
+   * Routes and server middleware go in `start`, not `boot`.
+   *
+   * Upstream documents that phase for exactly this, and the order is what makes
+   * it matter: providers boot, then providers START, then the preloads run —
+   * and the preloads are where an application writes its own routes and kernel.
+   * Mounted in `boot`, a framework route landed ahead of every application
+   * route, so an overlapping path was answered by the framework rather than by
+   * the app that meant to override it.
+   */
+  override async start(): Promise<void> {
     const config = this.app.config.get<StaticConfig>('static')
     const middleware = this.#override ?? (config?.root ? new StaticMiddleware(config) : undefined)
     if (!middleware) return // not configured — opt-out