ingenium 0.0.1

package/src/sinatra/top-level.ts

@@ -0,0 +1,151 @@
+/**
+ * Sinatra-style top-level shorthand.
+ *
+ * Lets users skip the app object entirely:
+ *
+ * ```ts
+ * import { get, post, listen } from 'ingenium'
+ *
+ * get('/', () => 'hi')
+ * get('/users/:id', (ctx) => ({ id: ctx.params.id }))
+ * post('/echo', async (ctx) => ctx.body.json())
+ *
+ * await listen(3000)
+ * ```
+ *
+ * All exported verbs route to a lazy singleton `IngeniumApp` created on first
+ * call. The instance is retained for the lifetime of the process; tests can
+ * call `_resetDefaultApp()` to drop it (this throws in production).
+ */
+
+import { IngeniumApp, type IngeniumErrorHandler } from '../app.ts'
+import type { IngeniumHandler, IngeniumMiddleware } from '../middleware/types.ts'
+import { Router } from '../router/router.ts'
+import type { ListeningServer } from '../transport/types.ts'
+
+let _defaultApp: IngeniumApp | null = null
+
+/**
+ * Get the lazy default app. Created on first call, retained for the
+ * lifetime of the process (or until `_resetDefaultApp()` is invoked).
+ *
+ * The same instance is returned on every subsequent call, so all
+ * top-level verb functions and `listen()` operate on a single coherent
+ * registration journal.
+ */
+export function defaultApp(): IngeniumApp {
+  if (!_defaultApp) _defaultApp = new IngeniumApp()
+  return _defaultApp
+}
+
+/**
+ * Reset the default app — for tests only. The next call to any top-level
+ * function will lazily create a fresh `IngeniumApp`. Throws when
+ * `NODE_ENV === 'production'` so accidental production calls are loud.
+ */
+export function _resetDefaultApp(): void {
+  if (process.env.NODE_ENV === 'production') {
+    throw new Error('_resetDefaultApp is a test-only API')
+  }
+  _defaultApp = null
+}
+
+// ───── HTTP verb shorthand ──────────────────────────────────────────────────
+//
+// Signatures mirror `IngeniumApp.get/post/...` exactly (`(path, handler)`),
+// so the typed-ctx story (e.g. `IngeniumHandler<{ id: string }>`) is preserved
+// for users who import these as drop-in replacements for `app.get(...)`.
+
+export function get(path: string, handler: IngeniumHandler): IngeniumApp {
+  return defaultApp().get(path, handler)
+}
+
+export function post(path: string, handler: IngeniumHandler): IngeniumApp {
+  return defaultApp().post(path, handler)
+}
+
+export function put(path: string, handler: IngeniumHandler): IngeniumApp {
+  return defaultApp().put(path, handler)
+}
+
+export function patch(path: string, handler: IngeniumHandler): IngeniumApp {
+  return defaultApp().patch(path, handler)
+}
+
+/**
+ * Default-app shorthand for `app.delete(path, handler)`.
+ * Exported as `del` because `delete` is a reserved word in JavaScript and
+ * cannot be used as a top-level identifier. `index.ts` re-exports this as
+ * `{ del as delete }` so the public name is `delete`.
+ */
+export function del(path: string, handler: IngeniumHandler): IngeniumApp {
+  return defaultApp().delete(path, handler)
+}
+
+export function head(path: string, handler: IngeniumHandler): IngeniumApp {
+  return defaultApp().head(path, handler)
+}
+
+export function options(path: string, handler: IngeniumHandler): IngeniumApp {
+  return defaultApp().options(path, handler)
+}
+
+// ───── use / onError / listen ───────────────────────────────────────────────
+
+/**
+ * Mount middleware on the default app. Same overload set as `app.use`:
+ *   - `use(mw)` — global
+ *   - `use(prefix, mw | Router)` — prefix-scoped
+ */
+export function use(mw: IngeniumMiddleware): IngeniumApp
+export function use(prefix: string, mw: IngeniumMiddleware | Router): IngeniumApp
+export function use(
+  arg1: string | IngeniumMiddleware,
+  arg2?: IngeniumMiddleware | Router,
+): IngeniumApp {
+  const app = defaultApp()
+  if (typeof arg1 === 'string') {
+    return app.use(arg1, arg2 as IngeniumMiddleware | Router)
+  }
+  return app.use(arg1)
+}
+
+/** Default-app shorthand for `app.onError(handler)`. */
+export function onError(handler: IngeniumErrorHandler): IngeniumApp {
+  return defaultApp().onError(handler)
+}
+
+/**
+ * Bind the default app to a port. Returns a `ListeningServer` whose
+ * `.close()` shuts down the underlying transport. Pass `0` for an
+ * ephemeral port (useful in tests).
+ */
+export function listen(port: number, host?: string): Promise<ListeningServer> {
+  return host !== undefined ? defaultApp().listen(port, host) : defaultApp().listen(port)
+}
+
+// ───── Sinatra-style filter shorthand ───────────────────────────────────────
+//
+// Mirrors `IngeniumApp.before/after` overloads exactly.
+
+export function before(handler: IngeniumMiddleware): IngeniumApp
+export function before(pattern: string, handler: IngeniumMiddleware): IngeniumApp
+export function before(
+  arg1: string | IngeniumMiddleware,
+  arg2?: IngeniumMiddleware,
+): IngeniumApp {
+  const app = defaultApp()
+  if (typeof arg1 === 'string') return app.before(arg1, arg2 as IngeniumMiddleware)
+  return app.before(arg1)
+}
+
+export function after(handler: IngeniumMiddleware): IngeniumApp
+export function after(pattern: string, handler: IngeniumMiddleware): IngeniumApp
+export function after(
+  arg1: string | IngeniumMiddleware,
+  arg2?: IngeniumMiddleware,
+): IngeniumApp {
+  const app = defaultApp()
+  if (typeof arg1 === 'string') return app.after(arg1, arg2 as IngeniumMiddleware)
+  return app.after(arg1)
+}

