@swarmmachina/swm-core 1.1.5 → 1.3.0

package/README.md

@@ -26,6 +26,22 @@ on [uWebSockets.js](https://github.com/uNetworking/uWebSockets.js).
 npm install @swarmmachina/swm-core
 ```
 
+### Runtime requirements
+
+This package depends on the native [uWebSockets.js](https://github.com/uNetworking/uWebSockets.js)
+addon, which imposes a few constraints on the install/runtime environment:
+
+- **Node.js 22+** — required by both this package and the bundled uWS prebuilt.
+- **glibc, not musl** — the prebuilt binaries target glibc. Use a `bookworm`/`slim`
+  (Debian) base image rather than `alpine` (musl), otherwise the native module fails to load.
+- **Architecture-specific prebuilt** — the loaded binary must match the host CPU
+  architecture and Node ABI. When building container images, build for the same
+  platform you deploy to (e.g. `--platform linux/amd64`); a binary built on
+  arm64 will not run on an amd64 server.
+- **Network access to GitHub at install time** — uWS is pulled from a GitHub tag
+  (`uNetworking/uWebSockets.js#v20.67.0`), so `npm install` needs outbound access
+  to GitHub. Offline/air-gapped installs require a pre-populated cache or mirror.
+
 ## Quick Start
 
 ### Basic HTTP Server
@@ -146,6 +162,7 @@ await server.listen()
 - **URL Parameters** - Built-in support for `:param` syntax
 - **Cleaner Code** - Declarative route definitions
 - **Method-specific** - Automatic HTTP method routing
+- **Wildcard catch-all** - A `{ method: 'any', path: '/*' }` route matches anything not matched by a more specific route (useful as a 404 handler or static-file fallback). Specific routes always win over `/*`.
 
 ### WebSocket Server
 
@@ -208,11 +225,12 @@ new Server(options)
 
 **Route Definition (for `routes` array):**
 
-| Property  | Type       | Description                                                                                    |
-| --------- | ---------- | ---------------------------------------------------------------------------------------------- |
-| `method`  | `String`   | HTTP method: `'get'`, `'post'`, `'put'`, `'delete'`, `'patch'`, `'options'`, `'head'`, `'any'` |
-| `path`    | `String`   | URL path pattern (supports `:param` syntax)                                                    |
-| `handler` | `Function` | Handler function `(ctx) => any \| Promise<any>`                                                |
+| Property     | Type               | Description                                                                                            |
+| ------------ | ------------------ | ------------------------------------------------------------------------------------------------------ |
+| `method`     | `String`           | HTTP method: `'get'`, `'post'`, `'put'`, `'delete'`, `'patch'`, `'options'`, `'head'`, `'any'`         |
+| `path`       | `String`           | URL path pattern. Supports `:param` segments and a `/*` wildcard catch-all                             |
+| `handler`    | `Function`         | Handler function `(ctx) => any \| Promise<any>`                                                        |
+| `preHandler` | `Function`/`Array` | Optional. One function or an array, run before `handler` (see [Route preHandlers](#route-prehandlers)) |
 
 **WebSocket Options (`ws` object):**
 
@@ -291,7 +309,7 @@ The `ctx` object passed to the router function:
 
 Get request lowercased method.
 
-```javascriptx
+```javascript
 const method = ctx.method()
 ```
 
@@ -408,7 +426,7 @@ ctx.status(201).send({ created: true })
 
 ##### `ctx.setHeader(key, value)`
 
-Set a response header. Returns context for chaining.
+Set or replace a staged response header. Header names are case-insensitive. Repeated `setHeader()` calls replace previously staged values for the same header. Null or undefined values are silently ignored.
 
 ```javascript
 ctx.setHeader('x-header-any', 'string-value').status(201).send({ created: true })
@@ -416,6 +434,37 @@ ctx.setHeader('x-header-any', 'string-value').status(201).send({ created: true }
 
 **Returns:** `HttpContext`
 
+##### `ctx.appendHeader(key, value)`
+
+Append another staged response header line without replacing existing values. Useful for repeated headers such as `Set-Cookie`. Null or undefined values are silently ignored.
+
+```javascript
+ctx.appendHeader('set-cookie', 'access=...; Path=/; HttpOnly')
+ctx.appendHeader('set-cookie', 'refresh=...; Path=/refresh; HttpOnly')
+```
+
+**Returns:** `HttpContext`
+
+##### `ctx.setHeaders(headers)`
+
+Set multiple response headers at once. Equivalent to calling `setHeader()` for each key. Header values may be strings or arrays of strings.
+
+```javascript
+ctx.setHeaders({
+  'x-request-id': '123',
+  'cache-control': 'no-cache',
+  'set-cookie': ['a=1; Path=/', 'b=2; Path=/refresh']
+})
+```
+
+##### `ctx.flushHeaders([headers])`
+
+Flush all staged headers (and optionally stage additional ones) to the underlying response. Called automatically by `reply()` and `startStreaming()` — only needed for advanced use cases.
+
+```javascript
+ctx.flushHeaders({ 'x-extra': 'value' })
+```
+
 ##### `ctx.send(data)`
 
 Send response with automatic content-type detection.
@@ -429,12 +478,59 @@ ctx.send(null) // 204 No Content
 
 **Supported types:** Object, String, Buffer, null, undefined
 
+##### `ctx.sendJson(data, [status])`
+
+Send a JSON response with explicit status code. Defaults to `200`.
+
+```javascript
+ctx.sendJson({ users: [] })
+ctx.sendJson({ error: 'Not found' }, 404)
+```
+
+##### `ctx.sendText(text, [status])`
+
+Send a plain text response with explicit status code. Defaults to `200`.
+
+```javascript
+ctx.sendText('OK')
+ctx.sendText('Created', 201)
+```
+
+##### `ctx.sendBuffer(buffer, [status])`
+
+Send a binary response with explicit status code. Defaults to `200`.
+
+```javascript
+ctx.sendBuffer(Buffer.from('data'))
+ctx.sendBuffer(imageBuffer, 201)
+```
+
+##### `ctx.sendError(error)`
+
+Send an error response. If `error.status` is a finite number, uses that as the HTTP status with `error.message` as the body. Otherwise responds with `500 Internal Server Error`.
+
+```javascript
+ctx.sendError(new Error('Something broke'))
+
+// With custom status
+const err = new Error('Not found')
+err.status = 404
+ctx.sendError(err)
+```
+
 ##### `ctx.reply(status, headers, body)`
 
-Send response with full control over status, headers, and body.
+Send response with full control over status, headers, and body. Header values may be strings or arrays of strings. Array values are written as separate header lines.
 
 ```javascript
-ctx.reply(200, { 'content-type': 'application/json' }, '{"ok":true}')
+ctx.reply(
+  200,
+  {
+    'content-type': 'application/json',
+    'set-cookie': ['a=1; Path=/', 'b=2; Path=/refresh']
+  },
+  '{"ok":true}'
+)
 ```
 
 ##### `ctx.stream(readable, [status], [headers])`
@@ -452,10 +548,13 @@ await ctx.stream(stream, 200, { 'content-type': 'video/mp4' })
 
 ##### `ctx.startStreaming([status], [headers])`
 
-Start streaming response manually (for advanced use cases).
+Start streaming response manually (for advanced use cases). Header values may be strings or arrays of strings.
 
 ```javascript
-ctx.startStreaming(200, { 'content-type': 'text/plain' })
+ctx.startStreaming(200, {
+  'content-type': 'text/plain',
+  'set-cookie': ['a=1; Path=/', 'b=2; Path=/refresh']
+})
 ```
 
 ##### `ctx.write(chunk)`
@@ -824,6 +923,34 @@ process.on('SIGINT', () => {
 })
 ```
 
+### Route preHandlers
+
+A route may declare a `preHandler` — one function or an array — run before its
+`handler` (auth, logging, validation).
+
+```javascript
+const requireAuth = (ctx) => {
+  if (ctx.header('authorization') !== 'Bearer secret') {
+    ctx.status(401).send('Unauthorized') // replying short-circuits the chain
+  }
+}
+
+const server = new Server({
+  routes: [
+    {
+      method: 'get',
+      path: '/admin',
+      preHandler: requireAuth,
+      handler: () => ({ ok: true })
+    }
+  ]
+})
+```
+
+- Run in order, sync or async (awaited); replying (`ctx.replied`) stops the chain.
+- Composed once at registration — zero per-request cost for routes without one.
+- Native `routes` API only (not the `router` function).
+
 ### Custom Response Headers
 
 ```javascript
@@ -844,6 +971,70 @@ const server = new Server({
 })
 ```
 
+### CORS
+
+`cors(options)` stages CORS headers and replies to preflight (`OPTIONS`) requests.
+Call it at the top of a handler; it returns `true` when it handled the preflight.
+
+```javascript
+import Server, { cors } from '@swarmmachina/swm-core'
+
+const applyCors = cors({
+  origin: 'https://app.example', // default '*'
+  credentials: true, // default false
+  maxAge: 600 // optional, preflight cache seconds
+})
+
+const server = new Server({
+  routes: [
+    {
+      method: 'any',
+      path: '/*',
+      handler: (ctx) => {
+        if (applyCors(ctx)) {
+          return // preflight handled (204)
+        }
+
+        return { ok: true }
+      }
+    }
+  ]
+})
+```
+
+Options: `origin` (default `'*'`), `methods`, `allowedHeaders`, `credentials`,
+`maxAge`. A non-`'*'` `origin` appends `Vary: Origin`; `credentials` requires an
+explicit `origin`.
+
+### Serving Static Files
+
+`serveStatic(root, options)` returns a handler for a wildcard `/*` route (specific
+routes still take precedence). It guards against path traversal, sets Content-Type
+by extension, and caches file contents in memory.
+
+```javascript
+import Server, { serveStatic } from '@swarmmachina/swm-core'
+
+const server = new Server({
+  routes: [
+    { method: 'get', path: '/api/health', handler: () => ({ ok: true }) },
+    {
+      method: 'get',
+      path: '/*',
+      handler: serveStatic('./public', {
+        spa: true, // fall back to index.html for unmatched paths (default false)
+        maxAge: 3600 // optional Cache-Control: public, max-age=<seconds>
+      })
+    }
+  ]
+})
+```
+
+Options: `spa` (fall back to `index`), `index` (default `'index.html'`), `cache`
+(default `true`; set `false` in dev to pick up edits), `cacheLimit` (max cached
+files, default `128`), `maxAge` (`Cache-Control` seconds). Misses return `404`,
+traversal `403`, non-`GET`/`HEAD` `405`.
+
 ### Backpressure Handling
 
 ```javascript
@@ -881,6 +1072,62 @@ npm test
 npm test:coverage
 ```
 
+## Regression profiling (CI)
+
+`npm run profile:ci` runs the regression-profiling suites (HTTP, body-parser and
+WebSocket), records CPU profiles and memory peaks, and fails on a guard breach.
+In CI it runs only on push to `master` and `workflow_dispatch` (see
+`.github/workflows/ci.yml`) and uploads the `regression-profiles` artifact.
+Thresholds live in `benchmark/baselines/*.json`.
+
+GitHub's shared runners are noisy — throughput can swing 30–40% between runs — so
+absolute thresholds there only catch large regressions. Running the profiling job
+on a quiet self-hosted runner removes that noise and lets the thresholds be
+tightened enough to catch small regressions.
+
+### Self-hosted runner
+
+Only the gated `regression-profile` job uses the self-hosted runner; the `test`
+job stays on `ubuntu-latest`.
+
+> **Public-repository note.** The `regression-profile` job is gated to
+> `push`/`workflow_dispatch`, so fork pull requests never reach the self-hosted
+> machine — they only run `test` on `ubuntu-latest`. Anything merged to `master`
+> still executes on the runner, so treat the host as exposed: dedicated
+> unprivileged user, firewalled, no production secrets, ephemeral runner.
+
+**1. Register the runner** (repo Settings → Actions → Runners → New self-hosted
+runner). The connection is outbound-only — no inbound ports, works behind NAT:
+
+```bash
+./config.sh --url https://github.com/<owner>/<repo> --token <RUNNER_TOKEN> --labels bench --ephemeral
+sudo ./svc.sh install <user>
+sudo ./svc.sh start
+```
+
+**2. Harden the host.**
+
+- Run the runner as a dedicated unprivileged user, never root.
+- Keep the host firewalled; allow only outbound HTTPS to GitHub.
+- Do not expose repository or production secrets to the runner.
+- `--ephemeral` de-registers the runner after each job, limiting persistence.
+
+**3. Tune for low noise** (otherwise the variance returns):
+
+```bash
+sudo cpupower frequency-set -g performance
+```
+
+Keep the host idle during a run; optionally pin the runner to dedicated cores.
+
+**4. Point the job at the runner.** In `.github/workflows/ci.yml`, set the
+`regression-profile` job to `runs-on: [self-hosted, Linux, bench]`.
+
+**5. Recalibrate.** Throughput and memory numbers differ per machine, so recalibrate
+`benchmark/baselines/*.json` on the self-hosted runner: collect a few green runs,
+then set each guard just past the observed noise floor (throughput `min` ≈ observed
+low × 0.9; latency and memory `max` ≈ observed high × 1.15).
+
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmmachina/swm-core",
-  "version": "1.1.5",
+  "version": "1.3.0",
   "description": "Zero-dependency high-performance HTTP/WebSocket server built on uWebSockets.js",
   "keywords": [
     "http",
@@ -15,12 +15,16 @@
   "author": "SwarmMachina Team",
   "license": "MPL-2.0",
   "main": "src/index.js",
+  "types": "./src/index.d.ts",
   "type": "module",
   "engines": {
     "node": ">=22.0.0"
   },
   "exports": {
-    ".": "./src/index.js"
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
   },
   "files": [
     "src/",
@@ -44,18 +48,24 @@
     "test:e2e:ws": "node --test tests/e2e/ws/*.test.js",
     "bench": "node ./benchmark/bench.js --test base --runs 1 --warmup 10 --sample-ms 250 --v8prof true",
     "bench:core": "node ./benchmark/bench.js --test base --runs 1 --warmup 10 --sample-ms 250 --v8prof true --fw core",
+    "bench:headers": "node ./benchmark/bench.js --test headers --runs 1 --warmup 10 --sample-ms 250 --v8prof true",
+    "bench:headers:core": "node ./benchmark/bench.js --test headers --runs 1 --warmup 10 --sample-ms 250 --v8prof true --fw core",
+    "bench:ws": "node ./benchmark/ws-bench.js --fw core,ws --runs 1 --warmup 2 --v8prof true",
+    "bench:prehandler": "node ./benchmark/prehandler-bench.js",
+    "profile:ci": "node ./benchmark/regression-ci.js",
+    "profile:compare": "node ./benchmark/compare-ci.js",
     "prepublishOnly": "npm run fix && npm test",
     "release": "npm run check && npm test && npm publish"
   },
   "dependencies": {
-    "uwebsockets.js": "uNetworking/uWebSockets.js#v20.56.0"
+    "uwebsockets.js": "uNetworking/uWebSockets.js#v20.67.0"
   },
   "devDependencies": {
-    "@swarmmachina/standards": "^1.0.1",
+    "@swarmmachina/standards": "^1.0.3",
     "autocannon": "^8.0.0",
     "express": "^5.2.1",
-    "fastify": "^5.6.2",
+    "fastify": "^5.8.5",
     "micro": "^10.0.1",
-    "ws": "^8.18.3"
+    "ws": "^8.21.0"
   }
 }

package/src/cors.js

@@ -0,0 +1,53 @@
+const DEFAULT_METHODS = 'GET,HEAD,PUT,PATCH,POST,DELETE'
+const DEFAULT_HEADERS = 'Content-Type, Authorization'
+
+/**
+ * @typedef {object} CorsOptions
+ * @property {string} [origin]
+ * @property {string} [methods]
+ * @property {string} [allowedHeaders]
+ * @property {boolean} [credentials]
+ * @property {number} [maxAge]
+ */
+
+/**
+ * @param {CorsOptions} [options]
+ * @returns {(ctx: import('./http-context.js').default) => boolean}
+ */
+export default function cors(options = {}) {
+  const origin = options.origin ?? '*'
+  const methods = options.methods ?? DEFAULT_METHODS
+  const allowedHeaders = options.allowedHeaders ?? DEFAULT_HEADERS
+  const credentials = options.credentials === true
+  const maxAge = options.maxAge
+
+  if (credentials && origin === '*') {
+    throw new TypeError("cors: 'credentials' requires an explicit 'origin' (wildcard '*' is rejected by browsers)")
+  }
+
+  return function applyCors(ctx) {
+    ctx.setHeader('access-control-allow-origin', origin)
+
+    if (origin !== '*') {
+      ctx.appendHeader('vary', 'Origin')
+    }
+
+    if (credentials) {
+      ctx.setHeader('access-control-allow-credentials', 'true')
+    }
+
+    if (ctx.method() !== 'options') {
+      return false
+    }
+
+    ctx.setHeader('access-control-allow-methods', methods)
+    ctx.setHeader('access-control-allow-headers', allowedHeaders)
+
+    if (maxAge != null) {
+      ctx.setHeader('access-control-max-age', `${maxAge}`)
+    }
+
+    ctx.reply(204, null, null)
+    return true
+  }
+}

package/src/http-context.js

@@ -36,12 +36,14 @@ export default class HttpContext {
   }
 
   onResolve = (result) => {
-    if (this.done || this.aborted || this.replied) {
+    if (this.done || this.aborted) {
       return
     }
 
     try {
-      this.send(result)
+      if (!this.replied) {
+        this.send(result)
+      }
     } catch (err) {
       if (!this.replied) {
         try {
@@ -60,14 +62,16 @@ export default class HttpContext {
   }
 
   onReject = (err) => {
-    if (this.done || this.aborted || this.replied) {
+    if (this.done || this.aborted) {
       return
     }
 
-    try {
-      this.sendError(err)
-    } catch {
-      //
+    if (!this.replied) {
+      try {
+        this.sendError(err)
+      } catch {
+        //
+      }
     }
 
     void this.server.safeHttpError(this, err)
@@ -428,12 +432,61 @@ export default class HttpContext {
       return this
     }
 
-    this.#stageHeader(key, value)
+    if (typeof key !== 'string') {
+      throw new TypeError('Header name must be a string')
+    }
+
+    if (value === undefined || value === null) {
+      return this
+    }
+
+    const headerKey = key.toLowerCase()
+
+    this.#pendingHeaders.set(headerKey, [key, `${value}`])
     return this
   }
 
   /**
-   * @param {Record<string, string> | null | undefined} headers
+   * @param {string} key
+   * @param {string} value
+   * @returns {HttpContext}
+   */
+  appendHeader(key, value) {
+    if (this.replied || this.aborted) {
+      return this
+    }
+
+    if (typeof key !== 'string') {
+      throw new TypeError('Header name must be a string')
+    }
+
+    if (value === undefined || value === null) {
+      return this
+    }
+
+    const headerKey = key.toLowerCase()
+    const headerValue = `${value}`
+    const pendingHeader = this.#pendingHeaders.get(headerKey)
+
+    if (!pendingHeader) {
+      this.#pendingHeaders.set(headerKey, [key, headerValue])
+      return this
+    }
+
+    pendingHeader[0] = key
+    const cur = pendingHeader[1]
+
+    if (typeof cur === 'string') {
+      pendingHeader[1] = [cur, headerValue]
+    } else {
+      cur[cur.length] = headerValue
+    }
+
+    return this
+  }
+
+  /**
+   * @param {Record<string, string | string[]> | null | undefined} headers
    */
   setHeaders(headers) {
     if (this.replied || this.aborted) {
@@ -444,7 +497,7 @@ export default class HttpContext {
   }
 
   /**
-   * @param {Record<string, string> | null | undefined} headers
+   * @param {Record<string, string | string[]> | null | undefined} headers
    */
   flushHeaders(headers = null) {
     this.#flushPendingHeaders(headers)
@@ -452,21 +505,83 @@ export default class HttpContext {
 
   /**
    * @param {string} key
-   * @param {string} value
+   * @param {string | string[] | null | undefined} value
+   * @param {boolean} append
    */
-  #stageHeader(key, value) {
+  #stagePendingHeader(key, value, append) {
     if (value === undefined || value === null) {
       return
     }
 
-    const headerName = String(key)
-    const headerValue = String(value)
+    const headerKey = key.toLowerCase()
 
-    this.#pendingHeaders.set(headerName.toLowerCase(), [headerName, headerValue])
+    if (!Array.isArray(value)) {
+      const headerValue = `${value}`
+
+      if (!append) {
+        this.#pendingHeaders.set(headerKey, [key, headerValue])
+        return
+      }
+
+      const pendingHeader = this.#pendingHeaders.get(headerKey)
+
+      if (!pendingHeader) {
+        this.#pendingHeaders.set(headerKey, [key, headerValue])
+        return
+      }
+
+      pendingHeader[0] = key
+      const cur = pendingHeader[1]
+
+      if (typeof cur === 'string') {
+        pendingHeader[1] = [cur, headerValue]
+      } else {
+        cur[cur.length] = headerValue
+      }
+
+      return
+    }
+
+    this.#stagePendingHeaderArray(key, headerKey, value, append)
   }
 
   /**
-   * @param {Record<string, string> | null | undefined} headers
+   * @param {string} key
+   * @param {string} headerKey
+   * @param {string[]} value
+   * @param {boolean} append
+   */
+  #stagePendingHeaderArray(key, headerKey, value, append) {
+    let pendingHeader = append ? this.#pendingHeaders.get(headerKey) : null
+
+    for (let i = 0, len = value.length; i < len; i++) {
+      const entry = value[i]
+
+      if (entry === undefined || entry === null) {
+        continue
+      }
+
+      const headerValue = `${entry}`
+
+      if (!pendingHeader) {
+        pendingHeader = [key, headerValue]
+        this.#pendingHeaders.set(headerKey, pendingHeader)
+        continue
+      }
+
+      pendingHeader[0] = key
+      const cur = pendingHeader[1]
+
+      if (typeof cur === 'string') {
+        pendingHeader[1] = [cur, headerValue]
+      } else {
+        cur[cur.length] = headerValue
+      }
+    }
+  }
+
+  /**
+   * @param {Record<string, string | string[]> | null | undefined} headers
    */
   #stageHeaders(headers) {
     if (!headers) {
@@ -474,29 +589,27 @@ export default class HttpContext {
     }
 
     if (headers === TEXT_PLAIN_HEADER) {
-      this.#stageHeader('content-type', 'text/plain; charset=utf-8')
+      this.#pendingHeaders.set('content-type', ['content-type', 'text/plain; charset=utf-8'])
       return
     }
 
     if (headers === JSON_HEADER) {
-      this.#stageHeader('content-type', 'application/json; charset=utf-8')
+      this.#pendingHeaders.set('content-type', ['content-type', 'application/json; charset=utf-8'])
       return
     }
 
     if (headers === OCTET_STREAM_HEADER) {
-      this.#stageHeader('content-type', 'application/octet-stream')
+      this.#pendingHeaders.set('content-type', ['content-type', 'application/octet-stream'])
       return
     }
 
     for (const key in headers) {
-      const value = headers[key]
-
-      this.#stageHeader(key, value)
+      this.#stagePendingHeader(key, headers[key], false)
     }
   }
 
   /**
-   * @param {Record<string, string> | null | undefined} headers
+   * @param {Record<string, string | string[]> | null | undefined} headers
    */
   #flushPendingHeaders(headers = null) {
     if (!this.res) {
@@ -508,8 +621,19 @@ export default class HttpContext {
       this.#stageHeaders(headers)
     }
 
-    for (const [, [key, value]] of this.#pendingHeaders) {
-      this.res.writeHeader(key, value)
+    for (const [, pendingHeader] of this.#pendingHeaders) {
+      const headerValue = pendingHeader[1]
+
+      if (typeof headerValue === 'string') {
+        this.res.writeHeader(pendingHeader[0], headerValue)
+        continue
+      }
+
+      const name = pendingHeader[0]
+
+      for (let i = 0, len = headerValue.length; i < len; i++) {
+        this.res.writeHeader(name, headerValue[i])
+      }
     }
 
     this.#pendingHeaders.clear()
@@ -582,7 +706,7 @@ export default class HttpContext {
 
   /**
    * @param {number} status
-   * @param {Record<string,string>} headers
+   * @param {Record<string, string | string[]>} headers
    * @param {string|ArrayBuffer|Uint8Array|Buffer|null|undefined} body
    */
   reply(status = 200, headers = null, body = null) {
@@ -610,7 +734,7 @@ export default class HttpContext {
 
   /**
    * @param {number} status
-   * @param {Record<string,string>} headers
+   * @param {Record<string, string | string[]>} headers
    * @returns {HttpContext}
    */
   startStreaming(status = 200, headers = null) {

package/src/index.d.ts

@@ -0,0 +1,168 @@
+import type { Readable } from 'node:stream'
+
+export type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'del' | 'patch' | 'options' | 'head' | 'any'
+
+/** Body payload accepted by response/streaming writers. */
+export type HttpBody = string | ArrayBuffer | ArrayBufferView | Buffer
+
+/** Response headers map; values may be a single string or repeated as an array. */
+export type HttpHeaders = Record<string, string | string[]>
+
+/** HTTP route handler. Its return value is sent via `ctx.send()` unless the response was already written. */
+export type Handler = (ctx: HttpContext) => any | Promise<any>
+
+export interface Route {
+  method: HttpMethod
+  path: string
+  handler: Handler
+  /** One handler or a chain, run before `handler`. Replying short-circuits the chain. Native `routes` only. */
+  preHandler?: Handler | Handler[]
+}
+
+/** Metadata passed to `ws.onUpgrade`. */
+export interface UpgradeMeta {
+  url(): string
+  ip(): string
+  getParameter(index: number): string
+  getQuery(key?: string): string
+  getHeader(name: string): string
+  aborted: boolean
+}
+
+export interface UpgradeResult {
+  isAllowed: boolean
+  userData?: object
+}
+
+export interface WSOptions {
+  enabled?: boolean
+  wsIdleTimeoutSec?: number
+  onOpen?: (ctx: WSContext) => any
+  onMessage?: (ctx: WSContext, message: ArrayBuffer, isBinary: boolean) => any
+  onClose?: (ctx: WSContext, code: number, message: ArrayBuffer) => any
+  onDrain?: (ctx: WSContext) => any
+  onError?: (ctx: WSContext | null, err: Error) => any
+  onUpgrade?: (meta: UpgradeMeta) => UpgradeResult | Promise<UpgradeResult>
+  onSubscription?: (ctx: WSContext, topic: ArrayBuffer, newCount: number, oldCount: number) => any
+}
+
+export interface ServerOptions {
+  /** Universal router function (micro-like API). Provide either `router` or `routes`, not both. */
+  router?: Handler
+  /** Native routing API: an array of route definitions. Provide either `router` or `routes`, not both. */
+  routes?: Route[]
+  onHttpError?: (ctx: HttpContext, err: Error) => any | Promise<any>
+  /** @default 6000 */
+  port?: number
+  /** Max request body size in MB (1-64). @default 1 */
+  maxBodySize?: number
+  ws?: WSOptions
+}
+
+/** Per-request context passed to HTTP handlers. Instances are pooled and reused. */
+export class HttpContext {
+  /** Whether a response has already been sent. */
+  replied: boolean
+  /** Whether the underlying request was aborted by the client. */
+  aborted: boolean
+
+  body(maxSize?: number): Promise<Buffer>
+  buffer(maxSize?: number): Promise<Buffer>
+  text(maxSize?: number): Promise<string>
+  json<T = any>(maxSize?: number): Promise<T>
+
+  ip(): string
+  method(): string
+  url(): string
+  fullQuery(): string
+  query(name: string): string | undefined
+  param(indexOrName: number | string): string | undefined
+  header(name: string): string
+  contentLength(): number | null
+
+  status(code: number): this
+  setHeader(key: string, value: string | number): this
+  appendHeader(key: string, value: string | number): this
+  setHeaders(headers: HttpHeaders | null | undefined): void
+  flushHeaders(headers?: HttpHeaders | null): void
+
+  send(data: any): void
+  sendJson(data: any, status?: number): void
+  sendText(text: string, status?: number): void
+  sendBuffer(buffer: Buffer | Uint8Array | ArrayBuffer, status?: number): void
+  sendError(error: { status?: number; message?: string } | Error): void
+  reply(status?: number, headers?: HttpHeaders | null, body?: HttpBody | null): void
+
+  stream(readable: Readable, status?: number, headers?: HttpHeaders | null): Promise<void>
+  startStreaming(status?: number, headers?: HttpHeaders | null): this
+  write(chunk: HttpBody): boolean
+  end(chunk?: HttpBody): void
+  onWritable(callback: (offset: number) => void): void
+  tryEnd(chunk: HttpBody, totalSize?: number): [boolean, boolean]
+  getWriteOffset(): number
+}
+
+/** Per-connection context passed to WebSocket handlers. Instances are pooled and reused. */
+export class WSContext {
+  /** User data returned from `ws.onUpgrade` (`userData` field). */
+  data: any
+  /** Raw uWebSockets.js WebSocket object. */
+  ws: any
+
+  send(data: string | ArrayBuffer | ArrayBufferView, isBinary?: boolean): number
+  end(code?: number, reason?: string): void
+  subscribe(topic: string): boolean
+  unsubscribe(topic: string): boolean
+  publish(topic: string, message: string | ArrayBuffer | ArrayBufferView, isBinary?: boolean): boolean
+}
+
+export default class Server {
+  constructor(options: ServerOptions)
+
+  readonly port: number
+
+  /** Start the server and begin accepting connections. */
+  listen(): Promise<this>
+  /** Gracefully shut down, waiting up to `timeout` ms for active connections to finish. @default 10000 */
+  shutdown(timeout?: number): Promise<void>
+  /** Forcefully close the server immediately. */
+  close(): void
+  /** Publish a message to all clients subscribed to `topic`. */
+  publish(topic: string, message: string | ArrayBuffer | Uint8Array | Buffer, isBinary?: boolean): boolean
+  /** Number of subscribers for a topic. */
+  getSubscribersCount(topic: string): number
+}
+
+export interface CorsOptions {
+  /** @default '*' */
+  origin?: string
+  methods?: string
+  allowedHeaders?: string
+  /** @default false */
+  credentials?: boolean
+  /** Preflight cache lifetime in seconds. */
+  maxAge?: number
+}
+
+/**
+ * Build a CORS applier. Call it at the top of a handler; it returns `true` when it
+ * already replied to a preflight (`OPTIONS`) request. Throws if `credentials` is set
+ * together with the wildcard `origin` `'*'`.
+ */
+export function cors(options?: CorsOptions): (ctx: HttpContext) => boolean
+
+export interface ServeStaticOptions {
+  /** Fall back to the index file for unmatched paths. @default false */
+  spa?: boolean
+  /** @default 'index.html' */
+  index?: string
+  /** In-memory content cache. @default true */
+  cache?: boolean
+  /** Max number of cached files (FIFO eviction). @default 128 */
+  cacheLimit?: number
+  /** `Cache-Control: public, max-age=<seconds>`. */
+  maxAge?: number
+}
+
+/** Build a handler that serves files from `root`, intended for a wildcard `/*` route. */
+export function serveStatic(root: string, options?: ServeStaticOptions): (ctx: HttpContext) => Promise<void>

package/src/index.js

@@ -5,6 +5,9 @@ import WSContext from './ws-context.js'
 import ContextPool from './context-pool.js'
 import { STATUS_TEXT } from './constants.js'
 
+export { default as cors } from './cors.js'
+export { default as serveStatic } from './serve-static.js'
+
 const WS_CONTEXT_SYMBOL = Symbol('WS_CONTEXT')
 
 const isPromise = (v) => v != null && (typeof v === 'object' || typeof v === 'function') && typeof v.then === 'function'
@@ -27,6 +30,7 @@ const isPromise = (v) => v != null && (typeof v === 'object' || typeof v === 'fu
  * @property {'get'|'post'|'put'|'delete'|'del'|'patch'|'options'|'head'|'any'} method
  * @property {string} path - '/users/:id','/*'
  * @property {(ctx: HttpContext) => any|Promise<any>} handler
+ * @property {((ctx: HttpContext) => any|Promise<any>)|((ctx: HttpContext) => any|Promise<any>)[]} [preHandler]
  */
 
 export default class Server {
@@ -138,7 +142,7 @@ export default class Server {
 
       if (this.useNativeRouting) {
         for (const route of this.routes) {
-          const { method, path, handler } = route
+          const { method, path, handler, preHandler } = route
           const methodName = method === 'delete' ? 'del' : method
 
           if (typeof this.app[methodName] !== 'function') {
@@ -149,7 +153,9 @@ export default class Server {
             throw new TypeError(`Invalid Path in route, method: ${method}, path: ${path}`)
           }
 
-          this.app[methodName](path, (res, req) => this.handleWithContext(res, req, handler))
+          const routeHandler = this.#composeRouteHandler(handler, preHandler)
+
+          this.app[methodName](path, (res, req) => this.handleWithContext(res, req, routeHandler))
         }
       } else {
         this.app.any('/*', (res, req) => this.handleWithContext(res, req, this.router))
@@ -186,6 +192,42 @@ export default class Server {
     return this.#listenPromise
   }
 
+  /**
+   * @param {(ctx: HttpContext) => any|Promise<any>} handler
+   * @param {((ctx: HttpContext) => any|Promise<any>)|((ctx: HttpContext) => any|Promise<any>)[]} [preHandler]
+   * @returns {(ctx: HttpContext) => any|Promise<any>}
+   */
+  #composeRouteHandler(handler, preHandler) {
+    if (preHandler == null) {
+      return handler
+    }
+
+    const chain = Array.isArray(preHandler) ? preHandler : [preHandler]
+
+    for (let i = 0; i < chain.length; i++) {
+      if (typeof chain[i] !== 'function') {
+        throw new TypeError('Route preHandler must be a function or an array of functions')
+      }
+    }
+
+    if (chain.length === 0) {
+      return handler
+    }
+
+    return async (ctx) => {
+      for (let i = 0; i < chain.length; i++) {
+        await chain[i](ctx)
+
+        if (ctx.replied || ctx.aborted) {
+          ctx.finalize()
+          return
+        }
+      }
+
+      return handler(ctx)
+    }
+  }
+
   /**
    * @param {Function} fn
    * @param  {...any} args

package/src/res-streamer.js

@@ -82,7 +82,7 @@ export default class ResStreamer {
 
   /**
    * @param {number|string} status
-   * @param {Record<string,string>|null} headers
+   * @param {Record<string, string | string[]>|null} headers
    * @returns {ResStreamer}
    */
   begin(status = 200, headers = null) {

package/src/serve-static.js

@@ -0,0 +1,143 @@
+import { readFile, stat } from 'node:fs/promises'
+import { resolve, join, extname, sep } from 'node:path'
+
+const MIME_TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; 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',
+  '.map': 'application/json; charset=utf-8',
+  '.wasm': 'application/wasm',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf'
+}
+
+const OCTET_STREAM = 'application/octet-stream'
+
+/**
+ * @param {string} filePath
+ * @returns {string}
+ */
+function mimeFor(filePath) {
+  return MIME_TYPES[extname(filePath).toLowerCase()] || OCTET_STREAM
+}
+
+/**
+ * @typedef {object} ServeStaticOptions
+ * @property {boolean} [spa]
+ * @property {string} [index]
+ * @property {boolean} [cache]
+ * @property {number} [cacheLimit]
+ * @property {number} [maxAge]
+ */
+
+/**
+ * @param {string} root
+ * @param {ServeStaticOptions} [options]
+ * @returns {(ctx: import('./http-context.js').default) => Promise<void>}
+ */
+export default function serveStatic(root, options = {}) {
+  const rootDir = resolve(root)
+  const indexFile = options.index ?? 'index.html'
+  const spa = options.spa === true
+  const useCache = options.cache !== false
+  const cacheLimit = options.cacheLimit ?? 128
+  const maxAge = options.maxAge
+  const cacheControl = maxAge != null ? `public, max-age=${maxAge}` : null
+  const cache = useCache ? new Map() : null
+
+  /**
+   * @param {string} absPath
+   * @returns {Promise<{ buf: Buffer, type: string } | null>}
+   */
+  async function load(absPath) {
+    if (cache && cache.has(absPath)) {
+      return cache.get(absPath)
+    }
+
+    let buf
+
+    try {
+      const info = await stat(absPath)
+
+      if (!info.isFile()) {
+        return null
+      }
+
+      buf = await readFile(absPath)
+    } catch {
+      return null
+    }
+
+    const entry = { buf, type: mimeFor(absPath) }
+
+    if (cache) {
+      if (cache.size >= cacheLimit) {
+        cache.delete(cache.keys().next().value)
+      }
+
+      cache.set(absPath, entry)
+    }
+
+    return entry
+  }
+
+  return async function handleStatic(ctx) {
+    const method = ctx.method()
+
+    if (method !== 'get' && method !== 'head') {
+      ctx.status(405).send('Method Not Allowed')
+      return
+    }
+
+    let pathname
+
+    try {
+      pathname = decodeURIComponent(ctx.url())
+    } catch {
+      ctx.status(400).send('Bad Request')
+      return
+    }
+
+    if (pathname.endsWith('/')) {
+      pathname += indexFile
+    }
+
+    const rel = pathname.replace(/^\/+/, '')
+    const absPath = resolve(rootDir, rel)
+
+    if (absPath !== rootDir && !absPath.startsWith(rootDir + sep)) {
+      ctx.status(403).send('Forbidden')
+      return
+    }
+
+    let entry = await load(absPath)
+
+    if (!entry && spa) {
+      entry = await load(join(rootDir, indexFile))
+    }
+
+    if (!entry) {
+      ctx.status(404).send('Not Found')
+      return
+    }
+
+    if (cacheControl) {
+      ctx.setHeader('cache-control', cacheControl)
+    }
+
+    // uWS strips the body for HEAD requests at the native level and keeps the
+    // correct Content-Length, so GET and HEAD share the same reply path.
+    ctx.reply(200, { 'content-type': entry.type }, entry.buf)
+  }
+}