@c9up/ream 0.2.27 → 0.2.29

package/src/Codemods.ts

@@ -1,9 +1,36 @@
 import * as fs from 'node:fs'
 import * as path from 'node:path'
+import {
+  appendToLiteral,
+  findCall,
+  findExportDefaultObject,
+  isSingleExpression,
+  matchClose,
+  properties,
+  segments,
+} from './codemods/source.js'
 import { render as renderTemplate, type StubState } from './stubs/template.js'
 
 export type { StubState }
 
+/** The environments a preload (or provider) entry can be scoped to. */
+export type PreloadEnvironment = 'web' | 'console' | 'test' | 'repl'
+
+const PRELOAD_ENVIRONMENTS: readonly PreloadEnvironment[] = ['web', 'console', 'test', 'repl']
+
+/** Validation rules a configure hook adds to `start/env.ts`. */
+export interface EnvValidationNode {
+  /** Written once, as a banner comment above the rules this call adds. */
+  leadingComment?: string
+  /** Variable name → rule source, e.g. `{ REDIS_PORT: 'Env.schema.number()' }`. */
+  variables: Record<string, string>
+  /**
+   * Replace a rule the file already has. Off by default, so a rule the user
+   * edited survives a re-run; configure hooks pass their `--force` flag.
+   */
+  overwrite?: boolean
+}
+
 export interface Codemods {
   addProvider(importPath: string): Promise<void>
   addMetaFile(pattern: string, reloadServer?: boolean): Promise<void>
@@ -17,6 +44,8 @@ export interface Codemods {
   ): Promise<GeneratedStub>
   registerCommand(importPath: string): Promise<void>
   registerMiddleware(importPath: string, options?: { tier?: 'server' | 'router' }): Promise<void>
+  defineEnvValidations(definition: EnvValidationNode): Promise<string[]>
+  addPreloadFile(modulePath: string, environments?: PreloadEnvironment[]): Promise<void>
 }
 
 /** What a stub may interpolate. Scalars only — a stub is text, not a program. */
