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 shutdown — and delegates the runtime-boundary primitives (HTTP serve, WS upgrade construction, signals, pid, exit) to a TestingServerAdapter. The shipped adapters are testing/cross_backend/testing_server_node.ts (@hono/node-server + @hono/node-ws) and testing/cross_backend/testing_server_bun.ts (Bun.serve + @hono/bun).

The app itself — routes, RPC, DB, _testing_reset, WS endpoints — is the caller's StartTestingServerOptions.build_app seam, so this core stays domain-free. WebSocket endpoints mount through create_app_server's ws_endpoints: build_app asks its context to prepare the runtime's upgrade helper and passes the resulting factory as create_upgrade_websocket; the core attaches it to the server once serve returns (Node's injectWebSocket). fuz_app's own testing_spine_server passes a no-domain build; consumers (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 / @hono/bun peer deps; only test binaries import them.

view source

Declarations
#

9 declarations

BuildTestingAppContext
#

testing/cross_backend/testing_server_core.ts view source

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

What the core hands a StartTestingServerOptions.build_app seam.

prepare_websocket

Prepare the runtime adapter's WS upgrade helper and return the factory to pass to create_app_server as create_upgrade_websocket. The core runs the adapter's attach step once the server is bound, so a build that mounts ws_endpoints needs nothing else. An HTTP-only build doesn't call it. Call it at most once per build: the Node adapter attaches one upgrade listener per preparation, and two would race on the shared socket.

type (options?: PrepareWebsocketOptions | undefined): (app: Hono<BlankEnv, BlankSchema, "/">) => UpgradeWebSocket<unknown, any, WSEvents<unknown>>

options?

optional
returns (app: Hono<BlankEnv, BlankSchema, "/">) => UpgradeWebSocket<unknown, any, WSEvents<unknown>>

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 StartTestingServerOptions.build_app seam returns.

app

The assembled Hono app (HTTP routes, RPC, and WS endpoints already mounted).

type Hono<BlankEnv, BlankSchema, "/">

close

Tear down backend(s) + DB + any rotation on graceful shutdown. Called after the listener stops accepting connections and before its drain is awaited, so it must end live WebSockets (AppServer.close does).

type (): Promise<void>

returns Promise<void>

is_loopback_bind_host
#

testing/cross_backend/testing_server_core.ts view source

(host: string): boolean import {is_loopback_bind_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.

create_upgrade_websocket is the factory a build passes to create_app_server as AppServerOptions.create_upgrade_websocket. attach_to_server runs after serve() returns a ServeHandle — Node uses it for injectWebSocket(server), and it does nothing when the factory was never called (no ws_endpoints); Bun leaves it undefined.

create_upgrade_websocket

type (app: Hono<BlankEnv, BlankSchema, "/">): UpgradeWebSocket<unknown, any, WSEvents<unknown>>

app

type Hono<BlankEnv, BlankSchema, "/">
returns UpgradeWebSocket<unknown, any, WSEvents<unknown>>

attach_to_server?

type (handle: ServeHandle): void

handle

returns void

PrepareWebsocketOptions
#

testing/cross_backend/testing_server_core.ts view source

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

Options for TestingServerAdapter.prepare_websocket.

max_message_bytes?

Largest inbound WebSocket message, in bytes — pass the largest WsEndpointSpec.max_message_bytes of the mounted endpoints; a smaller value refuses messages the endpoint would accept. Node and Bun take twice it as their frame cap (ws's maxPayload, Bun's maxPayloadLength): past its cap ws closes with no reason and Bun drops the socket without a close frame, so the headroom leaves a message just over the limit to the per-message check register_action_ws makes, while a grossly oversized one is still refused before it is buffered whole. Both close a message just over the limit with WS_CLOSE_MESSAGE_TOO_BIG. The default sits far below ws's own 100 MiB and Bun's 16 MiB, so a build raising an endpoint's cap must pass it here too.

type number

default DEFAULT_WS_MAX_MESSAGE_BYTES

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 at once and settles when the in-flight ones have drained — the core starts it, closes the app (which ends live WebSockets), then awaits it. native is an adapter-specific server reference — used by Node's @hono/node-ws injectWebSocket(server) post-serve hook.

shutdown

type (): Promise<void>

returns 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 shutdown — but the app is the caller's no-domain (or domain) StartTestingServerOptions.build_app and the runtime boundary is the TestingServerAdapter. Refuses any non-loopback bind host (the test binary must stay on loopback — see is_loopback_bind_host).

options

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';

adapter

Runtime-boundary adapter (Node or Bun).

type TestingServerAdapter

daemon_name

Daemon-info namespace — the app name 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 and a close teardown.

type (context: BuildTestingAppContext): Promise<BuiltTestingApp>

context

returns Promise<BuiltTestingApp>

log?

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

type Logger

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_bun.ts) implements this and hands the shape to start_testing_server.

runtime_label

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

type string

runtime

RuntimeDeps capability bundle from create_node_runtime.

type RuntimeDeps

get_connection_ip

Extract the raw TCP connection IP from a Hono context.

type (c: Context<any, any, {}>): string | undefined

c

type Context<any, any, {}>
returns string | undefined

prepare_websocket

Prepare the runtime's WS upgrade helper and its post-serve attach step.

type (options?: PrepareWebsocketOptions | undefined): PreparedWebsocket

options?

optional

serve

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

type (options: { fetch: (request: Request, env?: unknown, executionCtx?: ExecutionContext | undefined) => Response | Promise<Response>; port: number; hostname: string; }): ServeHandle

options

type { fetch: (request: Request, env?: unknown, executionCtx?: ExecutionContext | undefined) => Response | Promise<Response>; port: number; hostname: string; }
returns 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

handler

type () => Promise<void>
returns void

exit

Forceful exit on graceful-shutdown completion or fatal error.

type (code: number): never

code

type number
returns never

Depends on
#

Imported by
#