ECO-355: DB-backed framework tests — embedded Postgres provisioning + js-hedgedoc; disable native addon loading

[Arshia001]

Kicks off the ECO-355 DB phase (SQLite was resolved as no-go; all former Tier B apps except Actual Budget can run against MySQL/Postgres instead).

Harness: ephemeral embedded databases

Backend apps declare their DB in a top-level database block in routes.json; the harness starts an ephemeral PostgreSQL before the app server (real embedded-postgres binaries as plain child processes — no Docker, since framework tests also run on macOS CI runners and locally via make), injects the declared env vars ({dbUrl}/{dbHost}/{dbPort}/…, plus {port} expanded at spawn time), and tears everything down per stage. Binaries install on demand into .framework-test/db-tools using the shared pnpm store. The WASIX runner's env allowlist is extended via FRAMEWORK_TEST_EXTRA_ENV; the guest reaches the host DB over loopback with --net.

Runtime: native addon loading disabled (WASIX parity)

Native and WASIX must expose the same functionality, and WASIX has no dynamic linking — process.dlopen now throws a catchable ERR_DLOPEN_FAILED before ever calling dlopen(). Failing early matters: legacy NAPI_MODULE-style prebuilds (bufferutil, utf-8-validate) call the unexported napi_module_register from a static constructor during dlopen, which previously killed the process with an uncatchable dynamic-linker error on native. Now optional accelerators fall back to pure JS exactly as under WASIX, and the unreachable dlopen machinery is removed (−123 lines). N-API is unaffected: native napi tests are statically linked; safe mode / WASIX use the wasmer napi extension.

First app: js-hedgedoc

HedgeDoc 1.11.0 + PostgreSQL via wasmerio/examples#2 (submodule bump — merge that PR first). Auto-migrations on boot, unauthenticated assert routes. Green on Node → QuickJS native → QuickJS WASIX; js-totaljs-cms re-validated on the modified harness.

Next up per the triage in plans/eco-355-selfhosted-app-framework-tests.md: RSSMonster (needs a MySQL provider in the DB module), Uptime Kuma, Firekylin. Blocked regardless of DB: Umami (Prisma 7 WASM query compiler), Ghost (sharp), Directus (sharp + isolated-vm + argon2).

🤖 Generated with Claude Code

[Arshia001]

Added the second DB-backed app, js-rssmonster (MySQL), with three harness extensions:

• MySQL provider (kind: "mysql") via mysql-memory-server — uses a matching system mysqld when available (Linux CI images ship MySQL 8), otherwise downloads official binaries once and caches them (the macOS case); harness user created with a password via init SQL.
• database.setup — routes.json commands (sequelize migrations/seeds) run after the DB is up, before the server starts, always on host Node: package .bin launchers prefer the sibling node_modules/.bin/node (the injected Edge runner on Edge stages), so the harness swaps that shim to host Node for the duration.
• Tracked-artifact preservation — the node stage no longer deletes git-tracked GENERATED_FRAMEWORK_PATHS entries (vendored prebuilt dist/public/build); this bug had silently stripped js-hedgedoc's assets from the examples PR (restored there).

js-rssmonster is green on Node/QuickJS-native/QuickJS-WASIX locally.

🤖 Generated with Claude Code

[Arshia001]

