Node.js Operations

Request parsing and cache failures

For custom Node HTTP servers or middleware registered before a framework parser, call aiwaf.bodyParser() before AIWAF and before forwarding requests. It parses JSON and URL-encoded bodies, retains original forwarding bytes, and rejects oversized bodies (default 64 KiB). Fastify/Hapi integrations must enforce AIWAF after body parsing and before their proxy handler.

Redis rate-cache failures return generic HTTP 503. AIWAF_RATE_CACHE_FAILURE_MODE defaults to 'closed'; explicitly choosing 'open' allows requests during cache failures. The new filesystem CSV transactions and retained training handles are Python/PyO3 capabilities; installing WASM does not migrate Node middleware/storage to that implementation.

Native deployment and benchmarking

Native mode: Node source candidate aiwaf 1.1.5 declares aiwaf-wasm ^0.2.5. Explicit native registration validates NativeRequestPipeline at startup; missing or incompatible support is an error. There is no JavaScript policy fallback for this engine. Installing the dependency does not switch an existing legacy middleware chain.

Build/install the matching WASM companion first, await initialization, verify diagnostics().native and diagnostics().model, and test normal routes, unknown PHP paths and nested SQL bodies. Use setModel(model) to replace the fitted Rust snapshot or restart. The legacy trainer/log stores are separate from the native event files; do not assume an automatic import.

Run npm run test:native from js/ in the source checkout. node scripts/benchmark_js_pipeline.js compares full HTTP requests against bare Express, with AI off/on and actual inference counters. Server samples include synchronous finalization/logging, and overhead subtracts the framework-only baseline. Legacy SQLite/JSONL and native Rust/CSV have different persistence semantics, so comparisons are integration results rather than pure language speedups.

Stop traffic and wait for in-flight responses before close(). Model/rate/honeypot/history state is local; persisted blocks/keywords only reload on reconstruction. Publication must make the compatible WASM API available before users enable native mode.

Read the native lifecycle, configuration, deployment and measurements, and migration.

Measured Node request overhead

Windows x64, Node v22.18.0, Express 4.22.1, built WASM 0.2.2. Three alternating runs of 300 requests per mode, one keep-alive client. 80% GET / 20% JSON POST with 30 fields; 1,000 blocklist entries; all eight stages selected; memory rate/form state. Native AI uses a seeded 100-tree forest fitted to 200 rows, with one inference per measured/warm-up request verified by counters.

Server samples include synchronous finalization and immediate logging. Overhead subtracts the matched bare Express baseline; figures are medians of per-run means. Legacy uses SQLite policy lookups and one immediate JSONL append; native uses Rust state and one immediate CSV append. These stores/policies have different persistence semantics, so this is an integration comparison, not a pure Rust-versus-JavaScript equivalence test. GeoIP is an unknown-country fixture, not a real database lookup. Synthetic local latency does not establish production throughput or latency.

Native execution and actual inference counters were verified; all 3,600 measured requests returned 200. Protected SQL/PHP probes returned 403. Reproduce from the source checkout with scripts/benchmark_js_pipeline.js.

Dependency security and reproducible checks

The source lockfile uses Jest 30.5.2, Fastify 5.12.7, and patched NestJS 11 dependencies (the validated install resolved 11.2.7). The direct glob dependency is 13.0.6. Targeted overrides update qs and the NYC loader's YAML dependency; old global parser overrides have been removed. Framework packages in devDependencies support adapter testing; they do not select the framework for an installed application.

cd js
npm ci
npm audit
npm run test:coverage
npm run test:wasm
npm run test:native

The repository's Jest tests use generated CommonJS WASM bindings through AIWAF_NATIVE_TEST_MODULE. Release CI builds that fixture from rust/crates/aiwaf_wasm and runs real installed-WASM checks separately. Jest also transforms the ESM cookie dependency used by Fastify's injection client so the suite works on Node 22.

Earlier dependency validation on 13 October 2026 passed 227 tests across 63 suites, with coverage thresholds met, plus real WASM and native framework transport checks. npm ci and the full npm audit reported zero known vulnerabilities for that lockfile. The release workflow audits production and development dependencies. Rerun the audit after dependency changes; this result describes the tested tree and advisory database at that time.

Upstream deprecation warnings remain for SQLite's prebuild-install and coverage tooling's glob 10 dependency. Deprecation notices and blocked optional install scripts are separate from audit findings. The repository permits SQLite's install script; the tested installation did not require enabling every optional postinstall script.

The latency figures above were measured before this dependency update. They have not been remeasured with the patched tree.

October 2026 release upgrade

The prepared source versions are Python 1.1.6, Rust/Python 0.2.5, Node.js 1.1.4, WASM 0.2.4, and Java 1.3.4. These are source targets; verify registry availability before installing. Python requires aiwaf-rust>=0.2.5, including the TrainingEvidence API. Node offline training requires the matching WASM receipt API.

1. Back up policies, logs, models, and training evidence. Use the same absolute data and evidence directories for application workers and CLI trainers.
2. Install the matching native companion before upgrading its host package: Rust before Python, WASM before Node. Preserve training_evidence.json and node_training_evidence.json across expiry, unblocking, restarts, and log rotation.
3. Stop older file writers and restart all workers on the new code. Mixing old unlocked writers with new writers can still lose updates.
4. In staging, train twice on identical logs, then verify handled evidence does not recreate a removed or expired block. Add genuinely fresh requests and confirm they must independently satisfy the enforcement threshold.
5. Verify that listing and expiry checks preserve concurrently refreshed blocks and unrelated IPs. Check the raw expiry and backend location if entries disappear unexpectedly.

Java CSV and file storage

Java 1.3.4 reloads current storage under a shared JVM and OS sidecar lock for each operation. Reads filter expiry without rewriting disk; mutations preserve other instances' updates and report persistence failures. This adds file I/O. Java model training still does not add blocklist entries. Rate buckets and other per-engine memory state retain their existing isolation.

Lock recovery

Python training uses an OS file lock; Java CSV/file OS locks also release on process exit. Keep their stable sidecar lock files in place while workers run. Node uses lock directories for training and legacy CSV mutations; a crash can leave them behind. Confirm the owning process has stopped before removing a Node lock directory. Do not delete training receipts to clear a lock: doing so loses handled-evidence history.

Release checks

Local validation passed 247 Node tests across 67 suites with the coverage gate, 215 Java tests with 3 skips, and 38 Rust/WASM native tests. After the native dependency bump, 11 affected Python packaging tests passed through the appropriate Django and pytest runners. These checks do not replace full release CI, dependency audits, signing, or operating-system wheel builds. Build Linux/macOS Rust wheels using the release matrix; the local bundle contains a Windows x86-64 wheel.

For release maintainers: publish the WASM companion, refresh the Node lockfile from the registry to record its actual integrity, then run npm ci and the native integration checks. Do not substitute an older native dependency to satisfy a stale packaging test. See the changelog.