import '../assert_dev_env.js';
/**
 * 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_server_node.ts` (`@hono/node-server` + `@hono/node-ws`) and
 * `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.js';`, 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.
 *
 * @module
 */
import type { Context, Hono } from 'hono';
import type { UpgradeWebSocket } from 'hono/ws';
import { type Logger as LoggerType } from '@fuzdev/fuz_util/log.js';
import type { RuntimeDeps } from '../../runtime/deps.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.
 */
export interface ServeHandle {
    shutdown: () => Promise<void>;
    /** Adapter-specific server ref for post-serve hooks. Type-erased at the seam. */
    native?: unknown;
}
/**
 * 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 {@link ServeHandle} — Node uses it for
 * `injectWebSocket(server)`; Deno leaves it undefined.
 */
export interface PreparedWebsocket {
    upgrade_websocket: UpgradeWebSocket;
    attach_to_server?: (handle: ServeHandle) => void;
}
/**
 * Runtime adapter contract for the test-binary entry. Each adapter
 * (`testing_server_node.ts`, `testing_server_deno.ts`) implements this and
 * hands the shape to {@link start_testing_server}.
 */
export interface TestingServerAdapter {
    /** Human-readable runtime label for log output (e.g. `"Node"`, `"Deno"`). */
    runtime_label: string;
    /** `RuntimeDeps` capability bundle from `create_node_runtime` / `create_deno_runtime`. */
    runtime: RuntimeDeps;
    /** Extract the raw TCP connection IP from a Hono context. */
    get_connection_ip: (c: Context) => string | undefined;
    /** Build the WS upgrade closure after the caller's `build_app` returns the app. */
    prepare_websocket: (app: Hono) => PreparedWebsocket;
    /** Bind `app.fetch` to `port` on `hostname`; return a {@link ServeHandle}. */
    serve: (options: {
        fetch: Hono['fetch'];
        port: number;
        hostname: string;
    }) => ServeHandle;
    /** Current process pid (for `daemon.json`). */
    pid: number;
    /** Register SIGINT/SIGTERM listeners that invoke `handler` once each. */
    register_shutdown_signals: (handler: () => Promise<void>) => void;
    /** Forceful exit on graceful-shutdown completion or fatal error. */
    exit: (code: number) => never;
}
/**
 * The assembled app a {@link StartTestingServerOptions.build_app} 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.
 */
export interface BuiltTestingApp {
    /** The assembled Hono app (HTTP routes + RPC already mounted). */
    app: Hono;
    /** Tear down backend(s) + DB + any rotation on graceful shutdown. */
    close: () => Promise<void>;
    /** Mount WS endpoint(s) given the runtime-prepared upgrade closure. */
    mount_websocket?: (upgrade_websocket: UpgradeWebSocket) => void;
}
/** Options for {@link start_testing_server}. */
export interface StartTestingServerOptions {
    /** Runtime-boundary adapter (Node or Deno). */
    adapter: TestingServerAdapter;
    /**
     * 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.
     */
    daemon_name: string;
    /** Bind host (e.g. `'localhost'`). */
    host: string;
    /** Bind port. */
    port: number;
    /** App version recorded in `daemon.json`. */
    app_version?: string;
    /**
     * 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.
     */
    build_app: () => Promise<BuiltTestingApp>;
    /** Optional logger; defaults to a `[daemon_name]`-namespaced `Logger`. */
    log?: LoggerType;
}
/**
 * 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) {@link StartTestingServerOptions.build_app}
 * and the runtime boundary is the {@link TestingServerAdapter}. Refuses to
 * bind an open host (the test binary must stay on loopback).
 */
export declare const start_testing_server: (options: StartTestingServerOptions) => Promise<void>;
//# sourceMappingURL=testing_server_core.d.ts.map