@c9up/ream 0.1.3

package/src/Provider.ts

@@ -0,0 +1,74 @@
+/**
+ * Base Provider class — modules register via providers.
+ *
+ * @implements FR20
+ *
+ * Lifecycle (AdonisJS-compatible):
+ *   register() → boot() → start() → ready() → ... → shutdown()
+ */
+
+import type { ConfigStore } from './ConfigLoader.js'
+import type { Container } from './container/Container.js'
+
+export interface AppContext {
+  container: Container
+  config: ConfigStore
+}
+
+/**
+ * Structural contract for a provider — all phases optional. Independently-
+ * published packages (spectrum, warden, blackhole, relay, ...) implement
+ * only the phases they need without taking a hard dependency on
+ * `@c9up/ream`. The lifecycle runner guards each call with a `typeof`
+ * check, so a missing method is opt-out, not a contract break.
+ *
+ * The abstract `Provider` class below is the convenience implementation
+ * for code that *does* live inside this package — it ships empty
+ * defaults for every phase. Both shapes satisfy `ProviderContract`.
+ */
+export interface ProviderContract {
+  register?(): void
+  boot?(): Promise<void> | void
+  start?(): Promise<void> | void
+  ready?(): Promise<void> | void
+  shutdown?(): Promise<void> | void
+}
+
+/**
+ * Invoke an async lifecycle phase on a provider, ignoring it when the
+ * method is absent. Centralises the duck-type guard that the lifecycle
+ * runner has to do at every phase since `ProviderContract` makes them
+ * all optional.
+ */
+export async function callProviderPhase(
+  provider: ProviderContract,
+  phase: 'boot' | 'start' | 'ready' | 'shutdown',
+): Promise<void> {
+  const fn = provider[phase]
+  if (typeof fn === 'function') {
+    await fn.call(provider)
+  }
+}
+
+export abstract class Provider implements ProviderContract {
+  protected app: AppContext
+
+  constructor(app: AppContext) {
+    this.app = app
+  }
+
+  /** Phase 1: Register bindings in the container (synchronous). */
+  register(): void {}
+
+  /** Phase 2: Boot — framework setup, verify connections. */
+  async boot(): Promise<void> {}
+
+  /** Phase 3: Start — before HTTP server starts. Import routes, warm caches. */
+  async start(): Promise<void> {}
+
+  /** Phase 4: Ready — app fully operational, HTTP server listening. */
+  async ready(): Promise<void> {}
+
+  /** Cleanup on shutdown (reverse order). */
+  async shutdown(): Promise<void> {}
+}

package/src/bodyparser/BodyParserMiddleware.ts