@@ -128,6 +157,76 @@ function assertCanonicallyInside(root: string, filePath: string, displayName: st
   }
 }
 
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+/**
+ * A module path goes between the quotes of an `import('...')`; anything that
+ * could close them, escape or end the line is refused rather than escaped.
+ */
+const SAFE_MODULE_PATH = /^[^'"`\\\r\n\u2028\u2029]+$/
+
+const BANNER_RULE = '|----------------------------------------------------------'
+
+/** The rules of `definition`, refused before anything is written when unsafe. */
+function assertEnvValidations(definition: EnvValidationNode): void {
+  const comment = definition.leadingComment
+  if (comment !== undefined && (/[\r\n\u2028\u2029]/.test(comment) || comment.includes('*/'))) {
+    throw new Error(
+      '[configure] defineEnvValidations: the leading comment must be one line without `*/`',
+    )
+  }
+  for (const [name, rule] of Object.entries(definition.variables)) {
+    if (!ENV_NAME.test(name)) {
+      throw new Error(
+        `[configure] defineEnvValidations: '${name}' is not an environment variable name`,
+      )
+    }
+    if (typeof rule !== 'string' || !isSingleExpression(rule)) {
+      throw new Error(
+        `[configure] defineEnvValidations: the rule for ${name} is not one complete expression: ${String(rule)}`,
+      )
+    }
+  }
+}
+
+/** The `{` and `}` of the schema object passed to `Env.create`. */
+function locateEnvSchema(content: string): { open: number; close: number } {
+  const paren = findCall(content, 'Env.create')
+  const parenClose = paren === -1 ? -1 : matchClose(content, paren)
+  if (paren === -1 || parenClose === -1) {
+    throw new Error(
+      '[configure] Could not find an Env.create(...) call in start/env.ts — add the validations by hand.',
+    )
+  }
+  const open = segments(content, paren + 1, parenClose)[1]?.codeStart ?? -1
+  const close = content[open] === '{' ? matchClose(content, open) : -1
+  if (close === -1) {
+    throw new Error(
+      '[configure] The second argument of Env.create in start/env.ts is not an object literal — add the validations by hand.',
+    )
+  }
+  return { open, close }
+}
+
+/** The `{` and `}` of the object `reamrc.ts` exports (through `defineConfig` or bare). */
+function locateRcObject(content: string): { open: number; close: number } | null {
+  const paren = findCall(content, 'defineConfig')
+  let open = -1
+  if (paren !== -1) {
+    const parenClose = matchClose(content, paren)
+    if (parenClose !== -1) open = segments(content, paren + 1, parenClose)[0]?.codeStart ?? -1
+  } else {
+    open = findExportDefaultObject(content)
+  }
+  const close = open !== -1 && content[open] === '{' ? matchClose(content, open) : -1
+  return close === -1 ? null : { open, close }
+}
+
+/** The module an rc array element lazily imports. */
+function importedModule(element: string): string | undefined {
+  return /import\s*\(\s*(['"])([^'"]*)\1\s*\)/.exec(element)?.[2]
+}
+
 export function createCodemods(options?: { force?: boolean; cwd?: string }): Codemods {
   const force = options?.force ?? false
   const root = path.resolve(options?.cwd ?? process.cwd())
@@ -516,5 +615,171 @@ export function createCodemods(options?: { force?: boolean; cwd?: string }): Cod
       content = `${content.slice(0, targetBlock.start)}${eol}${entry}${content.slice(targetBlock.start)}`
       fs.writeFileSync(kernelPath, content)
     },
+
+    /**
+     * Add validation rules to the schema `start/env.ts` passes to
+     * `Env.create`, so the variables a package writes to `.env` are checked
+     * at boot like the app's own.
+     *
+     * A rule already in the file is left alone, unless `overwrite` is set:
+     * the user may have tightened it. Returns the variables kept that way
+     * with a rule different from the one asked for, so the caller can say
+     * so. The banner comment is written only when the first new rule comes
+     * before any variable the file already had.
+     */
+    async defineEnvValidations(definition: EnvValidationNode): Promise<string[]> {
+      const envPath = path.join(root, 'start', 'env.ts')
+      if (!fs.existsSync(envPath)) {
+        throw new Error(
+          `[configure] start/env.ts not found — cannot add the validations for ${Object.keys(definition.variables).join(', ')}.`,
+        )
+      }
+      assertCanonicallyInside(root, envPath, 'start/env.ts')
+      assertEnvValidations(definition)
+
+      const original = fs.readFileSync(envPath, 'utf8')
+      const eol = detectLineEnding(original)
+      let content = original
+      const schema = locateEnvSchema(content)
+      const existing = new Map(
+        properties(content, schema.open, schema.close).map((property) => [property.key, property]),
+      )
+
+      const kept: string[] = []
+      const replacements: Array<{ start: number; end: number; text: string }> = []
+      const additions: Array<[string, string]> = []
+      let shouldAddComment = true
+      let decorate = false
+      for (const [name, rule] of Object.entries(definition.variables)) {
+        const property = existing.get(name)
+        if (property === undefined) {
+          if (additions.length === 0) decorate = shouldAddComment
+          shouldAddComment = false
+          additions.push([name, rule])
+          continue
+        }
+        shouldAddComment = false
+        const current = content.slice(property.valueStart, property.valueEnd)
+        if (definition.overwrite) {
+          replacements.push({ start: property.valueStart, end: property.valueEnd, text: rule })
+        } else if (current.replace(/\s+/g, '') !== rule.replace(/\s+/g, '')) {
+          kept.push(name)
+        }
+      }
+
+      for (const { start, end, text } of replacements.sort((a, b) => b.start - a.start)) {
+        content = `${content.slice(0, start)}${text}${content.slice(end)}`
+      }
+
+      if (additions.length > 0) {
+        const { open, close } = locateEnvSchema(content)
+        const comment = definition.leadingComment
+        content = appendToLiteral(
+          content,
+          open,
+          close,
+          eol,
+          (indent) => [
+            ...(decorate && comment !== undefined
+              ? [
+                  `${indent}/*`,
+                  `${indent}${BANNER_RULE}`,
+                  `${indent}| ${comment}`,
+                  `${indent}${BANNER_RULE}`,
+                  `${indent}*/`,
+                ]
+              : []),
+            ...additions.map(([name, rule]) => `${indent}${name}: ${rule},`),
+          ],
+          decorate,
+        )
+      }
+
+      if (content !== original) fs.writeFileSync(envPath, content)
+      return kept
+    },
+
+    /**
+     * Register a preload file in `reamrc.ts`, appended to `preloads` (the
+     * array is created when absent). Listing only some environments writes
+     * a `{ file, environment }` entry; none, or all of them, a plain lazy
+     * import. A module already in `preloads` is left as it is.
+     */
+    async addPreloadFile(modulePath: string, environments?: PreloadEnvironment[]): Promise<void> {
+      if (!SAFE_MODULE_PATH.test(modulePath)) {
+        throw new Error(`[configure] Unsafe preload module path: ${JSON.stringify(modulePath)}`)
+      }
+      for (const environment of environments ?? []) {
+        if (!PRELOAD_ENVIRONMENTS.includes(environment)) {
+          throw new Error(
+            `[configure] Unknown environment '${String(environment)}' for preload ${modulePath}. Expected one of ${PRELOAD_ENVIRONMENTS.join(', ')}.`,
+          )
+        }
+      }
+
+      const rcPath = path.join(root, 'reamrc.ts')
+      if (!fs.existsSync(rcPath)) {
+        throw new Error(
+          `[configure] reamrc.ts not found — cannot register preload ${modulePath}. Run 'ream new' first.`,
+        )
+      }
+      assertCanonicallyInside(root, rcPath, 'reamrc.ts')
+
+      const content = fs.readFileSync(rcPath, 'utf8')
+      const eol = detectLineEnding(content)
+      const config = locateRcObject(content)
+      if (config === null) {
+        throw new Error(
+          `[configure] Could not find 'defineConfig({ ... })' in reamrc.ts — preload ${modulePath} not added.`,
+        )
+      }
+
+      // Scoped only when it actually leaves an environment out.
+      const scope = PRELOAD_ENVIRONMENTS.some(
+        (environment) => environments !== undefined && !environments.includes(environment),
+      )
+        ? environments
+        : undefined
+      const entry = (indent: string): string[] =>
+        scope
+          ? [
+              `${indent}{`,
+              `${indent}  file: () => import('${modulePath}'),`,
+              `${indent}  environment: [${scope.map((e) => `'${e}'`).join(', ')}],`,
+              `${indent}},`,
+            ]
+          : [`${indent}() => import('${modulePath}'),`]
+
+      const preloads = properties(content, config.open, config.close).find(
+        (property) => property.key === 'preloads',
+      )
+      if (preloads === undefined) {
+        fs.writeFileSync(
+          rcPath,
+          appendToLiteral(content, config.open, config.close, eol, (indent) => [
+            `${indent}preloads: [`,
+            ...entry(`${indent}  `),
+            `${indent}],`,
+          ]),
+        )
+        return
+      }
+
+      const arrayClose =
+        content[preloads.valueStart] === '[' ? matchClose(content, preloads.valueStart) : -1
+      if (arrayClose === -1) {
+        throw new Error(
+          `[configure] reamrc.ts declares preloads as something other than an array literal — add ${modulePath} by hand.`,
+        )
+      }
+      const registered = segments(content, preloads.valueStart + 1, arrayClose).some(
+        (element) => importedModule(content.slice(element.codeStart, element.end)) === modulePath,
+      )
+      if (registered) return
+      fs.writeFileSync(
+        rcPath,
+        appendToLiteral(content, preloads.valueStart, arrayClose, eol, entry),
+      )
+    },
   }
 }

package/src/Ignitor.ts

@@ -14,6 +14,7 @@
  */
 
 import { Application } from './Application.js'
+import type { BodyParserConfig } from './bodyparser/BodyParserMiddleware.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'
@@ -51,13 +52,20 @@ import {
 import { Router } from './router/Router.js'
 import { CookieSigner } from './security/CookieSigner.js'
 import { SignedUrl } from './security/SignedUrl.js'
-import { Server } from './server/Server.js'
+import { cancellableGrpc, type NativeGrpcHandler } from './server/nativeGrpc.js'
+import {
+  type NativeBodyLimits,
+  type NativeConnectionConfig,
+  nativeBodyLimits,
+  nativeConnectionConfig,
+} from './server/nativeLimits.js'
+import { type GrpcLimits, Server } from './server/Server.js'
 import { clearApp, setApp } from './services/app.js'
 import { clearEncryption, setEncryption } from './services/encryption.js'
 import { clearLogger, setLogger } from './services/logger.js'
 import { clearRouter, setRouter } from './services/router.js'
 import { clearServer, setServer } from './services/server.js'
-import { registerSessionTemplateTags } from './session/templateTags.js'
+import { installSessionTemplateTags } from './session/templateTags.js'
 
 /** Application environment. */
 /**
@@ -268,6 +276,10 @@ export function defineConfig(config: ReamrcConfig): ReamrcConfig {
 /** Minimal interface for the HTTP server (NAPI or mock). */
 export interface HyperServerLike {
   onRequest(callback: (request: HttpKernelRequest) => Promise<HttpKernelResponse>): void
+  /** Optional — present on the real `HyperServer`; required once `server.grpc()` is used. */
+  onGrpc?(callback: NativeGrpcHandler, limits?: GrpcLimits): void
+  /** Optional — reports the calls a client gave up on; without it no call's signal aborts. */
+  onGrpcCancel?(callback: (id: number) => void): void
   /**
    * Optional — present on the real `HyperServer` (Rust-backed), absent on
    * trivial test mocks. Ignitor only calls it when a shield config is set.
@@ -277,6 +289,10 @@ export interface HyperServerLike {
   configureTrustedProxies?(cidrs: string[]): void
   /** Optional — same lifecycle as `configureShield`. */
   configureRateLimit?(config: { max: number; windowSecs: number } | null): void
+  /** Optional — same lifecycle as `configureShield`. */
+  configureBodyLimits?(config: NativeBodyLimits): void
+  /** Optional — same lifecycle as `configureShield`. */
+  configureConnections?(config: NativeConnectionConfig): void
   listen(): Promise<void>
   port(): Promise<number>
   close(): Promise<void>
@@ -682,26 +698,12 @@ export class Ignitor {
 
   /**
    * Give the template engine `@error` / `@errors` / `@inputError` /
-   * `@flashMessage`, as AdonisJS's session plugin does.
-   *
-   * The engine is duck-typed out of the container so ream carries no dependency
-   * on it, and an app with no template layer simply skips this.
+   * `@flashMessage`, as AdonisJS's session plugin does — through the engine
+   * package's module singleton, guarded by `usingInker` (see
+   * `installSessionTemplateTags`). An app with no template layer skips this.
    */
   async #registerSessionTemplateTags(): Promise<void> {
-    for (const token of ['inker', 'view']) {
-      if (!this.#app.container.has(token)) continue
-      const binding: unknown = await this.#app.container.resolve(token)
-      for (const candidate of [binding, Reflect.get(Object(binding), '_templates')]) {
-        const register = Reflect.get(Object(candidate), 'registerTag')
-        if (typeof register !== 'function') continue
-        registerSessionTemplateTags({
-          registerTag: (tag) => {
-            register.call(candidate, tag)
-          },
-        })
-        return
-      }
-    }
+    await installSessionTemplateTags(this.#app.usingInker === true)
   }
 
   async #phaseRegister(): Promise<void> {
@@ -903,6 +905,19 @@ export class Ignitor {
         this.#config.host ?? process.env.HOST ?? (this.#app.inProduction ? '0.0.0.0' : 'localhost')
       this.#_httpServer = this.#config.serverFactory(availablePort, this.#host)
       this.#_httpServer.onRequest(kernel)
+      const grpc = this.#server.getGrpcHandler()
+      if (grpc) {
+        if (typeof this.#_httpServer.onGrpc !== 'function') {
+          throw new ReamError(
+            'E_IGNITOR_GRPC_UNSUPPORTED',
+            'A gRPC handler is registered, but this server cannot serve gRPC.',
+            { hint: 'Use the native HyperServer, or a test server that implements onGrpc().' },
+          )
+        }
+        const calls = cancellableGrpc(grpc)
+        this.#_httpServer.onGrpcCancel?.(calls.onCancel)
+        this.#_httpServer.onGrpc(calls.onCall, this.#server.getGrpcLimits())
+      }
       // Pre-resolve client IPs in Rust from the trusted-proxy CIDRs before
       // listen. Security filtering itself lives in @c9up/blackhole.
       const trustedProxies = this.#server.getTrustedProxies()
@@ -912,6 +927,19 @@ export class Ignitor {
       ) {
         this.#_httpServer.configureTrustedProxies([...trustedProxies])
       }
+      // Body limits from `config/bodyparser.ts`, enforced while the native
+      // server reads a body: nothing past them is ever buffered.
+      const bodyparser = this.#app.config.get<BodyParserConfig>('bodyparser')
+      if (bodyparser && typeof this.#_httpServer.configureBodyLimits === 'function') {
+        this.#_httpServer.configureBodyLimits(nativeBodyLimits(bodyparser))
+      }
+      // AdonisJS `config/app.ts` → `http: { headersTimeout, requestTimeout,
+      // keepAliveTimeout }`, plus `maxConnections`.
+      if (typeof this.#_httpServer.configureConnections === 'function') {
+        this.#_httpServer.configureConnections(
+          nativeConnectionConfig(this.#app.config.get<unknown>('app.http')),
+        )
+      }
       await this.#_httpServer.listen()
 
       // Whoever opened the socket closes it. `app.terminate()` runs the

package/src/bodyparser/BodyParserMiddleware.ts

@@ -136,6 +136,9 @@ export default class BodyParserMiddleware {
     }
 
     const contentType = ctx.request.header('content-type') ?? ''
+    // A body over its native limit (`bodyTooLarge`) was never kept: `raw()`
+    // throws the same 413 below instead of handing back an empty string. The
+    // route is already matched here, so an unknown URL answered 404 first.
     const rawBody = ctx.request.raw()
 
     // Size check. Thrown rather than written: the app's exception handler

package/src/bodyparser/qsParse.ts

@@ -11,7 +11,7 @@
  * dependency it can write in a screenful, and the limits below are easier to
  * defend when they are visible.
  *
- * Three guards, all of which `qs` also applies:
+ * Four guards, all of which `qs` also applies:
  *
  *  - **Prototype keys are dropped.** `__proto__[x]=1` in a form body is the
  *    classic prototype-pollution vector; the key never reaches an object.
@@ -19,11 +19,14 @@
  *    as a literal key rather than allocating unbounded nesting.
  *  - **Parameter count is capped** (`qs` defaults to 1000), so a body of a
  *    million `a[0]`, `a[1]`… cannot be turned into a million-entry object.
+ *  - **Explicit array indices are capped** (`qs` `arrayLimit`, default 20).
+ *    A larger index is an object key, so `ids[4294967294]=1` stays one entry.
  */
 
 /** `qs` defaults, reproduced so the behaviour is the same out of the box. */
 export const DEFAULT_DEPTH = 5
 export const DEFAULT_PARAMETER_LIMIT = 1000
+export const DEFAULT_ARRAY_LIMIT = 20
 
 export interface QsParseOptions {
   /**
@@ -34,6 +37,12 @@ export interface QsParseOptions {
   allowDots?: boolean
   depth?: number
   parameterLimit?: number
+  /**
+   * Highest explicit index + 1 that still builds an array (`qs` defaults to
+   * 20). `ids[25]=x` becomes `{ ids: { '25': 'x' } }`, so a 16-byte request
+   * cannot allocate a 100-million-slot array.
+   */
+  arrayLimit?: number
   /** Turn `''` into `null`, as AdonisJS' `convertEmptyStringsToNull` does. */
   convertEmptyStringsToNull?: boolean
   /** Trim surrounding whitespace, as AdonisJS' `trimWhitespaces` does. */
@@ -77,15 +86,53 @@ function isIndex(segment: string): boolean {
   return /^\d+$/.test(segment)
 }
 
-/** Assign `value` at `segments` inside `target`, creating containers as needed. */
-function assign(target: Record<string, unknown>, segments: string[], value: unknown): void {
-  let cursor: Record<string, unknown> | unknown[] = target
+type Container = Record<string, unknown> | unknown[]
+
+function isContainer(value: unknown): value is Container {
+  return typeof value === 'object' && value !== null
+}
+
+/** `{ '0': a, '1': b }` from `[a, b]`, holes left out — what `qs` produces on overflow. */
+function arrayToObject(array: unknown[]): Record<string, unknown> {
+  const object: Record<string, unknown> = {}
+  array.forEach((item, index) => {
+    object[String(index)] = item
+  })
+  return object
+}
+
+/**
+ * Assign `value` at `segments` inside `target`, creating containers as needed.
+ *
+ * An explicit index at or above `arrayLimit` never addresses an array: the
+ * container becomes (or is converted into) an object keyed by that index,
+ * as `qs` does. Without it, `ids[100000000]=1` allocates a sparse array whose
+ * iteration or serialisation blocks the event loop for seconds. Appends
+ * (`tags[]`, a repeated key) stay arrays — each one costs a parameter, so
+ * `parameterLimit` already bounds them, and a long checkbox group keeps the
+ * shape its handler expects (`qs` turns those into objects past the limit).
+ */
+function assign(
+  target: Record<string, unknown>,
+  segments: string[],
+  value: unknown,
+  arrayLimit: number,
+): void {
+  let cursor: Container = target
+  // Swaps `cursor` inside its parent when an array has to become an object.
+  let replace: (next: Container) => void = () => {}
   for (let i = 0; i < segments.length; i++) {
     const segment = segments[i] ?? ''
     const last = i === segments.length - 1
 
     if (FORBIDDEN_KEYS.has(segment)) return
 
+    if (Array.isArray(cursor) && isIndex(segment) && Number(segment) >= arrayLimit) {
+      const converted = arrayToObject(cursor)
+      replace(converted)
+      cursor = converted
+    }
+
     if (last) {
       if (segment === '') {
         // `tags[]` — append.
@@ -109,24 +156,31 @@ function assign(target: Record<string, unknown>, segments: string[], value: unkn
     }
 
     const nextSegment = segments[i + 1] ?? ''
-    const wantsArray = nextSegment === '' || isIndex(nextSegment)
+    const wantsArray =
+      nextSegment === '' || (isIndex(nextSegment) && Number(nextSegment) < arrayLimit)
 
     if (Array.isArray(cursor)) {
       if (!isIndex(segment)) return
+      const array: unknown[] = cursor
       const index = Number(segment)
-      const existing = cursor[index]
-      if (existing === undefined || typeof existing !== 'object' || existing === null) {
-        cursor[index] = wantsArray ? [] : {}
+      const existing: unknown = array[index]
+      const child: Container = isContainer(existing) ? existing : wantsArray ? [] : {}
+      array[index] = child
+      replace = (next) => {
+        array[index] = next
       }
-      cursor = cursor[index] as Record<string, unknown> | unknown[]
+      cursor = child
       continue
     }
 
-    const existing = cursor[segment]
-    if (existing === undefined || typeof existing !== 'object' || existing === null) {
-      cursor[segment] = wantsArray ? [] : {}
+    const object: Record<string, unknown> = cursor
+    const existing: unknown = object[segment]
+    const child: Container = isContainer(existing) ? existing : wantsArray ? [] : {}
+    object[segment] = child
+    replace = (next) => {
+      object[segment] = next
     }
-    cursor = cursor[segment] as Record<string, unknown> | unknown[]
+    cursor = child
   }
 }
 
@@ -155,6 +209,7 @@ export function parseQueryString(
 ): Record<string, unknown> {
   const depth = options.depth ?? DEFAULT_DEPTH
   const parameterLimit = options.parameterLimit ?? DEFAULT_PARAMETER_LIMIT
+  const arrayLimit = options.arrayLimit ?? DEFAULT_ARRAY_LIMIT
   const result: Record<string, unknown> = {}
   if (!body) return result
 
@@ -173,7 +228,7 @@ export function parseQueryString(
     if (options.trimWhitespaces && typeof value === 'string') value = value.trim()
     if (options.convertEmptyStringsToNull && value === '') value = null
 
-    assign(result, splitKey(key, depth, options.allowDots ?? true), value)
+    assign(result, splitKey(key, depth, options.allowDots ?? true), value, arrayLimit)
   }
   return result
 }