@c9up/ream 0.2.14 → 0.2.16

package/src/rpc/RpcRouter.ts

@@ -30,7 +30,7 @@ export type RpcHandler = (ctx: HttpContext, params: unknown) => Promise<unknown>
  * the shared `'middleware'` registry, and `validator:<name>` schemas.
  */
 interface RpcContainer {
-  make<T>(target: new (...args: unknown[]) => T): Promise<T>
+  make<T>(target: abstract new (...args: never[]) => T): Promise<T>
   resolve<T>(token: string): Promise<T>
   has(token: string): boolean
 }
@@ -151,11 +151,21 @@ export class RpcRouter {
     return new RpcMethodBuilder(def)
   }
 
-  /** Register methods from a controller — auto-registers all public methods. */
-  namespace(
-    prefix: string,
-    controller: new (...args: unknown[]) => Record<string, (...args: unknown[]) => unknown>,
-  ): void {
+  /**
+   * Register methods from a controller — auto-registers all public methods.
+   *
+   * The parameter used to demand
+   * `new (...args: unknown[]) => Record<string, (...args: unknown[]) => unknown>`,
+   * which NO real controller satisfies: a class with any non-method property
+   * fails the `Record`, and a method declared `bump(): number` fails the
+   * `unknown[]` parameters, which are compared contravariantly. So the
+   * documented call — `rpc.namespace('task', TaskController)` — did not
+   * typecheck, and nothing noticed because the tests were outside `tsc`.
+   *
+   * Any class, then. The body already checks that what it found is callable
+   * and names the method when it is not.
+   */
+  namespace(prefix: string, controller: abstract new (...args: never[]) => object): void {
     const proto = controller.prototype
     const methods = Object.getOwnPropertyNames(proto).filter(
       (m) => m !== 'constructor' && typeof proto[m] === 'function',
@@ -164,8 +174,18 @@ export class RpcRouter {
       this.method(`${prefix}.${methodName}`, async (ctx, params) => {
         // Resolve through the container on every call (fresh DI per request,
         // like GraphQLEngine), falling back to a bare `new` when unset.
-        const instance = this.#container ? await this.#container.make(controller) : new controller()
-        return instance[methodName](ctx, params)
+        // `Reflect.construct`, not `new controller()`: the token may be an
+        // abstract class, which the runtime builds happily and `new` refuses.
+        const instance: object = this.#container
+          ? await this.#container.make(controller)
+          : Reflect.construct(controller, [])
+        const handler = Reflect.get(instance, methodName)
+        if (typeof handler !== 'function') {
+          throw new Error(
+            `RPC method '${prefix}.${methodName}' is not a function on ${controller.name}`,
+          )
+        }
+        return handler.call(instance, ctx, params)
       })
     }
   }
@@ -199,6 +219,16 @@ export class RpcRouter {
 
     // Batch support (max 50 to prevent DoS)
     if (Array.isArray(body)) {
+      // §6: "If the batch rpc call itself fails to be recognized as an valid
+      // JSON or as an Array with at least one value, the response from the
+      // Server MUST be a single Response object." An empty batch answered with
+      // 204 No Content, which is what this replies when every call in a batch
+      // was a notification — so a client that sent nothing was told its calls
+      // had run.
+      if (body.length === 0) {
+        ctx.response.status(200).json(rpcError(-32600, 'Invalid Request', null))
+        return
+      }
       if (body.length > 50) {
         ctx.response.status(400).json(rpcError(-32600, 'Batch too large (max 50)', null))
         return

package/src/scheduler/Schedule.ts

@@ -90,7 +90,14 @@ export function Schedule(cronExpr: string): MethodDecorator {
  * none). Returns a shallow copy so callers cannot mutate the stored
  * metadata by accident.
  */
-export function getScheduleMetadata(target: Constructor): ScheduleMetadata[] {
+/**
+ * `abstract new`, not `Constructor`: reading metadata off a class never
+ * constructs it, and the service registry holds abstract ones too since a
+ * contextual binding binds against an abstract base.
+ */
+export function getScheduleMetadata(
+  target: abstract new (...args: never[]) => unknown,
+): ScheduleMetadata[] {
   const stored: ScheduleMetadata[] = Reflect.getOwnMetadata(SCHEDULE_METADATA_KEY, target) ?? []
   return [...stored]
 }

package/src/scheduler/ScheduleProvider.ts

@@ -10,7 +10,8 @@
  *     throws, tasks 1..N-1 registered in the same boot are unregistered
  *     before the error propagates, so the scheduler is never left in a
  *     half-registered state.
- *   - `start()` — launches the Rust tick loop.
+ *   - `ready()` — discovers the tasks `app/modules/**` declared, then
+ *     launches the Rust tick loop.
  *   - `shutdown()` — cancels the Rust tick loop.
  *
  * The registered callback resolves the service **at invocation time**
@@ -86,26 +87,35 @@ export class ScheduleProvider extends Provider {
   }
 
   /**
-   * Discovery runs at START, not at boot, and that is the whole point.
+   * The pass that matters runs at READY, and the ordering is the reason.
    *
-   * `app/modules/**` is auto-loaded during the start phase — after every
-   * provider has booted. A `@Service()` carrying `@Schedule` there, which is
-   * where one naturally lives, was therefore registered into the service
-   * registry AFTER this had already read it. The task was never registered,
-   * and nothing said so: no error, no warning, the application started
-   * normally and the task simply never fired.
+   * A `@Service()` carrying `@Schedule` naturally lives in `app/modules/**`,
+   * which the application auto-loads at the END of the start phase — after
+   * every provider's `start()`. Discovering in `start()` therefore read the
+   * service registry before the modules had put anything in it: the task was
+   * never registered, and nothing said so. No error, no warning, the
+   * application started normally and the task simply never fired. `ready()`
+   * runs after the autoload, which is what makes the second pass real.
    *
-   * Reading the registry once the modules are in place is what fixes it. A
-   * service declared anywhere earlier — a provider, a preload — is in the
-   * registry by then too, so nothing is lost by waiting.
+   * The earlier passes are kept because they cost nothing and shorten the gap:
+   * a service declared by a provider or a preload is registered as soon as it
+   * is seen. `#discover()` is idempotent, so a task found twice is registered
+   * once.
    */
   override async boot(): Promise<void> {
     // Anything already in the registry — declared by a provider, or imported
-    // by one. The rest is caught at start().
+    // by one. The rest is caught later.
     this.#discover()
   }
 
   override async start(): Promise<void> {
+    // Preloads have not run yet either; this catches whatever the boot phase
+    // added. The ticker deliberately does NOT start here.
+    this.#discover()
+  }
+
+  override async ready(): Promise<void> {
+    // The pass after `app/modules/**`.
     this.#discover()
     if (activeProvider !== undefined && activeProvider !== this) {
       // A previous app's scheduler is still running — stop it before this one

package/src/security/CookieSigner.ts

@@ -225,12 +225,22 @@ export class CookieSigner {
   }
 
   decrypt<T = string>(encrypted: string, purpose?: string): T | null {
-    const parts = encrypted.split('.')
-    if (parts.length !== 3) return null
+    // Destructured rather than indexed, and `extra` is what keeps the old
+    // length check honest: three names bind on a four-part string too, so the
+    // fourth has to be looked at to reject it.
+    const [ivPart, dataPart, tagPart, extra] = encrypted.split('.')
+    if (
+      ivPart === undefined ||
+      dataPart === undefined ||
+      tagPart === undefined ||
+      extra !== undefined
+    ) {
+      return null
+    }
     try {
-      const iv = Buffer.from(parts[0], 'base64url')
-      const data = Buffer.from(parts[1], 'base64url')
-      const tag = Buffer.from(parts[2], 'base64url')
+      const iv = Buffer.from(ivPart, 'base64url')
+      const data = Buffer.from(dataPart, 'base64url')
+      const tag = Buffer.from(tagPart, 'base64url')
       const decipher = createDecipheriv('aes-256-gcm', this.#keyBuffer, iv)
       decipher.setAuthTag(tag)
       const raw = Buffer.concat([decipher.update(data), decipher.final()]).toString('utf8')

package/src/security/SignedUrl.ts

@@ -55,8 +55,9 @@ function parseExpiry(value: string | number): number {
   if (typeof value === 'number') return value
   const match = value.match(/^(\d+)(s|m|h|d)$/)
   if (!match) return 3600
-  const num = parseInt(match[1], 10)
-  switch (match[2]) {
+  const [, digits, unit] = match
+  const num = parseInt(digits ?? '0', 10)
+  switch (unit) {
     case 's':
       return num
     case 'm':

package/src/session/SessionMiddleware.ts

@@ -6,9 +6,11 @@
  */
 
 import { randomBytes } from 'node:crypto'
+import { readModuleConfig } from '../config/moduleConfig.js'
 import { currentNodeEnv } from '../env/nodeEnv.js'
 import { durationToSeconds } from '../helpers/duration.js'
 import type { HttpContext } from '../http/HttpContext.js'
+import type { SessionConfigInput } from './config.js'
 import { CookieDriver } from './drivers/CookieDriver.js'
 import { DatabaseDriver, type SessionDbConnection } from './drivers/DatabaseDriver.js'
 import { FileDriver } from './drivers/FileDriver.js'
@@ -16,7 +18,7 @@ import { MemoryDriver } from './drivers/MemoryDriver.js'
 import { RedisDriver } from './drivers/RedisDriver.js'
 import { quasarConnection } from './quasar.js'
 import { ReadOnlyValuesStore, type ValuePath } from './ReadOnlyValuesStore.js'
-import type { SessionConfig, SessionDriver } from './Session.js'
+import type { SessionDriver } from './Session.js'
 import { Session } from './Session.js'
 
 interface ResolvedSessionConfig {
@@ -42,7 +44,18 @@ export default class SessionMiddleware {
   #cookieDriver: CookieDriver | null = null
   #config: ResolvedSessionConfig
 
-  constructor(config?: SessionConfig & { secret?: string }) {
+  constructor(explicitConfig: SessionConfigInput | undefined = undefined) {
+    // The default value is load-bearing: an OPTIONAL parameter still counts
+    // toward `Function.length`, and the container refuses to auto-construct a
+    // class that declares parameters it has no metadata for. A parameter with a
+    // default counts for nothing, which is what lets
+    // `router.use([() => import('…')])` build this middleware.
+    // Nothing is passed when the container builds this middleware from
+    // `router.use([() => import('@c9up/ream/session_middleware')])`, which is
+    // the registration shape the framework documents. `config/session.ts` is
+    // where the settings live in that case — the same file the config loader
+    // already reads into `config.get('session')`.
+    const config = explicitConfig ?? readModuleConfig<SessionConfigInput>('session')
     // `store` + `stores` (AdonisJS) and `driver` (ream) name the same thing.
     // A named store supplies the driver and its own options, so
     // `{ store: 'redis', stores: { redis: { driver: 'redis' } } }` works.

package/src/session/config.ts

@@ -0,0 +1,29 @@
+/**
+ * `config/session.ts` — the session store's configuration, in the file the
+ * config loader reads (`config/<name>.ts` → `config.get('<name>')`).
+ *
+ * @example
+ *   // config/session.ts
+ *   import env from '#start/env.js'
+ *   import { defineConfig } from '@c9up/ream/session/config'
+ *
+ *   export default defineConfig({
+ *     store: 'cookie',
+ *     secret: env.get('APP_KEY'),
+ *   })
+ */
+
+import type { SessionConfig } from './Session.js'
+
+/** What a session config file may declare. */
+export type SessionConfigInput = SessionConfig & {
+  /**
+   * Signs the session cookie. Required by the cookie store, which carries the
+   * data itself and would otherwise hand the client something it could edit.
+   */
+  secret?: string
+}
+
+export function defineConfig(config: SessionConfigInput): SessionConfigInput {
+  return config
+}

package/src/session/drivers/DatabaseDriver.ts

@@ -8,10 +8,28 @@ import type { SessionDriverWithTagging, TaggedSession } from '../Session.js'
  * app's own wrapper.
  */
 export interface SessionDbConnection {
-  query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>
+  /**
+   * Rows, as rows: `Record<string, unknown>`, not a shape the caller names.
+   *
+   * `query<T>` let this driver ASSERT what a SELECT returned — a promise the
+   * database never made and the connection cannot keep. It also made the
+   * interface unimplementable by anything but a real driver: a generic method
+   * must work for every `T`, so no fake could satisfy it, and this file's tests
+   * sat outside the typecheck because of it.
+   *
+   * The columns are read through {@link textColumn} below instead, which is
+   * what a row from a database deserves.
+   */
+  query(sql: string, params?: unknown[]): Promise<Array<Record<string, unknown>>>
   execute(sql: string, params?: unknown[]): Promise<{ rowsAffected: number }>
 }
 
+/** A column that must be text to be usable, or `null`. */
+function textColumn(row: Record<string, unknown>, name: string): string | null {
+  const value = row[name]
+  return typeof value === 'string' ? value : null
+}
+
 export interface DatabaseDriverOptions {
   connection: SessionDbConnection
   /** Table holding the sessions. Default `sessions`. */
@@ -71,17 +89,20 @@ export class DatabaseDriver implements SessionDriverWithTagging {
   }
 
   async read(sessionId: string): Promise<Record<string, unknown> | null> {
-    const rows = await this.#db.query<{ data: string; expires_at: number | string }>(
-      `SELECT data, expires_at FROM ${this.#table} WHERE id = ?`,
-      [sessionId],
-    )
+    const rows = await this.#db.query(`SELECT data, expires_at FROM ${this.#table} WHERE id = ?`, [
+      sessionId,
+    ])
     const row = rows[0]
     if (!row) return null
     if (Number(row.expires_at) < Date.now()) {
       await this.destroy(sessionId)
       return null
     }
-    return parseData(row.data)
+    const data = textColumn(row, 'data')
+    // A row whose payload is not text is not a session — the same outcome as a
+    // row that will not parse.
+    if (data === null) return null
+    return parseData(data)
   }
 
   async write(sessionId: string, data: Record<string, unknown>, ttl: number): Promise<void> {
@@ -157,11 +178,18 @@ export class DatabaseDriver implements SessionDriverWithTagging {
 
   /** Every non-expired session this user holds — their active devices. */
   async tagged(userId: string | number): Promise<TaggedSession[]> {
-    const rows = await this.#db.query<{ id: string; data: string }>(
+    const rows = await this.#db.query(
       `SELECT id, data FROM ${this.#table} WHERE user_id = ? AND expires_at >= ?`,
       [String(userId), Date.now()],
     )
-    return rows.map((row) => ({ id: row.id, data: parseData(row.data) }))
+    const sessions: TaggedSession[] = []
+    for (const row of rows) {
+      const id = textColumn(row, 'id')
+      const data = textColumn(row, 'data')
+      if (id === null || data === null) continue
+      sessions.push({ id, data: parseData(data) })
+    }
+    return sessions
   }
 
   /** Delete every expired row — for a scheduled job, since nothing else does. */

package/src/session/drivers/RedisDriver.ts

@@ -67,11 +67,19 @@ export class RedisDriver implements SessionDriverWithTagging {
     }
     if (!this.#pending) {
       const resolver = this.#source
-      this.#pending = Promise.resolve(resolver()).then((client) => {
-        this.#resolved = client
-        this.#pending = undefined
-        return client
-      })
+      // `finally`, not the success path: clearing it only on success left a
+      // REJECTED promise in the slot, and every later call returned that same
+      // rejection. One refused connection at boot — Redis still starting, a
+      // network blip — and the driver never tried again for the life of the
+      // process. Bay and echo already clear it this way.
+      this.#pending = Promise.resolve(resolver())
+        .then((client) => {
+          this.#resolved = client
+          return client
+        })
+        .finally(() => {
+          this.#pending = undefined
+        })
     }
     return this.#pending
   }

package/src/testing/ApiResponse.ts

@@ -149,15 +149,14 @@ function parseMultipartResponse(
     // Trim the trailing CRLF before the next boundary.
     let content = part.subarray(headerEnd + 4)
     if (content.subarray(-2).toString('binary') === '\r\n') content = content.subarray(0, -2)
-    const nameMatch = headerText.match(/name="([^"]*)"/i)
-    if (!nameMatch) continue
-    const name = nameMatch[1]
-    const fileMatch = headerText.match(/filename="([^"]*)"/i)
-    if (fileMatch) {
+    const [, name] = headerText.match(/name="([^"]*)"/i) ?? []
+    if (name === undefined) continue
+    const [, filename] = headerText.match(/filename="([^"]*)"/i) ?? []
+    if (filename !== undefined) {
       const typeMatch = headerText.match(/content-type:\s*([^\r\n]+)/i)
       files[name] = {
         fieldName: name,
-        filename: fileMatch[1],
+        filename,
         type: typeMatch?.[1]?.trim() ?? 'application/octet-stream',
         size: content.length,
         content,
@@ -355,8 +354,8 @@ export class ApiResponse {
   /** Charset from `Content-Type`, if any — helix `charset()`. */
   charset(): string | undefined {
     const ct = this.#raw.headers['content-type'] ?? ''
-    const m = ct.match(/charset=([^;]+)/i)
-    return m ? m[1].trim() : undefined
+    const [, charset] = ct.match(/charset=([^;]+)/i) ?? []
+    return charset?.trim()
   }
 
   /** All response cookies, parsed from `Set-Cookie` — helix `cookies()`. */
@@ -380,8 +379,8 @@ export class ApiResponse {
     if (!link) return {}
     const out: Record<string, string> = {}
     for (const part of link.split(',')) {
-      const m = part.match(/<([^>]+)>\s*;\s*rel="?([^";]+)"?/)
-      if (m) out[m[2]] = m[1]
+      const [, url, rel] = part.match(/<([^>]+)>\s*;\s*rel="?([^";]+)"?/) ?? []
+      if (url !== undefined && rel !== undefined) out[rel] = url
     }
     return out
   }

package/src/testing/TestClient.ts

@@ -368,15 +368,15 @@ export function parseHttpResponse(raw: string | Buffer): TestResponse {
 
   const lines = headerSection.split('\r\n')
   const statusLine = lines[0] ?? ''
-  const statusMatch = statusLine.match(/HTTP\/\d+\.\d+ (\d+)/)
-  const status = statusMatch ? Number.parseInt(statusMatch[1], 10) : 0
+  const [, statusDigits] = statusLine.match(/HTTP\/\d+\.\d+ (\d+)/) ?? []
+  const status = statusDigits === undefined ? 0 : Number.parseInt(statusDigits, 10)
 
   const headers: Dict = {}
-  for (let i = 1; i < lines.length; i++) {
-    const colonIdx = lines[i].indexOf(':')
+  for (const line of lines.slice(1)) {
+    const colonIdx = line.indexOf(':')
     if (colonIdx === -1) continue
-    const key = lines[i].slice(0, colonIdx).trim().toLowerCase()
-    const value = lines[i].slice(colonIdx + 1).trim()
+    const key = line.slice(0, colonIdx).trim().toLowerCase()
+    const value = line.slice(colonIdx + 1).trim()
     headers[key] = value
   }
 

package/src/utils/Macroable.ts

@@ -38,7 +38,11 @@ export class Macroable {
    * `HttpContext`, and two subclasses declaring the same name clobbered each
    * other silently.
    */
-  static macro(this: typeof Macroable, name: string, fn: MacroFn): void {
+  // `{ prototype: object }`, not `typeof Macroable`: a subclass whose
+  // constructor takes arguments — `Request`, say — has a different static side,
+  // so `Request.macro(...)` was "the 'this' context of type 'typeof Request' is
+  // not assignable". What this needs from `this` is the prototype it defines on.
+  static macro(this: { prototype: object }, name: string, fn: MacroFn): void {
     Object.defineProperty(this.prototype, name, {
       value: fn,
       writable: true,
@@ -51,7 +55,7 @@ export class Macroable {
    * `getter`). With `singleton`, the value is computed once per instance and
    * cached.
    */
-  static getter(this: typeof Macroable, name: string, fn: GetterFn, singleton = false): void {
+  static getter(this: { prototype: object }, name: string, fn: GetterFn, singleton = false): void {
     if (!singleton) {
       Object.defineProperty(this.prototype, name, { get: fn, configurable: true })
       return

package/src/utils/objectPath.ts

@@ -77,9 +77,13 @@ export function hasPath(source: unknown, path: string): boolean {
  */
 export function setPath(target: UnknownRecord, path: string, value: unknown): UnknownRecord {
   const segments = toSegments(path)
+  // The last segment is the one written; everything before it is walked. Split
+  // off by name rather than by index, so neither has to be read back out of
+  // the array afterwards and re-checked for existence.
+  const last = segments.pop()
+  if (last === undefined) return target
   let current: UnknownRecord = target
-  for (let i = 0; i < segments.length - 1; i += 1) {
-    const key = segments[i]
+  for (const key of segments) {
     const next = current[key]
     if (!isIndexable(next)) {
       const created: UnknownRecord = {}
@@ -89,7 +93,7 @@ export function setPath(target: UnknownRecord, path: string, value: unknown): Un
       current = next
     }
   }
-  current[segments[segments.length - 1]] = value
+  current[last] = value
   return target
 }
 
@@ -115,12 +119,14 @@ export function omitPaths(source: UnknownRecord, paths: string[]): UnknownRecord
   const result = structuredClone(source)
   for (const path of paths) {
     const segments = toSegments(path)
+    const last = segments.pop()
+    if (last === undefined) continue
     let current: unknown = result
-    for (let i = 0; i < segments.length - 1; i += 1) {
+    for (const key of segments) {
       if (!isIndexable(current)) break
-      current = current[segments[i]]
+      current = current[key]
     }
-    if (isIndexable(current)) delete current[segments[segments.length - 1]]
+    if (isIndexable(current)) delete current[last]
   }
   return result
 }