castrum 0.7.0 → 0.9.1

package/package.json

@@ -1,12 +1,12 @@
 {
     "name": "castrum",
-    "version": "0.7.0",
+    "version": "0.9.1",
     "private": false,
     "description": "Enterprise-grade Bun + Rust runtime: Rust-accelerated FFI primitives, a production-grade HTTP ingress pipeline, validation, hashing, and JSON processing with benchmark-grade performance.",
     "type": "module",
-    "main": "index.ts",
-    "module": "index.ts",
-    "types": "index.ts",
+    "main": "dist/index.js",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
     "license": "MIT",
     "keywords": [
         "bun",
@@ -25,70 +25,135 @@
         "type": "git",
         "url": "git+https://github.com/Axylabs/flux-rs.git"
     },
+    "homepage": "https://github.com/Axylabs/flux-rs#readme",
+    "bugs": {
+        "url": "https://github.com/Axylabs/flux-rs/issues"
+    },
     "publishConfig": {
         "access": "public"
     },
     "exports": {
-        ".": "./index.ts"
+        ".": {
+            "types": "./dist/index.d.ts",
+            "bun": "./index.ts",
+            "node": "./dist/index.js",
+            "default": "./dist/index.js"
+        },
+        "./package.json": "./package.json"
     },
     "files": [
         "index.ts",
-        "bench.ts",
+        "dist",
         "src",
-        "rust",
-        "Cargo.toml",
+        "docs",
         "README.md",
-        "*.node"
+        "*.node",
+        "!src/bench",
+        "!src/baseline",
+        "!src/data"
     ],
     "scripts": {
         "build": "napi build --release --platform",
+        "build:perf": "bash scripts/build-perf.sh",
+        "build:v3": "bash scripts/build-v3.sh",
+        "build:all": "bun run build && bun run build:v3",
+        "build:js": "bun run build:js:bundle && bun run build:js:types",
+        "build:js:bundle": "bun build ./index.ts --target=node --format=esm --outdir=dist",
+        "build:js:types": "dts-bundle-generator -o dist/index.d.ts index.ts",
         "bench": "bun run build && bun bench.ts",
         "check": "bun bench.ts",
         "test": "bun test",
+        "test:all": "bun test && bun run typecheck && bun run typecheck:test && bun run lint:ci && bun run check:clean && cargo test --lib",
+        "test:coverage": "node scripts/check-coverage.mjs",
+        "setup": "bun install && bun run build",
+        "test:node": "node --test test/integration/node-smoke.test.mjs test/integration/node-enterprise.test.mjs",
+        "verify:install": "node scripts/verify-install.mjs",
         "build:debug": "napi build --platform",
-        "artifacts": "napi artifacts",
+        "lint": "bunx biome check .",
+        "lint:fix": "bunx biome check --write .",
+        "lint:ci": "bunx biome check . --formatter-enabled=false --assist-enabled=false --error-on-warnings",
+        "format": "bunx biome format --write .",
+        "typecheck": "bunx tsc --noEmit",
+        "typecheck:test": "bunx tsc --noEmit -p tsconfig.test.json",
+        "test:rust": "cargo test",
+        "deny": "cargo deny check",
+        "check:version": "bun scripts/check-version.mjs",
+        "check:jsdoc": "bun scripts/check-jsdoc.ts",
+        "check:selection": "bun scripts/select-native.ts --check",
+        "check:clean": "bun scripts/check-clean.ts",
+        "audit": "bun audit",
         "publish:manual": "node scripts/publish-manual.mjs",
         "publish:manual:dry": "node scripts/publish-manual.mjs --dry-run",
-        "prepublishOnly": "node scripts/prepublish.mjs",
-        "bench:http": "bun run bench/run-bench.ts",
-        "bench:http:smoke": "bun run bench/run-bench.ts smoke",
-        "bench:http:stress": "bun run bench/run-bench.ts stress",
-        "bench:http:heavy": "bun run bench/run-bench.ts heavy-json",
-        "bench:http:crud": "bun run bench/run-bench.ts crud",
-        "bench:http:spike": "bun run bench/run-bench.ts spike",
-        "bench:http:soak": "bun run bench/run-bench.ts soak",
-        "bench:http:storm": "bun run bench/run-bench.ts storm",
-        "bench:http:boundary": "bun run bench/run-bench.ts boundary",
-        "bench:http:elysia": "bun run bench/run-bench.ts '' elysia",
-        "bench:http:ingress": "bun run bench/run-bench.ts '' ingress",
-        "bench:http:bun-only": "bun run bench/run-bench.ts '' bun",
-        "bench:http:all-heavy": "bun run bench/run-bench.ts 1"
+        "prepublishOnly": "bun run build:js && node scripts/prepublish.mjs",
+        "bench:http": "BUN_CONFIG_MAX_HTTP_REQUESTS=65536 bun run bench/run-bench.ts",
+        "bench:http:smoke": "BUN_CONFIG_MAX_HTTP_REQUESTS=65536 bun run bench/run-bench.ts smoke",
+        "bench:http:stress": "BUN_CONFIG_MAX_HTTP_REQUESTS=65536 bun run bench/run-bench.ts stress",
+        "bench:http:heavy": "BUN_CONFIG_MAX_HTTP_REQUESTS=65536 bun run bench/run-bench.ts heavy-json",
+        "bench:http:crud": "BUN_CONFIG_MAX_HTTP_REQUESTS=65536 bun run bench/run-bench.ts crud",
+        "bench:http:spike": "BUN_CONFIG_MAX_HTTP_REQUESTS=65536 bun run bench/run-bench.ts spike",
+        "bench:http:soak": "BUN_CONFIG_MAX_HTTP_REQUESTS=65536 bun run bench/run-bench.ts soak",
+        "bench:http:storm": "BUN_CONFIG_MAX_HTTP_REQUESTS=65536 bun run bench/run-bench.ts storm",
+        "bench:http:boundary": "BUN_CONFIG_MAX_HTTP_REQUESTS=65536 bun run bench/run-bench.ts boundary",
+        "bench:http:elysia": "BUN_CONFIG_MAX_HTTP_REQUESTS=65536 bun run bench/run-bench.ts '' elysia",
+        "bench:http:ingress": "BUN_CONFIG_MAX_HTTP_REQUESTS=65536 bun run bench/run-bench.ts '' ingress",
+        "bench:http:bun-only": "BUN_CONFIG_MAX_HTTP_REQUESTS=65536 bun run bench/run-bench.ts '' bun",
+        "bench:http:all-heavy": "BUN_CONFIG_MAX_HTTP_REQUESTS=65536 bun run bench/run-bench.ts 1",
+        "bench:http:ac": "bun bench/autocannon-stress.mjs",
+        "bench:http:stress:ac": "SCENARIO=03-stress bun bench/autocannon-stress.mjs",
+        "bench:startup": "bun run bench/startup.ts",
+        "bench:load": "bun run bench/load-phase.ts",
+        "bench:ffi": "bun run bench/ffi-all.ts",
+        "bench:ffi:load": "bun run bench/ffi-load.ts",
+        "bench:ffi:public": "bun run bench/ffi-public.ts",
+        "bench:ffi:workers": "bun run bench/ffi-workers.ts",
+        "bench:margin": "bun run bench/ffi-margin.ts",
+        "bench:router": "bun run bench/router-cost.ts",
+        "bench:ingress-cost": "bun run bench/ingress-cost.ts",
+        "bench:ingress-cost:post": "bun run bench/ingress-cost-post.ts",
+        "verify:native:batch": "bun run scripts/verify-native-batch.ts"
     },
-    "dependencies": {
-        "crc-32": "^1.2.2",
-        "fast-json-patch": "^3.1.1",
-        "mime-types": "^3.0.2",
-        "validator": "^13.15.35"
+    "dependencies": {},
+    "peerDependencies": {
+        "@types/node": "^26.1.2"
+    },
+    "peerDependenciesMeta": {
+        "@types/node": {
+            "optional": true
+        }
     },
     "devDependencies": {
         "@elysia/cors": "^1.4.2",
-        "@napi-rs/cli": "^3.7.4",
+        "@napi-rs/cli": "^3.8.6",
         "@types/bun": "^1.3.14",
         "@types/mime-types": "^3.0.1",
+        "autocannon": "^8.0.0",
         "@types/validator": "^13.15.10",
-        "elysia": "^1.4.0"
+        "ajv": "^8.20.0",
+        "crc-32": "^1.2.2",
+        "dts-bundle-generator": "^9.5.1",
+        "elysia": "^1.4.29",
+        "fast-json-patch": "^3.1.1",
+        "mime-types": "^3.0.2",
+        "typescript": "5.9.3",
+        "validator": "^13.15.35"
+    },
+    "overrides": {
+        "typescript": "5.9.3"
     },
     "engines": {
-        "bun": ">=1.1.0"
+        "bun": ">=1.1.0",
+        "node": ">=20.3"
     },
     "napi": {
         "binaryName": "castrum",
         "targets": [
             "aarch64-apple-darwin",
             "aarch64-unknown-linux-gnu",
+            "aarch64-unknown-linux-musl",
             "x86_64-apple-darwin",
             "x86_64-pc-windows-msvc",
-            "x86_64-unknown-linux-gnu"
+            "x86_64-unknown-linux-gnu",
+            "x86_64-unknown-linux-musl"
         ]
     }
 }

package/src/ingress/body.ts

@@ -0,0 +1,289 @@
+// src/ingress/body.ts — Streaming request-body reading for the async ingress
+// API.
+
+import { isBun } from '../shared/runtime'
+
+const EMPTY_BODY = new Uint8Array(0)
+
+/**
+ * Read the request body as bytes. Bun's `req.bytes()` returns a `Uint8Array`
+ * directly (no `ArrayBuffer` → view wrapper and no copy) — feature-detected so
+ * Node (which lacks `Response.bytes()` on some versions) falls back to
+ * `arrayBuffer()` + a zero-copy view. This is the hot-path body read for every
+ * write route.
+ */
+async function readBodyBytes(req: Request): Promise<Uint8Array> {
+  const bytes = (req as { bytes?: () => Promise<Uint8Array> }).bytes
+  if (typeof bytes === 'function') {
+    return bytes.call(req)
+  }
+  return new Uint8Array(await req.arrayBuffer())
+}
+
+/**
+ * Bun-only synchronous peek of an already-buffered body.
+ *
+ * Under Bun a body fully received during HTTP parsing resolves `req.bytes()`
+ * IMMEDIATELY — `Bun.peek` hands back the `Uint8Array` without awaiting, so a
+ * declared-Content-Length write route can read the body with no deadline race,
+ * no watchdog entry and no microtask turn (the common small-body case).
+ *
+ * Returns:
+ * - `{ bytes }` — already buffered; the caller reads it synchronously and
+ *   must NOT pay the deadline race (the body is already here).
+ * - `Promise<Uint8Array>` — the read is still pending (slow/trickling body);
+ *   the caller MUST still enforce its deadline against this promise.
+ * - `false` — no `req.bytes()` on this runtime (Node); the caller falls back
+ *   to the async `readBodyBytes` + race as before.
+ */
+function peekBufferedBody(req: Request): { bytes: Uint8Array } | Promise<Uint8Array> | false {
+  const bytes = (req as { bytes?: () => Promise<Uint8Array> }).bytes
+  if (typeof bytes !== 'function') return false
+  const pending = bytes.call(req)
+  if (!isBun()) return pending
+  const peeked = Bun.peek(pending)
+  return peeked instanceof Promise ? peeked : { bytes: peeked }
+}
+
+/** Read the request body once, enforcing the size guard when enabled. */
+export function readRequestBodyOnce(
+  req: Request,
+  maxBytes: number,
+  guard: boolean,
+  timeoutMs?: number,
+): Promise<Uint8Array> {
+  if (req.body === null) {
+    return Promise.resolve(EMPTY_BODY)
+  }
+
+  return readBodyWithLimit(req, maxBytes, guard, timeoutMs)
+}
+
+function bodyTooLargeError(): Error & { code?: string } {
+  const err = new Error('BODY_TOO_LARGE') as Error & { code?: string }
+  err.code = 'BODY_TOO_LARGE'
+  return err
+}
+
+// ── Shared body-read deadline watchdog ──────────────────────────────────────
+// One interval timer sweeps ALL in-flight body reads that carry a deadline,
+// replacing a per-request `setTimeout` + `clearTimeout` + `timer.unref` on
+// every write-route body read (that per-request timer alloc is measurable in
+// the POST micro-bench — ~800ns of the ~2.3µs body read). Abort semantics are
+// unchanged: a read that outlives its deadline rejects with REQUEST_TIMEOUT.
+// Entries are removed on completion or when the deadline fires; the interval
+// only runs while at least one read is pending.
+const bodyWatchdog = (() => {
+  const inflight = new Set<WatchdogEntry>()
+  let timer: ReturnType<typeof setInterval> | null = null
+  const SWEEP_MS = 250
+
+  function sweep() {
+    const now = Date.now()
+    for (const entry of inflight) {
+      if (entry.settled) {
+        inflight.delete(entry)
+        continue
+      }
+      if (now >= entry.deadlineWall) {
+        entry.settled = true
+        inflight.delete(entry)
+        entry.reject(timeoutError())
+      }
+    }
+    if (inflight.size === 0 && timer !== null) {
+      clearInterval(timer)
+      timer = null
+    }
+  }
+
+  function track(entry: WatchdogEntry) {
+    inflight.add(entry)
+    if (timer === null) {
+      timer = setInterval(sweep, SWEEP_MS)
+    }
+  }
+
+  function untrack(entry: WatchdogEntry) {
+    entry.settled = true
+    inflight.delete(entry)
+    if (inflight.size === 0 && timer !== null) {
+      clearInterval(timer)
+      timer = null
+    }
+  }
+
+  return { track, untrack }
+})()
+
+interface WatchdogEntry {
+  deadlineWall: number
+  settled: boolean
+  reject: (err: Error) => void
+}
+
+/** Create a deadline tracked by the shared watchdog (no per-read setTimeout). */
+function createDeadline(deadlineMs: number): { promise: Promise<never>; cancel: () => void } {
+  const entry: WatchdogEntry = {
+    deadlineWall: Date.now() + deadlineMs,
+    settled: false,
+    reject: () => {},
+  }
+  const promise = new Promise<never>((_resolve, reject) => {
+    entry.reject = reject
+  })
+  bodyWatchdog.track(entry)
+  return { promise, cancel: () => bodyWatchdog.untrack(entry) }
+}
+
+/**
+ * Stream-read the request body, enforcing the size guard when enabled and an
+ * optional overall deadline.
+ *
+ * Errors carry `err.code`:
+ * - `BODY_TOO_LARGE` when `guard` is on and the body exceeds `maxBytes`
+ *   (thrown as soon as the limit is crossed — the body is never fully
+ *   buffered first, which is the slowloris/large-body protection).
+ * - `REQUEST_TIMEOUT` when `timeoutMs` elapses before the body completes.
+ */
+export async function readBodyWithLimit(
+  req: Request,
+  maxBytes: number,
+  guard: boolean,
+  timeoutMs?: number,
+): Promise<Uint8Array> {
+  const deadline = timeoutMs && timeoutMs > 0 ? timeoutMs : 0
+
+  // Fast path: a declared Content-Length lets us PROVE the body fits the
+  // guard before reading, so one native `bytes()`/`arrayBuffer()` read
+  // replaces the reader + per-chunk `Promise.race` + `concatUint8Arrays`
+  // churn (the bench POSTs are single-shot bodies — this removes ~4-6
+  // allocations per write request). The deadline (when set) is still enforced
+  // with a single race, not one per chunk. The read is bounded by the
+  // server's `maxRequestBodySize`, and the post-read length re-check catches
+  // a client that lies about Content-Length.
+  const declared = req.headers.get('content-length')
+  if (declared !== null) {
+    const declaredLen = Number(declared)
+    if (Number.isFinite(declaredLen)) {
+      if (guard && declaredLen > maxBytes) {
+        throw bodyTooLargeError()
+      }
+      // `req.body` (the stream getter) is deliberately NOT touched on this
+      // path — `req.bytes()` (Bun) / `arrayBuffer()` (Node) read the buffered
+      // body directly, avoiding a lazily-constructed stream per write request.
+      if (deadline <= 0) {
+        const bytes = await readBodyBytes(req)
+        if (guard && bytes.byteLength > maxBytes) {
+          throw bodyTooLargeError()
+        }
+        return bytes
+      }
+      // Deadline path. Under Bun, a small declared-length body is usually
+      // already buffered — `Bun.peek` returns the bytes synchronously, so we
+      // skip the deadline race + watchdog + microtask entirely for the common
+      // case. Only a genuinely pending read (slow/trickling body) pays the
+      // race; non-Bun runtimes keep the previous behavior.
+      const buffered = peekBufferedBody(req)
+      if (buffered === false) {
+        const dl = createDeadline(deadline)
+        try {
+          const bytes = await Promise.race([readBodyBytes(req), dl.promise])
+          if (guard && bytes.byteLength > maxBytes) {
+            throw bodyTooLargeError()
+          }
+          return bytes
+        } finally {
+          dl.cancel()
+        }
+      }
+      if ('bytes' in buffered) {
+        if (guard && buffered.bytes.byteLength > maxBytes) {
+          throw bodyTooLargeError()
+        }
+        return buffered.bytes
+      }
+      const dl = createDeadline(deadline)
+      try {
+        const bytes = await Promise.race([buffered, dl.promise])
+        if (guard && bytes.byteLength > maxBytes) {
+          throw bodyTooLargeError()
+        }
+        return bytes
+      } finally {
+        dl.cancel()
+      }
+    }
+  }
+
+  // No (usable) Content-Length: fall back to the streaming reader. `req.body`
+  // is only touched here — the declared-length fast path never needs it.
+  const body = req.body
+  if (!body) {
+    return EMPTY_BODY
+  }
+
+  const reader = body.getReader()
+  const chunks: Uint8Array[] = []
+  let total = 0
+  // True when the stream was fully read to `done` — on that path the reader is
+  // already closed, so the `cancel()` in `finally` is a wasted async round-trip
+  // per request. It is still required when the loop exits early (timeout/error).
+  let completed = false
+  const dl = deadline > 0 ? createDeadline(deadline) : null
+
+  try {
+    for (;;) {
+      const { done, value } =
+        dl !== null ? await Promise.race([reader.read(), dl.promise]) : await reader.read()
+
+      if (done) {
+        completed = true
+        break
+      }
+      if (!value) continue
+
+      total += value.byteLength
+
+      if (guard && total > maxBytes) {
+        throw bodyTooLargeError()
+      }
+
+      chunks.push(value)
+    }
+  } finally {
+    dl?.cancel()
+    // Release the underlying stream. Cancelling while a read() is still
+    // pending (the timeout case) can resolve that pending read() as `done`
+    // and RACE the timeout rejection — so reject first, cancel only AFTER
+    // the loop has settled. The `.catch` keeps the cancel from masking a
+    // thrown REQUEST_TIMEOUT / BODY_TOO_LARGE. On the normal `done` path the
+    // stream is already closed, so skip the cancel entirely.
+    if (!completed) {
+      await reader.cancel().catch(() => {})
+    }
+  }
+
+  return concatUint8Arrays(chunks, total)
+}
+
+function timeoutError(): Error & { code?: string } {
+  const err = new Error('REQUEST_TIMEOUT') as Error & { code?: string }
+  err.code = 'REQUEST_TIMEOUT'
+  return err
+}
+
+function concatUint8Arrays(chunks: Uint8Array[], total: number): Uint8Array {
+  if (chunks.length === 0) return EMPTY_BODY
+  if (chunks.length === 1) return chunks[0] ?? EMPTY_BODY
+
+  const out = new Uint8Array(total)
+  let offset = 0
+
+  for (const chunk of chunks) {
+    out.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+
+  return out
+}