@@ -0,0 +1,183 @@
+/**
+ * BodyParser middleware — parses request bodies by content-type.
+ *
+ * Supports JSON, form-urlencoded, and raw text.
+ * Multipart (file uploads) handled separately.
+ * Configured via config/bodyparser.ts.
+ */
+
+import type { HttpContext } from '../http/HttpContext.js'
+import { hydrateMultipartPayload } from './MultipartFile.js'
+
+export interface BodyParserConfig {
+  json?: {
+    enabled?: boolean
+    limit?: string // e.g. '1mb'
+    types?: string[]
+  }
+  form?: {
+    enabled?: boolean
+    limit?: string
+    types?: string[]
+  }
+  raw?: {
+    enabled?: boolean
+    limit?: string
+    types?: string[]
+  }
+  multipart?: {
+    enabled?: boolean
+    limit?: string
+    maxFields?: number
+    tmpDir?: string
+    types?: string[]
+  }
+}
+
+interface ResolvedBodyParserConfig {
+  json: Required<NonNullable<BodyParserConfig['json']>>
+  form: Required<NonNullable<BodyParserConfig['form']>>
+  raw: Required<NonNullable<BodyParserConfig['raw']>>
+  multipart: Required<NonNullable<BodyParserConfig['multipart']>>
+}
+
+const DEFAULT_CONFIG: ResolvedBodyParserConfig = {
+  json: {
+    enabled: true,
+    limit: '1mb',
+    types: ['application/json', 'application/vnd.api+json'],
+  },
+  form: {
+    enabled: true,
+    limit: '1mb',
+    types: ['application/x-www-form-urlencoded'],
+  },
+  raw: {
+    enabled: false,
+    limit: '1mb',
+    types: ['text/plain'],
+  },
+  multipart: {
+    enabled: true,
+    limit: '20mb',
+    maxFields: 500,
+    tmpDir: '/tmp',
+    types: ['multipart/form-data'],
+  },
+}
+
+export default class BodyParserMiddleware {
+  #config: ResolvedBodyParserConfig
+
+  constructor(config?: BodyParserConfig) {
+    this.#config = {
+      json: { ...DEFAULT_CONFIG.json, ...config?.json },
+      form: { ...DEFAULT_CONFIG.form, ...config?.form },
+      raw: { ...DEFAULT_CONFIG.raw, ...config?.raw },
+      multipart: { ...DEFAULT_CONFIG.multipart, ...config?.multipart },
+    }
+  }
+
+  async handle(ctx: HttpContext, next: () => Promise<void>) {
+    const contentType = ctx.request.header('content-type') ?? ''
+    const rawBody = ctx.request.raw()
+
+    // Size check
+    if (Buffer.byteLength(rawBody, 'utf8') > parseSize(this.#getLimit(contentType))) {
+      ctx.response.status(413).json({
+        error: { code: 'E_REQUEST_ENTITY_TOO_LARGE', message: 'Request body exceeds size limit' },
+      })
+      return
+    }
+
+    // JSON
+    if (this.#config.json.enabled && matchesType(contentType, this.#config.json.types)) {
+      // Request already lazy-parses JSON — nothing to do
+    }
+
+    // Form URL-encoded
+    if (this.#config.form.enabled && matchesType(contentType, this.#config.form.types)) {
+      ctx.request.setParsedBody(parseFormUrlEncoded(rawBody))
+    }
+
+    // Raw text — wrap the string under `_body` so consumers can still
+    // reach it through `request.input('_body')`. This matches the fallback
+    // shape used by `Request.#ensureParsedBody` when JSON yields a non-object.
+    if (this.#config.raw.enabled && matchesType(contentType, this.#config.raw.types)) {
+      ctx.request.setParsedBody({ _body: rawBody })
+    }
+
+    // Multipart — the Rust-side HyperServer parses the body server-side
+    // (multer crate) and ships the structured payload on `request.multipart`.
+    // JS just hydrates `MultipartFile` instances from the typed envelope.
+    if (this.#config.multipart.enabled && matchesType(contentType, this.#config.multipart.types)) {
+      const payload = ctx.request.multipart()
+      if (payload) {
+        const { fields, files } = hydrateMultipartPayload(payload)
+        ctx.request.setParsedBody(fields)
+        ctx.request.setFiles(files)
+      }
+    }
+
+    await next()
+  }
+
+  #getLimit(contentType: string): string {
+    if (matchesType(contentType, this.#config.json.types)) return this.#config.json.limit
+    if (matchesType(contentType, this.#config.form.types)) return this.#config.form.limit
+    if (matchesType(contentType, this.#config.multipart.types)) return this.#config.multipart.limit
+    return this.#config.raw.limit
+  }
+}
+
+function matchesType(contentType: string, types: string[]): boolean {
+  return types.some((t) => contentType.includes(t))
+}
+
+function parseSize(size: string): number {
+  const match = size.match(/^(\d+)(kb|mb|gb)?$/i)
+  if (!match) return 1024 * 1024 // default 1mb
+  const num = parseInt(match[1], 10)
+  switch (match[2]?.toLowerCase()) {
+    case 'kb':
+      return num * 1024
+    case 'mb':
+      return num * 1024 * 1024
+    case 'gb':
+      return num * 1024 * 1024 * 1024
+    default:
+      return num
+  }
+}
+
+function parseFormUrlEncoded(body: string): Record<string, unknown> {
+  const result: Record<string, unknown> = {}
+  if (!body) return result
+  for (const pair of body.split('&')) {
+    if (!pair) continue
+    const eqIdx = pair.indexOf('=')
+    if (eqIdx === -1) {
+      result[decodeFormComponent(pair)] = ''
+    } else {
+      result[decodeFormComponent(pair.slice(0, eqIdx))] = decodeFormComponent(pair.slice(eqIdx + 1))
+    }
+  }
+  return result
+}
+
+// `application/x-www-form-urlencoded` reserves `+` for space (RFC 1866 / WHATWG
+// URL form spec), so the substitution must happen before percent-decoding —
+// otherwise a literal `+` (encoded as `%2B`) would be turned into a space too.
+//
+// Malformed percent-encoding (e.g. a truncated `a=%E0%A4%A`) makes
+// decodeURIComponent throw URIError; mirror Request.ts#safeDecode and fall back
+// to the substituted-but-undecoded value so an invalid body is a parse miss,
+// not a 500.
+function decodeFormComponent(value: string): string {
+  const spaced = value.replace(/\+/g, ' ')
+  try {
+    return decodeURIComponent(spaced)
+  } catch {
+    return spaced
+  }
+}

package/src/bodyparser/MultipartFile.ts

@@ -0,0 +1,181 @@
+/**
+ * MultipartFile — represents an uploaded file.
+ *
+ * Like AdonisJS MultipartFile:
+ *   const avatar = request.file('avatar', { size: '2mb', extnames: ['jpg', 'png'] })
+ *   await avatar.moveToDisk('uploads')
+ */
+
+import { randomBytes } from 'node:crypto'
+import { Readable } from 'node:stream'
+
+export interface FileValidationOptions {
+  size?: string
+  extnames?: string[]
+}
+
+export class MultipartFile {
+  /** Original filename from the client. */
+  readonly clientName: string
+
+  /** File extension (without dot). */
+  readonly extname: string
+
+  /** MIME type from the Content-Type header. */
+  readonly type: string
+
+  /** File size in bytes. */
+  readonly size: number
+
+  /** Raw file content as Buffer. */
+  readonly content: Buffer
+
+  /** Field name in the form. */
+  readonly fieldName: string
+
+  /** Validation errors. */
+  readonly errors: string[] = []
+
+  /** Whether the file has been moved. */
+  #moved = false
+
+  constructor(options: {
+    fieldName: string
+    clientName: string
+    type: string
+    content: Buffer
+  }) {
+    this.fieldName = options.fieldName
+    this.clientName = options.clientName
+    this.type = options.type
+    this.content = options.content
+    this.size = options.content.length
+    const segments = options.clientName.split('.')
+    this.extname = segments.length > 1 ? (segments.at(-1) ?? '').toLowerCase() : ''
+  }
+
+  /** Validate file against size and extension rules. */
+  validate(options: FileValidationOptions): boolean {
+    if (options.size) {
+      const maxBytes = parseFileSize(options.size)
+      if (this.size > maxBytes) {
+        this.errors.push(`File size ${this.size} exceeds limit ${options.size}`)
+      }
+    }
+    if (options.extnames && options.extnames.length > 0) {
+      if (!options.extnames.includes(this.extname)) {
+        this.errors.push(
+          `Extension '${this.extname}' not allowed. Allowed: ${options.extnames.join(', ')}`,
+        )
+      }
+    }
+    return this.errors.length === 0
+  }
+
+  get isValid(): boolean {
+    return this.errors.length === 0
+  }
+
+  /**
+   * Move file to a directory on disk. When `name` is supplied it must be
+   * a plain filename — no path separators, no `.`/`..` segments. The
+   * common footgun is passing the client-supplied `clientName` directly
+   * (`await file.moveToDisk('uploads', file.clientName)`); a malicious
+   * upload could otherwise traverse out of `directory` via `../../etc/...`.
+   */
+  async moveToDisk(directory: string, name?: string): Promise<string> {
+    const { mkdirSync, writeFileSync } = await import('node:fs')
+    const { join } = await import('node:path')
+
+    if (name !== undefined && !isSafeFilename(name)) {
+      throw new Error(
+        `MultipartFile.moveToDisk: 'name' must be a plain filename (no path separators, '.', or '..'). Got: ${JSON.stringify(name)}`,
+      )
+    }
+
+    mkdirSync(directory, { recursive: true })
+    const fileName = name ?? `${randomBytes(16).toString('hex')}.${this.extname}`
+    // Defense-in-depth: the default branch interpolates `extname` (derived
+    // from attacker-controlled `clientName`) into the filename, bypassing
+    // the `name` guard above. Re-validate the synthesized fileName before
+    // join to reject a hostile extname (separators, NUL).
+    if (!isSafeFilename(fileName)) {
+      throw new Error(
+        `MultipartFile.moveToDisk: derived filename '${fileName}' is unsafe (separator or invalid char in clientName-derived extname).`,
+      )
+    }
+    const filePath = join(directory, fileName)
+    writeFileSync(filePath, this.content)
+    this.#moved = true
+    return filePath
+  }
+
+  get isMoved(): boolean {
+    return this.#moved
+  }
+
+  /**
+   * Return a fresh `Readable` over the file's bytes. The underlying buffer is
+   * not consumed — repeated calls always start at byte 0, so callers can pipe
+   * the same file into multiple sinks (e.g. validation hash + disk write)
+   * without `Buffer.from(this.content)` boilerplate.
+   */
+  stream(): Readable {
+    return Readable.from(this.content, { objectMode: false })
+  }
+}
+
+function isSafeFilename(name: string): boolean {
+  if (name.length === 0) return false
+  if (name === '.' || name === '..') return false
+  if (/[\\/\0]/.test(name)) return false
+  return true
+}
+
+function parseFileSize(size: string): number {
+  const match = size.match(/^(\d+)(kb|mb|gb)?$/i)
+  if (!match) return 1024 * 1024
+  const num = parseInt(match[1], 10)
+  switch (match[2]?.toLowerCase()) {
+    case 'kb':
+      return num * 1024
+    case 'mb':
+      return num * 1024 * 1024
+    case 'gb':
+      return num * 1024 * 1024 * 1024
+    default:
+      return num
+  }
+}
+
+/**
+ * Hydrate `MultipartFile` instances from the typed payload the Rust
+ * HyperServer attaches to the request. The wire-level parser (multer crate,
+ * see `crates/ream-http/src/multipart.rs`) handles the actual RFC 7578
+ * parsing — JS just decodes the base64 envelope and wraps the result.
+ */
+export function hydrateMultipartPayload(payload: {
+  fields: Array<{ name: string; value: string }>
+  files: Array<{
+    fieldName: string
+    clientName: string
+    contentType: string
+    size: number
+    contentB64: string
+  }>
+}): { fields: Record<string, string>; files: MultipartFile[] } {
+  const fields: Record<string, string> = {}
+  for (const field of payload.fields) {
+    fields[field.name] = field.value
+  }
+  const files = payload.files.map(
+    (f) =>
+      new MultipartFile({
+        fieldName: f.fieldName,
+        clientName: f.clientName,
+        type: f.contentType,
+        content: Buffer.from(f.contentB64, 'base64'),
+      }),
+  )
+  return { fields, files }
+}

package/src/bodyparser/parseSize.ts

@@ -0,0 +1,19 @@
+/**
+ * Parse a human-readable size string (e.g. '1mb', '512kb', '2gb') to bytes.
+ * Single source of truth — used by both BodyParserMiddleware and MultipartFile.
+ */
+export function parseSize(size: string): number {
+  const match = size.match(/^(\d+)(kb|mb|gb)?$/i)
+  if (!match) return 1024 * 1024 // default 1mb
+  const num = parseInt(match[1], 10)
+  switch (match[2]?.toLowerCase()) {
+    case 'kb':
+      return num * 1024
+    case 'mb':
+      return num * 1024 * 1024
+    case 'gb':
+      return num * 1024 * 1024 * 1024
+    default:
+      return num
+  }
+}

package/src/bootstrap/hyper-server.ts

@@ -0,0 +1,78 @@
+/**
+ * Default HyperServer factory — encapsulates the platform-suffix mapping
+ * and the require() lookup so consumer apps stop hand-rolling the same
+ * ~25 lines in every `bin/server.ts`.
+ *
+ * Usage in an app:
+ *
+ *     import { createHyperServerFactory } from '@c9up/ream/bootstrap'
+ *     new Ignitor(APP_ROOT, {
+ *       port: 3000,
+ *       serverFactory: await createHyperServerFactory(),
+ *     })
+ *
+ * Returns `undefined` when no prebuilt binary matches the host platform —
+ * callers can branch on that to fall back to a JS-only server in tests.
+ *
+ * Binary lives at the package root (`./index.<platform>.node`),
+ * matching the @c9up/chronos / @c9up/sigil convention.
+ */
+
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { arch, platform } from 'node:process'
+import { fileURLToPath } from 'node:url'
+import type { HyperServerLike } from '../Ignitor.js'
+
+const PLATFORM_SUFFIX: Record<string, string> = {
+  'linux-x64': 'linux-x64-gnu',
+  'linux-arm64': 'linux-arm64-gnu',
+  'darwin-x64': 'darwin-x64',
+  'darwin-arm64': 'darwin-arm64',
+  'win32-x64': 'win32-x64-msvc',
+}
+
+interface HyperServerCtor {
+  new (port: number): HyperServerLike
+}
+
+interface HyperServerNapiModule {
+  HyperServer: HyperServerCtor
+}
+
+function isHyperServerNapi(value: unknown): value is HyperServerNapiModule {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'HyperServer' in value &&
+    typeof (value as { HyperServer: unknown }).HyperServer === 'function'
+  )
+}
+
+/**
+ * Resolve the prebuilt HyperServer NAPI binary for the current platform.
+ * Returns a `serverFactory` compatible with `IgnitorConfig`, or `undefined`
+ * when no binary is available (unsupported platform / missing build).
+ */
+export function createHyperServerFactory(): ((port: number) => HyperServerLike) | undefined {
+  const suffix = PLATFORM_SUFFIX[`${platform}-${arch}`]
+  if (!suffix) return undefined
+
+  const require2 = createRequire(import.meta.url)
+  const here = dirname(fileURLToPath(import.meta.url))
+  // bootstrap/hyper-server.ts lives at src/bootstrap/, so the package root
+  // is two directories up.
+  const binaryPath = join(here, '..', '..', `index.${suffix}.node`)
+
+  let mod: unknown
+  try {
+    mod = require2(binaryPath)
+  } catch {
+    return undefined
+  }
+
+  if (!isHyperServerNapi(mod)) return undefined
+
+  const Ctor = mod.HyperServer
+  return (port: number) => new Ctor(port)
+}

package/src/console/CommandRunner.ts

@@ -0,0 +1,82 @@
+/**
+ * CommandRunner — minimal CLI command framework.
+ *
+ * Registers commands and dispatches based on argv.
+ * Like AdonisJS Ace but lightweight.
+ */
+
+export interface Command {
+  name: string
+  description: string
+  run(args: string[], flags: Record<string, string | boolean>): Promise<void>
+}
+
+export class CommandRunner {
+  #commands: Map<string, Command> = new Map()
+
+  register(command: Command): this {
+    this.#commands.set(command.name, command)
+    return this
+  }
+
+  async handle(argv: string[]): Promise<void> {
+    const { commandName, args, flags } = parseArgv(argv)
+
+    if (!commandName || commandName === 'help') {
+      this.#printHelp()
+      return
+    }
+
+    const command = this.#commands.get(commandName)
+    if (!command) {
+      console.error(`Unknown command: ${commandName}`)
+      console.error(`Run without arguments to see available commands.`)
+      process.exitCode = 1
+      return
+    }
+
+    await command.run(args, flags)
+  }
+
+  #printHelp(): void {
+    console.log('\nAvailable commands:\n')
+    for (const [name, cmd] of this.#commands) {
+      console.log(`  ${name.padEnd(25)} ${cmd.description}`)
+    }
+    console.log('')
+  }
+
+  getCommands(): Map<string, Command> {
+    return new Map(this.#commands)
+  }
+}
+
+function parseArgv(argv: string[]): {
+  commandName: string | undefined
+  args: string[]
+  flags: Record<string, string | boolean>
+} {
+  const flags: Record<string, string | boolean> = {}
+  const positional: string[] = []
+
+  for (const arg of argv) {
+    if (arg.startsWith('--')) {
+      const eqIdx = arg.indexOf('=')
+      if (eqIdx !== -1) {
+        flags[arg.slice(2, eqIdx)] = arg.slice(eqIdx + 1)
+      } else {
+        flags[arg.slice(2)] = true
+      }
+    } else if (arg.startsWith('-') && arg.length === 2) {
+      flags[arg.slice(1)] = true
+    } else {
+      positional.push(arg)
+    }
+  }
+
+  return {
+    commandName: positional[0],
+    args: positional.slice(1),
+    flags,
+  }
+}