package/src/sse/keep-alive.ts

@@ -0,0 +1,52 @@
+import type { SseStream } from './sse.ts'
+
+/**
+ * Send a `:keepalive` comment to the given SSE stream every `intervalMs`
+ * milliseconds. Returns a cancellation function.
+ *
+ * The interval is automatically cancelled when the stream closes — but
+ * callers should still hold onto the cancel function for explicit cleanup
+ * (e.g. on a separate teardown signal).
+ *
+ * The internal timer is `unref()`'d so it won't keep the Node event loop
+ * alive on its own.
+ *
+ * @example
+ *   const stream = sse(ctx)
+ *   const cancel = startKeepAlive(stream, 15_000)
+ *   ctx.req.on('close', cancel) // optional
+ */
+export function startKeepAlive(
+  stream: SseStream,
+  intervalMs = 15_000,
+): () => void {
+  let cancelled = false
+
+  const timer = setInterval(() => {
+    if (cancelled || stream.closed) {
+      clearInterval(timer)
+      return
+    }
+    stream.comment('keepalive')
+  }, intervalMs)
+
+  if (typeof timer.unref === 'function') timer.unref()
+
+  // Best-effort: clear the interval as soon as we observe the stream closing.
+  // The interval also self-clears via the closed-check above, but this
+  // shortens the window before the next tick fires.
+  const watcher = setInterval(() => {
+    if (stream.closed) {
+      clearInterval(timer)
+      clearInterval(watcher)
+    }
+  }, Math.max(50, Math.min(intervalMs, 1000)))
+  if (typeof watcher.unref === 'function') watcher.unref()
+
+  return () => {
+    if (cancelled) return
+    cancelled = true
+    clearInterval(timer)
+    clearInterval(watcher)
+  }
+}

package/src/sse/sse.ts