Added the third DB-backed app, js-uptime-kuma (MySQL, Kuma's mariadb mode), which surfaced two more parity/harness fixes:

• process.platform now reports linux under WASIX (was wasi). Same parity rationale as the addon ban: packages switching on platform behaved differently per target — playwright-core throws at require time on unknown platforms, breaking Kuma's boot only on WASIX. WASIX emulates Linux syscalls. One node test newly runs because of its common.isLinux guard and is skipped (test-pipe-abstract-socket-http — abstract sockets are a kernel feature WASIX lacks). Full wasix quickjs suite locally: 1671 passed, 0 failed.
• Readiness now waits for the first route's expected status instead of any HTTP response: Kuma serves a temporary migration page that 404s API routes while its boot-time knex migrations run, so the harness validated too early. Apps with long migrations can set a top-level serverReadyTimeoutMs in routes.json. Both documented in plans/framework-integration-tests.md.

js-uptime-kuma is green on Node/QuickJS-native/QuickJS-WASIX locally (companion commit on wasmerio/examples#2).

🤖 Generated with Claude Code

[Arshia001]

Added the fourth and final planned DB app, js-firekylin (MySQL, ThinkJS 3), with two findings:

• MySQL provider now uses mysql_native_password for the harness user and pins MySQL 8.0.x: apps on the legacy mysql 2.x driver (Firekylin's think-mysql chain) can't do caching_sha2_password, and 8.4+ disables the native plugin by default. mysql2-based apps unaffected; all four DB apps re-validated on native + WASIX.
• WASIX capability gap — cluster IPC: ThinkJS always serves through cluster.fork(); under WASIX the forked worker's IPC channel is dead (process.send → write EPIPE; extra fds aren't passed through wasmer's process spawn), so the worker can never receive its listen handle and the master respawns it forever. js-firekylin is therefore skipped on the WASIX framework target (Makefile comment + ECO-355 plan note). Affects any cluster-based app — fixing it means fd passing (or a loopback IPC fallback) at the wasmer/edgejs process-spawn layer, which is beyond this PR.

That completes ECO-355 Phase DB: HedgeDoc (Postgres), RSSMonster (MySQL), Uptime Kuma (MySQL/mariadb-mode), Firekylin (MySQL) — all green on Node + QuickJS native, first three green on WASIX.

🤖 Generated with Claude Code

[Arshia001]

Root-caused the WASIX cluster IPC failure with Arshia — it was not fd passing at all. Full chain:

1. cluster.fork's channel is a plain socketpair; the fd survives proc_spawn fine (raw writes work, dup2-to-fd-10 relocation works).
2. The killer was wasix-libuv stubbing IPC stream reads to ENOSYS under __wasi__ (uv__stream_io): on first EPOLLIN the 'read' failed instantly, libuv closed the fd, and every later process.send got EPIPE — with zero error output. Fixed in wasix: read IPC streams with plain read() instead of failing ENOSYS wasix-org/libuv#8 (plain read() — no descriptor can accompany the data anyway since send_handle writes are refused with ENOSYS) and bumped here.
3. Separately, sock_pair inodes in wasmer get a default filestat (filetype=Unknown, st_mode=0), which breaks uv_guess_handle/net.Socket({fd}). Fixed in wasmer (sock_pair inodes now report SocketStream); verified fstat shows S_IFSOCK in spawned children.

After the libuv fix: fork/process.send message channels are fully functional under WASIX (ping/pong verified both directions), cluster workers come online and negotiate listen. The remaining gap for cluster serving is SCM_RIGHTS-style connection passing — a reuseport-style scheduling strategy is the tracked follow-up, so js-firekylin stays skipped on WASIX (rationale updated in the Makefile comment).

Regressions: js-hedgedoc/js-uptime-kuma WASIX green with the new libuv; wasix node suite shows only load-induced timing flakes locally (machine was at load 20 from an unrelated workload — failing sets don't reproduce individually and differ run to run). CI will confirm on quiet runners.

🤖 Generated with Claude Code

[Arshia001]

SO_REUSEPORT works properly under WASIX — investigated end to end with Arshia:

• The only gate was guest-side: libuv's uv__sock_reuseport whitelists Linux/DragonFly/AIX/Solaris and failed UV_ENOTSUP under __wasi__ before the runtime was consulted. Everything below works: wasix-libc → sock_set_opt_flag(SO_REUSEPORT) → wasmer applies it to the host socket before bind (virtual-net host backend).
• Opened the gate in wasix: enable SO_REUSEPORT in uv__sock_reuseport wasix-org/libuv#9 (stacked on Roadmap #8) and bumped here.

Verified under WASIX on wasmer 7.2.0-rc.1:

• two reusePort listeners bind the same port (same process and across forked guest processes)
• a listener without the flag still fails EADDRINUSE
• 40 connections to two forked workers balanced 18/22 — real kernel-level distribution
• Node's test-dgram-reuseport.js now passes (previously skipped on ENOTSUP)

Combined with the fork-IPC fix, all the primitives for a reuseport-based cluster scheduling strategy on WASIX are now in place (workers bind the shared port themselves instead of receiving handles via SCM_RIGHTS) — that scheduler change in edgejs's cluster internals is the remaining piece to unskip js-firekylin on WASIX.

🤖 Generated with Claude Code

[Arshia001]

js-firekylin is now green on the full matrix — WASIX included. The magic, in order:

1. fork IPC channel fixed (wasix: read IPC streams with plain read() instead of failing ENOSYS wasix-org/libuv#8) → cluster workers handshake and negotiate listens
2. SO_REUSEPORT enabled (wasix: enable SO_REUSEPORT in uv__sock_reuseport wasix-org/libuv#9) → verified kernel balancing across forked guest processes
3. New: a WASIX cluster scheduling strategy — since no listen handle can cross the IPC channel, queryServer for TCP listens now answers with a ReusePortHandle (primary binds nothing, replies reusePort: true) and the worker creates its own listen handle with UV_TCP_REUSEPORT. All cluster bookkeeping (listening events, worker registry, close tracking) works unchanged; UDP/fd/pipe listens and all native targets keep their existing paths. Detection uses a new isWasix constant on the process_methods binding (process.platform says linux under WASIX by design).

Verified: two cluster workers serving HTTP on one port under WASIX with requests balanced 6/6, and js-firekylin (ThinkJS, cluster-served) passing the framework test — removed from the WASIX skip list. Regressions green: firekylin native (round-robin untouched), hedgedoc + rssmonster WASIX, svelte native.

All four ECO-355 DB apps now pass Node + QuickJS native + QuickJS WASIX.

🤖 Generated with Claude Code

[syrusakbary]

None of the changes in the lib folder can be merged. All modifications must be done, if necessary in the native side

[syrusakbary]

This is wrong. This changes to disable dynamic linking in Edge.js are wrong and can't be merged. We can disable at most them on WASIX, but not natively

[Arshia001]

The idea is to keep native and WASIX behaving exactly the same. Since we don't enable DL for WASIX yet, this keeps them in sync. I can undo the change (but IMO it makes sense).

[syrusakbary]

Hard disagree on that, we should keep compatibility with native modules for now on the native Edge.js (but trigger an error if compiled target is WASIX for now, saying that we will support them soon)

[Arshia001]

Relocated the cluster reuseport strategy out of lib/ into native (src/edge_cluster_wasix.cc) per the pristine-lib policy — lib/ is now byte-identical to main again across the whole PR.

Implementation: EdgeRuntime installs an embedded script in WASIX cluster workers (before the main builtin runs, while NODE_UNIQUE_ID is still in the env) that replaces the worker-side cluster._getServer — an exported, replaceable property. TCP port listens bind their own UV_TCP_REUSEPORT handle and report the listening act for primary bookkeeping; the primary side needs no changes at all. UDP/fd/pipe listens and all native targets keep the upstream paths (compile-time gate). The child-only shape has one inherited limitation: _getServerData/_setServerData isn't round-tripped (TLS ticket keys stay per-worker).

Re-verified: cluster workers balance raw TCP 13/11 under WASIX (an earlier 12/0 read was HTTP agent keep-alive correctly pinning one reused connection), js-firekylin green on WASIX + native, uptime-kuma WASIX and svelte native regressions green.

🤖 Generated with Claude Code

[Arshia001]

@syrusakbary in the spirit of keeping node's JS sources untouched, the approach we came up with involves injecting JS code from the native side. I'm quite certain this can't be done with zero JS code. Is this good enough?

[Arshia001]

Ran the previously-skipped cluster/fork tests locally against the new stack — 11 of 17 pass and are unskipped, including TCP cluster serving (test-http-server-drop-connections-in-cluster, test-tls-ticket-cluster) and the child_process fork/messaging harnesses (test-diagnostics-channel-process, domain + http fork tests).

Of the 6 that still fail: 2 were misfiled (moved to the unix-socket and crypto groups — their failures are unrelated to cluster/fork), and 4 are UDP cluster listens, which still go through shared-handle passing (the reuseport strategy covers TCP only). One fun find: the known_issues negative test for cluster UDP port-0 sharing started "unexpectedly passing" because its error-swallowing path engages now that fork IPC actually delivers messages — skipped with rationale.

Full wasix quickjs suite locally: 1681 passed / 0 failed (up from the 1671 baseline).

🤖 Generated with Claude Code

[Arshia001]

Extended the reuseport strategy to UDP — the cluster/fork skip list is now empty.

The worker-side override now handles udp4/udp6 port listens via dgram._createSocketHandle + UV_UDP_REUSEPORT; the kernel distributes datagrams between workers by source hash (flows pin to a worker, vs shared-socket delivery upstream — verified 11/5 across two workers). Two contract details the upstream tests enforced along the way: _getServer callbacks must stay async (process.nextTick now, matching the upstream IPC round trip — test-dgram-cluster-close-during-bind depends on that window), and dgram passes raw bind() args through, so options.port can be null/undefined/the bind callback function — all meaning ephemeral-port listen.

Every cluster/fork test in the wasix lanes passes — WASIX_SKIP_CLUSTER_FORK_TESTS is empty, including the known_issues negative test (back to failing-as-expected). Full wasix quickjs suite locally: 1686 passed / 0 failed. js-firekylin re-verified on WASIX + native.

🤖 Generated with Claude Code

[syrusakbary]

This is even a bigger hack and can't be merged. What native call is behaving differently and why we need to do this? That's the question that will solve things properly and not force any hacks

[Arshia001]

because on native, node.js uses unix sockets and passes FDs through them using ancillary data, none of which are supported on WASIX, so we need a different implementation if we hope to get cluster working.

[syrusakbary]

Posted on Linear as well. What we need to do is to raise an issue on usage of Cluster.fork so it fails in WASIX for now.

We should still allow it to be imported and used, except of forking:

const cluster = require('node:cluster');
const http = require('node:http');
const numCPUs = require('node:os').availableParallelism();

if (cluster.isPrimary) {
  console.log(`Primary ${process.pid} is running`);

  // Fork workers.
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork(); // <-------------------------------- THIS SHOULD FAIL
  }

  cluster.on('exit', (worker, code, signal) => {
    console.log(`worker ${worker.process.pid} died`);
  });
} else {
  // Workers can share any TCP connection
  // In this case it is an HTTP server
  http.createServer((req, res) => {
    res.writeHead(200);
    res.end('hello world\n');
  }).listen(8000);

  console.log(`Worker ${process.pid} started`);
}