testing/cross_backend/testing_server_core.ts

Runtime-agnostic core for spawnable cross-process test server binaries.

A test binary mounts a fuz_app-derived surface over a real HTTP socket so the cross_backend/* suites (and the cross-impl bench) can drive it the same way they drive the Rust spine. This module owns the runtime-neutral orchestration — stale-daemon check, daemon-info write, serve, post-serve WS attach, graceful drain shutdown — and delegates the runtime-boundary primitives (HTTP serve, WS upgrade construction, signals, pid, exit) to a {@link TestingServerAdapter}. The two shipped adapters are testing/cross_backend/testing_server_node.ts (@hono/node-server + @hono/node-ws) and testing/cross_backend/testing_server_deno.ts (Deno.serve + hono/deno).

The app itself — routes, RPC, DB, _testing_reset, optional WS mount — is the caller's {@link StartTestingServerOptions.build_app} seam, so this core stays domain-free. fuz_app's own testing_spine_server passes a no-domain build; consumers (zzz, fuz_forge) pass their domain build.

NEVER ships in a release. This module lives under cross_backend/ and opens with import '../assert_dev_env.ts';, which throws on production-bundle load. The runtime adapters reach for the optional @hono/node-server / @hono/node-ws peer deps; only test binaries import them.

view source

Declarations
#

7 declarations

BuiltTestingApp
#

testing/cross_backend/testing_server_core.ts view source

BuiltTestingApp import type {BuiltTestingApp} from '@fuzdev/fuz_app/testing/cross_backend/testing_server_core.js';

The assembled app a seam returns.

mount_websocket is invoked by the core after the app exists and the adapter prepared the WS upgrade closure — the closure mounts the WS endpoint(s) (e.g. via register_ws_endpoint) and wires any audit-revocation guards. Omit it for an HTTP-only binary.

app

The assembled Hono app (HTTP routes + RPC already mounted).

type Hono

close

Tear down backend(s) + DB + any rotation on graceful shutdown.

type () => Promise<void>

mount_websocket?

Mount WS endpoint(s) given the runtime-prepared upgrade closure.

type (upgrade_websocket: UpgradeWebSocket) => void

is_loopback_host
#

testing/cross_backend/testing_server_core.ts view source

(host: string): boolean import {is_loopback_host} from '@fuzdev/fuz_app/testing/cross_backend/testing_server_core.js';

Loopback bind hosts — the only ones the test binary may serve on. It ships deterministic dev secrets (fixed cookie keys + bootstrap token in default_secrets.ts), so binding any network-reachable interface would let anyone who knows those fixed keys forge cookies against it. An allowlist (not an 0.0.0.0/:: blocklist) closes the gap a concrete LAN/public interface IP — e.g. --host 192.168.1.50 — would otherwise slip through. Covers localhost, the IPv4 loopback 127.0.0.0/8, and IPv6 ::1.

host

type string

returns

boolean

PreparedWebsocket
#

testing/cross_backend/testing_server_core.ts view source

PreparedWebsocket import type {PreparedWebsocket} from '@fuzdev/fuz_app/testing/cross_backend/testing_server_core.js';

Result of an adapter's WS preparation step.

upgrade_websocket is the Hono UpgradeWebSocket closure the caller's WS mount uses to register the endpoint. attach_to_server runs after serve() returns a — Node uses it for injectWebSocket(server); Deno leaves it undefined.

upgrade_websocket

type UpgradeWebSocket

attach_to_server?

type (handle: ServeHandle) => void

ServeHandle
#

testing/cross_backend/testing_server_core.ts view source

ServeHandle import type {ServeHandle} from '@fuzdev/fuz_app/testing/cross_backend/testing_server_core.js';

Adapter-built handle to a bound HTTP server.

shutdown stops accepting new connections and drains in-flight ones. native is an adapter-specific server reference — used by Node's @hono/node-ws injectWebSocket(server) post-serve hook; Deno leaves it unset.

shutdown

type () => Promise<void>

native?

Adapter-specific server ref for post-serve hooks. Type-erased at the seam.

type unknown

start_testing_server
#

testing/cross_backend/testing_server_core.ts view source

(options: StartTestingServerOptions): Promise<void> import {start_testing_server} from '@fuzdev/fuz_app/testing/cross_backend/testing_server_core.js';

Boot a test-mode server using the supplied runtime adapter.

Mirrors a production start_server at the surface level — stale-daemon check, daemon-info write, bind, graceful drain — but the app is the caller's no-domain (or domain) and the runtime boundary is the . Refuses any non-loopback bind host (the test binary must stay on loopback — see is_loopback_host).

options

type StartTestingServerOptions

returns

Promise<void>

StartTestingServerOptions
#

testing/cross_backend/testing_server_core.ts view source

StartTestingServerOptions import type {StartTestingServerOptions} from '@fuzdev/fuz_app/testing/cross_backend/testing_server_core.js';

Options for .

adapter

Runtime-boundary adapter (Node or Deno).

type TestingServerAdapter

daemon_name

Daemon-info namespace — the cli/daemon key the daemon.json is written under (e.g. 'fuz_app_spine'). The cross-process harness reads the daemon token from the rotation file, not this; daemon.json is for stale-process detection + parity with production daemon lifecycle.

type string

host

Bind host (e.g. 'localhost').

type string

port

Bind port.

type number

app_version?

App version recorded in daemon.json.

type string

build_app

Build the app. Closes over the entry's runtime + connection-IP getter + password deps + resolved config — so this core never touches the domain. Returns the assembled app, a close teardown, and an optional mount_websocket hook.

type () => Promise<BuiltTestingApp>

log?

Optional logger; defaults to a [daemon_name]-namespaced Logger.

type LoggerType

TestingServerAdapter
#

testing/cross_backend/testing_server_core.ts view source

TestingServerAdapter import type {TestingServerAdapter} from '@fuzdev/fuz_app/testing/cross_backend/testing_server_core.js';

Runtime adapter contract for the test-binary entry. Each adapter (testing/cross_backend/testing_server_node.ts, testing/cross_backend/testing_server_deno.ts) implements this and hands the shape to .

runtime_label

Human-readable runtime label for log output (e.g. "Node", "Deno").

type string

runtime

type RuntimeDeps

get_connection_ip

Extract the raw TCP connection IP from a Hono context.

type (c: Context) => string | undefined

prepare_websocket

Build the WS upgrade closure after the caller's build_app returns the app.

type (app: Hono) => PreparedWebsocket

serve

Bind app.fetch to port on hostname; return a .

type (options: {fetch: Hono['fetch']; port: number; hostname: string}) => ServeHandle

pid

Current process pid (for daemon.json).

type number

register_shutdown_signals

Register SIGINT/SIGTERM listeners that invoke handler once each.

type (handler: () => Promise<void>) => void

exit

Forceful exit on graceful-shutdown completion or fatal error.

type (code: number) => never

Depends on
#

Imported by
#