@@ -0,0 +1,115 @@
+import { PassThrough } from 'node:stream'
+import type { IngeniumContext } from '../context/context.ts'
+
+/**
+ * A single Server-Sent Event. The `data` field is required; if you pass an
+ * object, it's `JSON.stringify`'d before being written. All other fields are
+ * optional and serialized per the EventSource specification.
+ *
+ * @see https://html.spec.whatwg.org/multipage/server-sent-events.html
+ */
+export interface SseEvent {
+  /** Payload. Strings are written verbatim; objects are JSON-encoded. */
+  data: string | object
+  /** Optional event name — populates `event:` field. */
+  event?: string
+  /** Optional event id — populates `id:` field. */
+  id?: string
+  /** Optional retry hint in milliseconds — populates `retry:` field. */
+  retry?: number
+}
+
+/**
+ * Handle for an open SSE connection. Returned by {@link sse}. Use `send()`
+ * to push events, `comment()` for keep-alive frames, and `close()` to end
+ * the response stream cleanly.
+ */
+export interface SseStream {
+  /**
+   * Send a single event. A bare string is treated as `{ data: <string> }`.
+   */
+  send(event: SseEvent | string): void
+  /** Write a comment line (`: <text>`). Useful for heartbeats / keep-alive. */
+  comment(text: string): void
+  /** End the response stream. Subsequent calls are no-ops. */
+  close(): void
+  /** Whether the underlying stream has been closed (locally or by the client). */
+  readonly closed: boolean
+}
+
+/**
+ * Open a Server-Sent Events response on the given context. Sets the
+ * appropriate headers (`Content-Type: text/event-stream`, no caching, no
+ * proxy buffering) and wires a `PassThrough` into `ctx.stream()`.
+ *
+ * @example
+ *   app.get('/events', (ctx) => {
+ *     const stream = sse(ctx)
+ *     stream.send({ event: 'hello', data: { msg: 'world' } })
+ *     setTimeout(() => stream.close(), 1000)
+ *   })
+ */
+export function sse(ctx: IngeniumContext): SseStream {
+  const passthrough = new PassThrough()
+
+  // SSE headers — set BEFORE ctx.stream() so the adapter can flush them.
+  ctx.set('cache-control', 'no-cache')
+  ctx.set('connection', 'keep-alive')
+  // Disable proxy buffering (nginx-specific but harmless elsewhere).
+  ctx.set('x-accel-buffering', 'no')
+
+  ctx.stream(passthrough, 'text/event-stream; charset=utf-8')
+
+  let closed = false
+  passthrough.on('close', () => {
+    closed = true
+  })
+
+  function write(chunk: string): void {
+    if (closed) return
+    if (!passthrough.writable) {
+      closed = true
+      return
+    }
+    passthrough.write(chunk)
+  }
+
+  return {
+    get closed(): boolean {
+      return closed
+    },
+
+    send(eventOrString: SseEvent | string): void {
+      if (closed) return
+      const evt: SseEvent =
+        typeof eventOrString === 'string' ? { data: eventOrString } : eventOrString
+
+      let frame = ''
+      if (evt.event !== undefined) frame += `event: ${evt.event}\n`
+      if (evt.id !== undefined) frame += `id: ${evt.id}\n`
+      if (evt.retry !== undefined) frame += `retry: ${evt.retry}\n`
+
+      const dataStr =
+        typeof evt.data === 'string' ? evt.data : JSON.stringify(evt.data)
+      // Spec: split on newlines, emit one `data:` line per chunk.
+      const lines = dataStr.split('\n')
+      for (const line of lines) {
+        frame += `data: ${line}\n`
+      }
+      frame += '\n'
+      write(frame)
+    },
+
+    comment(text: string): void {
+      if (closed) return
+      // Comment lines start with ':'. Use \n\n terminator to flush.
+      write(`: ${text}\n\n`)
+    },
+
+    close(): void {
+      if (closed) return
+      closed = true
+      passthrough.end()
+    },
+  }
+}

package/src/static/middleware.ts

