@c9up/ream 0.2.17 → 0.2.19

package/scripts/copy-napi.mjs

@@ -21,7 +21,7 @@
 // crate listed in `NAPI_CRATES` ships in the tarball.
 
 import { copyFileSync, existsSync } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { dirname, join, resolve } from 'node:path'
 import { arch, env, platform } from 'node:process'
 import { fileURLToPath } from 'node:url'
 
@@ -48,6 +48,14 @@ const HOST_SUFFIX_MAP = {
   'win32-x64': 'win32-x64-msvc',
 }
 
+// Cargo writes its artifacts under CARGO_TARGET_DIR when that is set — a
+// shared cache, a CI mount — so they are not under this package's `target/` at
+// all. A relative value is resolved against the directory cargo ran in, which
+// is this package root.
+const targetDir = env.CARGO_TARGET_DIR
+  ? resolve(root, env.CARGO_TARGET_DIR)
+  : join(root, 'target')
+
 const triple = env.CARGO_BUILD_TARGET ?? ''
 let suffix
 let os
@@ -59,11 +67,11 @@ if (triple) {
   }
   suffix = entry.suffix
   os = entry.os
-  releaseDir = join(root, 'target', triple, 'release')
+  releaseDir = join(targetDir, triple, 'release')
 } else {
   suffix = HOST_SUFFIX_MAP[`${platform}-${arch}`]
   os = platform
-  releaseDir = join(root, 'target', 'release')
+  releaseDir = join(targetDir, 'release')
   if (!suffix) {
     throw new Error(`[ream:napi] unsupported platform/arch: ${platform}-${arch}`)
   }

package/src/Application.ts

@@ -73,6 +73,21 @@ export interface ReamrcContents {
 export class Application implements AppContext {
   readonly container: Container
   readonly config: ConfigStore
+  /**
+   * Whether the inker template engine is installed (AdonisJS `usingEdgeJS`).
+   *
+   * Set by `InkerProvider`'s CONSTRUCTOR, so it is already true by the time any
+   * other provider boots. A package that wants to contribute to templates —
+   * rosetta pushing its `t()` global, say — reads this before importing
+   * `@c9up/inker`, and stays installable without it when the answer is no.
+   *
+   * A flag rather than a container lookup, and that is the whole point: the
+   * engine is a module singleton, so asking the container would mean resolving
+   * a binding whose lifecycle has to have reached the right phase. This answers
+   * the only question the caller actually has — is the package there — without
+   * one.
+   */
+  usingInker = false
   #appRoot?: URL
   #directories: DirectoriesNode = { ...defaultDirectories }
   #rcFile: ReamrcContents = {}

package/src/HttpKernel.ts

@@ -32,6 +32,16 @@ export interface HttpKernelConfig {
   container?: Container
   exceptionHandler?: ExceptionHandler
   serverMiddleware?: MiddlewareFunction[]
+  /**
+   * A `<script>` appended to every HTML response, dev only.
+   *
+   * Set by the Ignitor when the application runs in development; `undefined`
+   * everywhere else, so a production response is byte-for-byte what the
+   * handler produced. It lives here rather than in a middleware because this
+   * is the one place every response passes through on its way out, whichever
+   * route or error handler produced it.
+   */
+  devReloadScript?: (nonce?: string) => string
   routerMiddleware?: MiddlewareFunction[]
   onError?: (error: unknown, ctx: HttpContext) => void
   debug?: boolean
@@ -345,7 +355,7 @@ export function createHttpKernel(
           correlationId,
         )
       }
-      const serialized = await serializeResponse(ctx)
+      const serialized = await serializeResponse(ctx, config.devReloadScript)
       // The body is built; anything registered with `response.onFinish()` runs
       // now — after the answer is ready, before we hand it back.
       ctx.response.runFinishCallbacks()
@@ -401,7 +411,7 @@ export function createHttpKernel(
           correlationId,
         )
       }
-      const serialized = await serializeResponse(ctx)
+      const serialized = await serializeResponse(ctx, config.devReloadScript)
       // The body is built; anything registered with `response.onFinish()` runs
       // now — after the answer is ready, before we hand it back.
       ctx.response.runFinishCallbacks()
@@ -452,15 +462,87 @@ function readControllerGuardMetadata(
   }
 }
 
-async function serializeResponse(ctx: HttpContext): Promise<HttpKernelResponse> {
+async function serializeResponse(
+  ctx: HttpContext,
+  devReloadScript?: (nonce?: string) => string,
+): Promise<HttpKernelResponse> {
   // The terminal step, as AdonisJS' server calls `response.finish()`: it
   // stamps the request id and waits for a body still being produced.
   await ctx.response.finish()
   const streamId = ctx.response.getStreamId()
+  const headers = ctx.response.getHeaders()
+  const body = withDevReloadScript(
+    ctx.response.getBody(),
+    headers,
+    streamId,
+    devReloadScript === undefined ? undefined : devReloadScript(ctx.response.nonce),
+  )
   return {
     status: ctx.response.getStatus(),
-    headers: ctx.response.getHeaders(),
-    body: ctx.response.getBody(),
+    headers: reconcileRepresentation(headers, ctx.response.getBody(), body),
+    body,
     ...(streamId !== undefined ? { streamId } : {}),
   }
 }
+
+/**
+ * Keep the representation headers describing the body that is actually sent.
+ *
+ * `content-length`, `etag` and the digest headers are computed from the body
+ * BEFORE the dev reload script is appended. Left alone they describe the
+ * previous one: a `content-length` short by the length of the script truncates
+ * it, and an `etag` computed before the change caches modified content under an
+ * unchanged validator.
+ *
+ * `content-length` is recomputed because it is cheap and exact; the validators
+ * are DROPPED rather than recomputed, because a validator this layer invents is
+ * not the one the handler meant.
+ */
+function reconcileRepresentation(
+  headers: Record<string, string>,
+  original: string,
+  sent: string,
+): Record<string, string> {
+  if (sent === original) return headers
+  const reconciled = { ...headers }
+  if (reconciled['content-length'] !== undefined) {
+    reconciled['content-length'] = String(Buffer.byteLength(sent, 'utf8'))
+  }
+  // Every validator, not the two that came to mind. `Content-Digest` and
+  // `Repr-Digest` (RFC 9530) are what replaced `Digest`, and leaving them
+  // describing the old body is the same defect one header along — a client
+  // that checks them rejects a response that is perfectly fine.
+  for (const name of [
+    'etag',
+    'content-md5',
+    'digest',
+    'content-digest',
+    'repr-digest',
+    'want-digest',
+    'want-content-digest',
+    'want-repr-digest',
+  ]) {
+    delete reconciled[name]
+  }
+  return reconciled
+}
+
+/**
+ * Append the dev reload script to an HTML body.
+ *
+ * Only HTML, and never a stream: appending to an SSE or a download would
+ * corrupt it, and a page is the only thing that can act on the script anyway.
+ * Before `</body>` when there is one, so the script is inside the document
+ * rather than trailing after it.
+ */
+function withDevReloadScript(
+  body: string,
+  headers: Record<string, string>,
+  streamId: string | undefined,
+  script?: string,
+): string {
+  if (script === undefined || streamId !== undefined || body === '') return body
+  if (!(headers['content-type'] ?? '').includes('text/html')) return body
+  const closing = body.lastIndexOf('</body>')
+  return closing === -1 ? body + script : body.slice(0, closing) + script + body.slice(closing)
+}

package/src/Ignitor.ts

@@ -17,6 +17,7 @@ import { Application } from './Application.js'
 import type { Console } from './console/Console.js'
 import type { CommandLoader, Kernel as ConsoleKernelInstance } from './console/Kernel.js'
 import { type CommandClass, isCommandClass } from './console/types.js'
+import { HMR_PATH, hmrClientScript, hmrToken } from './dev/hmr.js'
 import type { DirectoriesNode } from './directories.js'
 import type { ErrorEvent } from './ErrorBoundary.js'
 import { ErrorBoundary } from './ErrorBoundary.js'
@@ -31,6 +32,7 @@ import type { HttpKernelRequest, HttpKernelResponse } from './HttpKernel.js'
 import { createHttpKernel } from './HttpKernel.js'
 import { ExceptionHandler } from './http/Exception.js'
 import { type ChildLoggerSource, HttpContext } from './http/HttpContext.js'
+import { RequestValidator } from './http/RequestValidator.js'
 import type { MiddlewareFunction } from './middleware/Pipeline.js'
 import { MiddlewareRegistry } from './middleware/Pipeline.js'
 import { MigrationRegistry } from './migrations/MigrationRegistry.js'
@@ -325,6 +327,11 @@ export class Ignitor {
     // must stay agnostic reaches it through the container instead of importing
     // ream at runtime.
     this.#app.container.singleton('HttpContext', () => HttpContext)
+    // The seam a package installs its per-request messages provider or error
+    // reporter on. Bound rather than imported so an i18n provider can reach it
+    // without depending on ream — which is the only reason it is a container
+    // token and not just an import.
+    this.#app.container.singleton('requestValidator', () => RequestValidator)
     // `appRoot` is the URL passed to `new Ignitor(new URL('../', import.meta.url))`.
     // Providers resolve it through the container so they can interpret
     // relative paths in config files (e.g. `pages.root: './resources/pages'`)
@@ -659,6 +666,12 @@ export class Ignitor {
   }
 
   async #phaseStart(): Promise<void> {
+    // What the injected reload script polls, mounted BEFORE the socket accepts
+    // anything. Registered in `ready()` it came up after the server was already
+    // serving, so a page loaded in that window polled a route that did not
+    // exist yet.
+    this.#registerDevReloadRoute()
+
     // Providers start BEFORE the preload files, matching upstream's warm-up
     // order (`providers.start()` → `starting` hooks → preloads). A preload is
     // where an app writes its routes and kernel, and those reach for services
@@ -668,18 +681,28 @@ export class Ignitor {
       await callProviderPhase(provider, 'start')
     }
 
-    // Import preload files (routes.ts, kernel.ts, etc.)
+    // Import preload files (routes.ts, kernel.ts, etc.).
+    //
+    // Filtered on the environment first, then imported TOGETHER — upstream's
+    // `PreloadsManager.import()` is a filter followed by one `Promise.all`, and
+    // this used to walk them one at a time.
+    //
+    // The consequence is worth knowing: evaluation order between two preload
+    // files is now whichever finishes loading first, so an application cannot
+    // rely on the array's order to decide which of two overlapping routes
+    // answers. Work that must be ordered belongs inside ONE preload, where the
+    // order is the file's own — which is how upstream applications are written.
     if (this.#reamrc?.preloads) {
-      for (const preloadEntry of this.#reamrc.preloads) {
-        const preloadImport = typeof preloadEntry === 'function' ? preloadEntry : preloadEntry.file
-        const env =
-          typeof preloadEntry === 'function'
-            ? undefined
-            : (preloadEntry as { environment?: string[] }).environment
-
-        if (env && !env.includes(this.#app.getEnvironment())) continue
-        await preloadImport()
-      }
+      const applicable = this.#reamrc.preloads.filter((preloadEntry) => {
+        if (typeof preloadEntry === 'function') return true
+        const env = (preloadEntry as { environment?: string[] }).environment
+        return !env || env.includes(this.#app.getEnvironment())
+      })
+      await Promise.all(
+        applicable.map((preloadEntry) =>
+          typeof preloadEntry === 'function' ? preloadEntry() : preloadEntry.file(),
+        ),
+      )
     }
 
     // Auto-load module files (routes.ts, etc.) from modules directory
@@ -737,6 +760,7 @@ export class Ignitor {
           this.#server.getErrorHandler() ?? new ExceptionHandler(!this.#app.inProduction),
         serverMiddleware: this.#server.getServerMiddleware(),
         routerMiddleware: this.#router.getRouterMiddleware(),
+        devReloadScript: this.#devReloadScript(),
         onError: (error, ctx) => {
           this.#errorBoundary.serviceError('HttpKernel', error, ctx.id)
         },
@@ -859,11 +883,13 @@ export class Ignitor {
     // already-loaded ESM module returns the CACHED module without re-executing
     // its body (the thunk's specifier is opaque, so it cannot be cache-busted).
     // The "reload" therefore destroyed every preload-registered route on the
-    // first file save and never restored them. Process-level restart is the
-    // reload mechanism (`ream dev` runs `tsx watch`, which restarts on change);
-    // this watcher only surfaces an informational event for hosts that embed
-    // the Ignitor without a supervisor. A future true HMR needs a loader-hook
-    // (hot-hook style) that can invalidate the ESM cache — plug it in here.
+    // first file save and never restored them.
+    //
+    // Module-level reloading now happens OUTSIDE the Ignitor: `ream dev` loads
+    // `@c9up/ream/hot`, which registers hot-hook's loader and can invalidate
+    // the ESM cache — the loader hook this comment used to ask for. What is
+    // left here only surfaces an informational event for hosts that embed the
+    // Ignitor without a supervisor.
     if (this.isDevMode()) {
       const watchDirs = this.#config.watchDirs ?? ['app', 'start']
       this.#hotReloadCleanup = startHotReload({
@@ -1125,6 +1151,7 @@ export class Ignitor {
         this.#server.getErrorHandler() ?? new ExceptionHandler(!this.#app.inProduction),
       serverMiddleware: this.#server.getServerMiddleware(),
       routerMiddleware: this.#router.getRouterMiddleware(),
+      devReloadScript: this.#devReloadScript(),
     })
     return this.#kernel
   }
@@ -1135,6 +1162,33 @@ export class Ignitor {
     return this.#app.inDev
   }
 
+  /**
+   * The reload script, in development only.
+   *
+   * Gated on the environment rather than on `hot-hook` being present: the
+   * script is just as useful without it, since a restart is exactly what it
+   * detects. In production it is `undefined` and the response is untouched.
+   */
+  #devReloadScript(): ((nonce?: string) => string) | undefined {
+    return this.isDevMode() ? hmrClientScript : undefined
+  }
+
+  /**
+   * Serve the token the injected script polls.
+   *
+   * Registered on the router in development, next to the application's own
+   * routes, so it goes through the same server as everything else. Plain text
+   * and uncached: it is read once a second and its whole content is the answer.
+   */
+  #registerDevReloadRoute(): void {
+    if (!this.isDevMode()) return
+    this.#router.get(HMR_PATH, ({ response }) => {
+      response.header('cache-control', 'no-store')
+      response.header('content-type', 'text/plain; charset=utf-8')
+      response.send(hmrToken())
+    })
+  }
+
   getPhase(): string {
     return this.#phase
   }

package/src/Provider.ts

@@ -32,6 +32,21 @@ export interface ConfigReader {
 export interface AppContext {
   container: Container
   config: ConfigReader
+  /**
+   * Whether the inker template engine is installed — see
+   * `Application#usingInker`. Optional here because a host that is not ream
+   * satisfies this contract structurally and has no such flag; a provider
+   * reading it treats `undefined` as "no engine".
+   */
+  usingInker?: boolean
+  /**
+   * Absolute path to the application's `public/` directory — see
+   * `Application#publicPath`. Optional for the same reason as the flag above:
+   * a host that is not ream satisfies this contract structurally and has no
+   * directory layout. A provider that needs it falls back to a relative
+   * `'public'`, resolved against the working directory.
+   */
+  publicPath?(...paths: string[]): string
 }
 
 /**