@@ -0,0 +1,254 @@
+import { createReadStream } from 'node:fs'
+import { stat } from 'node:fs/promises'
+import * as path from 'node:path'
+import type { Stats } from 'node:fs'
+import type { IngeniumMiddleware } from '../middleware/types.ts'
+import type { StaticOptions } from './types.ts'
+
+/**
+ * Minimal MIME table — extension (lowercase, without dot) → content-type.
+ * Unknown extensions fall back to `application/octet-stream`.
+ */
+const MIME_TYPES: Readonly<Record<string, string>> = {
+  html: 'text/html; charset=utf-8',
+  css: 'text/css; charset=utf-8',
+  js: 'application/javascript; charset=utf-8',
+  mjs: 'application/javascript; charset=utf-8',
+  json: 'application/json; charset=utf-8',
+  svg: 'image/svg+xml',
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  ico: 'image/x-icon',
+  txt: 'text/plain; charset=utf-8',
+  woff: 'font/woff',
+  woff2: 'font/woff2',
+}
+
+const DEFAULT_INDEX = 'index.html'
+
+function mimeFor(file: string): string {
+  const ext = path.extname(file).slice(1).toLowerCase()
+  return MIME_TYPES[ext] ?? 'application/octet-stream'
+}
+
+function makeEtag(stats: Stats): string {
+  // Express-style weak etag: W/"<size>-<mtimeMs-as-hex>"
+  return `W/"${stats.size.toString(16)}-${Math.floor(stats.mtimeMs).toString(16)}"`
+}
+
+/**
+ * Parse a `Range: bytes=N-M` header against a known total size.
+ * Returns `{ start, end }` (inclusive), `'invalid'` if the header is malformed
+ * or unsatisfiable (caller should respond 416), or `null` if no/multi range
+ * (caller should serve the full body).
+ */
+function parseRange(
+  header: string | undefined,
+  size: number,
+): { start: number; end: number } | 'invalid' | null {
+  if (!header) return null
+  if (!header.startsWith('bytes=')) return null
+  const spec = header.slice(6)
+  // Multiple ranges: not supported — fall back to full body.
+  if (spec.includes(',')) return null
+  const dash = spec.indexOf('-')
+  if (dash === -1) return 'invalid'
+  const startStr = spec.slice(0, dash)
+  const endStr = spec.slice(dash + 1)
+  let start: number
+  let end: number
+  if (startStr === '') {
+    // Suffix range: bytes=-N → last N bytes
+    const suffix = Number(endStr)
+    if (!Number.isFinite(suffix) || suffix <= 0) return 'invalid'
+    start = Math.max(0, size - suffix)
+    end = size - 1
+  } else {
+    start = Number(startStr)
+    end = endStr === '' ? size - 1 : Number(endStr)
+    if (!Number.isFinite(start) || !Number.isFinite(end)) return 'invalid'
+    if (start < 0 || end < start) return 'invalid'
+    if (start >= size) return 'invalid'
+    if (end >= size) end = size - 1
+  }
+  return { start, end }
+}
+
+/**
+ * Static-file middleware. Serves files from `root`, supporting directory
+ * indexes, weak ETags, `If-None-Match`, byte-range requests, and basic
+ * dotfile policy. Misses (file not found) call `next()` — they do NOT
+ * write 404 themselves, so downstream routes still get a chance.
+ *
+ * @example
+ *   app.use(ingenium.static('./public', { maxAge: 60_000 }))
+ */
+export function staticMiddleware(root: string, opts: StaticOptions = {}): IngeniumMiddleware {
+  const absRoot = path.resolve(root)
+  const indexFile = opts.index === undefined ? DEFAULT_INDEX : opts.index
+  const maxAgeMs = opts.maxAge ?? 0
+  const cacheControl = `public, max-age=${Math.floor(maxAgeMs / 1000)}`
+  const extensions = opts.extensions ?? []
+  const dotfiles = opts.dotfiles ?? 'ignore'
+
+  return async (ctx, next) => {
+    // Only GET / HEAD make sense for static.
+    if (ctx.method !== 'GET' && ctx.method !== 'HEAD') {
+      return next()
+    }
+
+    // Decode percent-escapes; reject malformed URLs.
+    let urlPath: string
+    try {
+      urlPath = decodeURIComponent(ctx.path)
+    } catch {
+      ctx.status(400).text('Bad Request')
+      return
+    }
+
+    // Path-traversal protection: resolve, then ensure it stays under root.
+    const joined = path.join(absRoot, urlPath)
+    const resolved = path.resolve(joined)
+    const isUnderRoot =
+      resolved === absRoot ||
+      resolved.startsWith(absRoot + path.sep)
+    if (!isUnderRoot) {
+      ctx.status(403).text('Forbidden')
+      return
+    }
+
+    // Dotfile policy: check every segment of the path BELOW root.
+    const rel = path.relative(absRoot, resolved)
+    const segments = rel.length === 0 ? [] : rel.split(/[/\\]/)
+    const hasDot = segments.some((s) => s.length > 0 && s.startsWith('.'))
+    if (hasDot) {
+      if (dotfiles === 'deny') {
+        ctx.status(403).text('Forbidden')
+        return
+      }
+      if (dotfiles === 'ignore') {
+        return next()
+      }
+      // 'allow' falls through.
+    }
+
+    // Try to stat the resolved path. Fall through on ENOENT / not-a-file.
+    let target = resolved
+    let stats: Stats | null = null
+    try {
+      stats = await stat(target)
+    } catch {
+      stats = null
+    }
+
+    // Try `extensions` if the bare path didn't exist.
+    if (!stats && extensions.length > 0) {
+      for (const ext of extensions) {
+        const withExt = `${target}.${ext.replace(/^\./, '')}`
+        try {
+          const s = await stat(withExt)
+          if (s.isFile()) {
+            target = withExt
+            stats = s
+            break
+          }
+        } catch {
+          // try next
+        }
+      }
+    }
+
+    // Directory → optional index file.
+    if (stats && stats.isDirectory()) {
+      if (!indexFile) return next()
+      const idx = path.join(target, indexFile)
+      try {
+        const s = await stat(idx)
+        if (s.isFile()) {
+          target = idx
+          stats = s
+        } else {
+          return next()
+        }
+      } catch {
+        return next()
+      }
+    }
+
+    if (!stats || !stats.isFile()) {
+      return next()
+    }
+
+    // ───── Cacheable response headers ─────
+    const etag = makeEtag(stats)
+    const lastModified = new Date(stats.mtimeMs).toUTCString()
+    ctx.set('etag', etag)
+    ctx.set('last-modified', lastModified)
+    ctx.set('cache-control', cacheControl)
+    ctx.set('content-type', mimeFor(target))
+    ctx.set('accept-ranges', 'bytes')
+
+    // Conditional GET via If-None-Match (preferred) or If-Modified-Since
+    // (fallback per RFC 7232 §6). If-None-Match wins when both are present.
+    const ifNoneMatch = ctx.headers['if-none-match']
+    let notModified = typeof ifNoneMatch === 'string' && ifNoneMatch === etag
+
+    if (!notModified && !ifNoneMatch) {
+      const ifModifiedSince = ctx.headers['if-modified-since']
+      if (typeof ifModifiedSince === 'string') {
+        const sinceMs = Date.parse(ifModifiedSince)
+        // mtime is compared at second-resolution because HTTP-dates have no
+        // sub-second precision — Math.floor matches both sides.
+        const lastMs = Math.floor(stats.mtimeMs / 1000) * 1000
+        if (Number.isFinite(sinceMs) && lastMs <= sinceMs) notModified = true
+      }
+    }
+
+    if (notModified) {
+      ctx.status(304)
+      // 304 must not have a body.
+      ctx._body = { kind: 'none' }
+      ctx._written = true
+      return
+    }
+
+    const size = stats.size
+    const rangeHeader = ctx.headers.range
+    const range = parseRange(typeof rangeHeader === 'string' ? rangeHeader : undefined, size)
+
+    if (range === 'invalid') {
+      ctx.status(416)
+      ctx.set('content-range', `bytes */${size}`)
+      ctx._body = { kind: 'none' }
+      ctx._written = true
+      return
+    }
+
+    if (range) {
+      const { start, end } = range
+      const chunk = end - start + 1
+      ctx.status(206)
+      ctx.set('content-range', `bytes ${start}-${end}/${size}`)
+      ctx.set('content-length', String(chunk))
+      if (ctx.method === 'HEAD') {
+        ctx._body = { kind: 'none' }
+        ctx._written = true
+        return
+      }
+      ctx.stream(createReadStream(target, { start, end }))
+      return
+    }
+
+    // Full body.
+    ctx.set('content-length', String(size))
+    if (ctx.method === 'HEAD') {
+      ctx._body = { kind: 'none' }
+      ctx._written = true
+      return
+    }
+    ctx.stream(createReadStream(target))
+  }
+}

package/src/static/types.ts

@@ -0,0 +1,31 @@
+/**
+ * Options for the `ingenium.static` middleware.
+ */
+export interface StaticOptions {
+  /**
+   * The file to serve when a directory is requested. Set to `false` to
+   * disable directory-index resolution. Default: `'index.html'`.
+   */
+  index?: string | false
+
+  /**
+   * `Cache-Control: max-age=<seconds>` to set on served files, in
+   * MILLISECONDS (Express convention). Default: `0` (no caching).
+   */
+  maxAge?: number
+
+  /**
+   * Extensions to try (in order) when the requested path doesn't exist.
+   * For example, `['html']` lets `/about` resolve to `/about.html`.
+   * Default: `[]` (off).
+   */
+  extensions?: string[]
+
+  /**
+   * How to treat files / directories whose name starts with `.`:
+   * - `'allow'`  — serve normally
+   * - `'deny'`   — respond with 403
+   * - `'ignore'` — call `next()` (let routes 404 it). DEFAULT.
+   */
+  dotfiles?: 'allow' | 'deny' | 'ignore'
+}