@specific.dev/spectest 0.38.0 → 0.41.0

package/dist/harness/file-mounts.js

@@ -0,0 +1,119 @@
+/**
+ * Staging `files` and `certificates` for bind-mounting into a container.
+ *
+ * Ported out of `daemon.ts` as part of the harness split. These are the
+ * *pre-entrypoint* injection point — the only way to put something in place
+ * before the container's own process starts, which is what a config file a
+ * daemon reads at startup, or a TLS key it refuses to run without, actually
+ * needs. `setup` and `helpers` both run too late.
+ *
+ * What lives here is the part that decides *what* is staged and with which
+ * permissions. Writing the bytes, minting the certificate and running chown
+ * stay with the caller — but every rule that has ever been reported as a bug
+ * is a pure function below, with a test.
+ *
+ * ## The permission rules, and why they are not obvious
+ *
+ * **A bind mount carries the host inode's mode and ownership straight
+ * through, and the harness writes as root.** So `mode` on its own is not
+ * enough: locking a file down to `0600` gives the container a file owned by
+ * root that whoever it runs as cannot open. Postgres refusing to start on
+ * its own TLS key is the canonical report. `user`/`group` exist to name the
+ * reader, and naming one is what makes a strict mode usable.
+ *
+ * **Declaring a reader also implies the mode.** A key whose owner is named
+ * gets the strictest mode that owner can still open — `0600` when a user is
+ * named, `0640` when only a group is. A server that checks (postgres, ssh)
+ * refuses a lax key, so defaulting to something permissive would just move
+ * the failure. This only applies when an owner was named, so no existing
+ * environment changes behaviour.
+ *
+ * **`-1` means "leave this half alone", and Bun will not accept it.**
+ * chown(2) and node both read `-1` as unchanged, which is how plain `chown`
+ * lets you set a user without touching the group. Bun's `fs.chown` rejects
+ * it with `EPERM` (measured on Bun 1.3.14), so the untouched half has to be
+ * filled in from the file's current owner before the call —
+ * {@link resolveChownIds} is that, kept separate so the rule is testable
+ * without a filesystem.
+ */
+/** `{{SPECTEST_SERVICE}}` → the service's map key.
+ *
+ *  Lets a component author self-referential config without knowing the key
+ *  the user will choose for it — k3s's `registries.yaml` pointing at
+ *  `<key>.internal:5000` is the reason this exists. */
+export function expandServiceToken(text, service) {
+    return text.replaceAll("{{SPECTEST_SERVICE}}", service);
+}
+/** Parse a `user`/`group` value that may be a numeric id already. */
+export function numericId(value) {
+    return value !== undefined && /^[0-9]+$/.test(value) ? Number(value) : undefined;
+}
+/**
+ * Does resolving this owner need the image's `/etc/passwd` + `/etc/group`?
+ *
+ * Probing an image costs a `docker create` + `docker cp`, so it is worth
+ * knowing that two numeric ids need no probe at all.
+ */
+export function needsIdTables(user, group) {
+    return ((user !== undefined && numericId(user) === undefined) ||
+        (group !== undefined && numericId(group) === undefined));
+}
+/**
+ * The mode a certificate's key should get.
+ *
+ * `undefined` when no owner was named — the file keeps whatever the harness
+ * wrote, which is the pre-existing behaviour for every environment that
+ * never asked about ownership.
+ */
+export function defaultKeyMode(explicit, owner) {
+    if (explicit)
+        return explicit;
+    if (!owner)
+        return undefined;
+    // Only a group was named, so the group has to be able to read it.
+    return owner.uid === -1 ? "0640" : "0600";
+}
+/**
+ * Fill in the halves of a chown that were meant to be left alone.
+ *
+ * Takes the file's current ids rather than reading them, so the rule is a
+ * pure function. See the module header for why `-1` cannot simply be passed
+ * through under Bun.
+ */
+export function resolveChownIds(owner, current) {
+    return {
+        uid: owner.uid < 0 ? current.uid : owner.uid,
+        gid: owner.gid < 0 ? current.gid : owner.gid,
+    };
+}
+/** True when the owner asks for no change at all, so the chown can be
+ *  skipped entirely rather than resolved and re-applied. */
+export function isNoopChown(owner) {
+    return owner.uid < 0 && owner.gid < 0;
+}
+/**
+ * Reject a container path that isn't absolute.
+ *
+ * A relative path would be resolved by docker against the container's
+ * working directory, so the file would land somewhere that depends on the
+ * image rather than where the project said — a mount that appears to work
+ * and puts the file in the wrong place is worse than one that refuses.
+ */
+export function assertAbsolute(service, label, p) {
+    if (!p.startsWith("/")) {
+        throw new Error(`service ${JSON.stringify(service)}: ${label} ${JSON.stringify(p)} must be absolute`);
+    }
+}
+/** The hostnames a certificate entry covers, with the service token
+ *  expanded and the empty case refused. */
+export function certificateHostnames(service, index, hostnames) {
+    const expanded = hostnames.map((h) => expandServiceToken(h, service));
+    if (expanded.length === 0) {
+        throw new Error(`service ${JSON.stringify(service)}: certificate entry ${index} lists no hostnames`);
+    }
+    return expanded;
+}
+/** A read-only single-file bind mount. */
+export function mountFlag(hostPath, containerPath) {
+    return `--volume=${hostPath}:${containerPath}:ro`;
+}

package/dist/harness/hostmatch.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Hostname matching for ingress: which route serves a request, and which
+ * certificate may serve a TLS handshake.
+ *
+ * Ported out of `daemon.ts` as part of the harness split. These are pure
+ * functions guarding two rules that are easy to state and easy to get
+ * subtly wrong, and until now they had no tests at all.
+ *
+ * ## The two rules
+ *
+ * **Precedence: exact first, then longest suffix.** A `*.example.com`
+ * route and an `api.example.com` route can both match `api.example.com`;
+ * the exact one wins. Among competing wildcards the longest suffix wins,
+ * so `*.eu.example.com` beats `*.example.com` for `a.eu.example.com`.
+ * The same ordering applies at all three layers — DNS in the resolver,
+ * routes here, and SNI in Bun's cert table.
+ *
+ * **Routes and certificates match differently, deliberately.** A wildcard
+ * *route* matches any depth of subdomain, but a wildcard *certificate*
+ * covers exactly one label — which is what RFC 6125 says and what every
+ * TLS client enforces. So `a.b.example.com` under `*.example.com` is
+ * reverse-proxied happily over http, and needs its own cert entry for
+ * https.
+ *
+ * That asymmetry is load-bearing, not an oversight. Loosening
+ * {@link wildcardCoversHost} to a plain suffix test would make
+ * {@link certCovers} report that a deep name is already covered, so the
+ * runtime-TLS path would skip minting the leaf that name actually needs
+ * and hand the client a certificate it rejects — a TLS failure at request
+ * time, far from the code that caused it.
+ */
+export { isWildcard } from "../ingress";
+/** `"*.example.com"` → `".example.com"`. */
+export declare function wildcardSuffix(pattern: string): string;
+/**
+ * Does a wildcard *certificate* pattern cover `hostname`?
+ *
+ * One label only (RFC 6125): `*.example.com` covers `api.example.com` and
+ * NOT `a.b.example.com`. See the module header for why this must not be
+ * relaxed into a suffix test.
+ */
+export declare function wildcardCoversHost(pattern: string, hostname: string): boolean;
+/**
+ * Is `hostname` already served by an exact or wildcard certificate?
+ *
+ * Takes the set of configured server names rather than reading module
+ * state, so the rule is testable on its own — the caller passes
+ * `HTTPS_CERT_BY_HOST.keys()`.
+ */
+export declare function certCovers(serverNames: Iterable<string>, hostname: string): boolean;
+/**
+ * Pick the route for `host`: exact match first, then the longest matching
+ * wildcard suffix.
+ *
+ * Unlike a certificate, a wildcard route matches any depth — `*.test`
+ * serves `a.b.test`.
+ */
+export declare function matchRoute<T>(byHost: ReadonlyMap<string, T>, host: string): T | undefined;
+/**
+ * Strip the port from a `Host` header value.
+ *
+ * IPv6 literals arrive bracketed (`[::1]:8080`), so a naive split on the
+ * last `:` would mangle them; the brackets are what disambiguate.
+ */
+export declare function hostWithoutPort(hostHeader: string): string;

package/dist/harness/hostmatch.js

@@ -0,0 +1,108 @@
+/**
+ * Hostname matching for ingress: which route serves a request, and which
+ * certificate may serve a TLS handshake.
+ *
+ * Ported out of `daemon.ts` as part of the harness split. These are pure
+ * functions guarding two rules that are easy to state and easy to get
+ * subtly wrong, and until now they had no tests at all.
+ *
+ * ## The two rules
+ *
+ * **Precedence: exact first, then longest suffix.** A `*.example.com`
+ * route and an `api.example.com` route can both match `api.example.com`;
+ * the exact one wins. Among competing wildcards the longest suffix wins,
+ * so `*.eu.example.com` beats `*.example.com` for `a.eu.example.com`.
+ * The same ordering applies at all three layers — DNS in the resolver,
+ * routes here, and SNI in Bun's cert table.
+ *
+ * **Routes and certificates match differently, deliberately.** A wildcard
+ * *route* matches any depth of subdomain, but a wildcard *certificate*
+ * covers exactly one label — which is what RFC 6125 says and what every
+ * TLS client enforces. So `a.b.example.com` under `*.example.com` is
+ * reverse-proxied happily over http, and needs its own cert entry for
+ * https.
+ *
+ * That asymmetry is load-bearing, not an oversight. Loosening
+ * {@link wildcardCoversHost} to a plain suffix test would make
+ * {@link certCovers} report that a deep name is already covered, so the
+ * runtime-TLS path would skip minting the leaf that name actually needs
+ * and hand the client a certificate it rejects — a TLS failure at request
+ * time, far from the code that caused it.
+ */
+// Re-exported rather than redefined: `ingress.ts` owns the wildcard shape
+// for the declarative lowering, and two copies of "what counts as a
+// wildcard" is precisely the drift this port exists to remove.
+export { isWildcard } from "../ingress";
+import { isWildcard } from "../ingress";
+/** `"*.example.com"` → `".example.com"`. */
+export function wildcardSuffix(pattern) {
+    return pattern.slice(1);
+}
+/**
+ * Does a wildcard *certificate* pattern cover `hostname`?
+ *
+ * One label only (RFC 6125): `*.example.com` covers `api.example.com` and
+ * NOT `a.b.example.com`. See the module header for why this must not be
+ * relaxed into a suffix test.
+ */
+export function wildcardCoversHost(pattern, hostname) {
+    const suffix = wildcardSuffix(pattern);
+    if (!hostname.endsWith(suffix))
+        return false;
+    const label = hostname.slice(0, -suffix.length);
+    return label.length > 0 && !label.includes(".");
+}
+/**
+ * Is `hostname` already served by an exact or wildcard certificate?
+ *
+ * Takes the set of configured server names rather than reading module
+ * state, so the rule is testable on its own — the caller passes
+ * `HTTPS_CERT_BY_HOST.keys()`.
+ */
+export function certCovers(serverNames, hostname) {
+    const names = [...serverNames];
+    if (names.includes(hostname))
+        return true;
+    return names.some((n) => isWildcard(n) && wildcardCoversHost(n, hostname));
+}
+/**
+ * Pick the route for `host`: exact match first, then the longest matching
+ * wildcard suffix.
+ *
+ * Unlike a certificate, a wildcard route matches any depth — `*.test`
+ * serves `a.b.test`.
+ */
+export function matchRoute(byHost, host) {
+    const exact = byHost.get(host);
+    if (exact !== undefined)
+        return exact;
+    let best;
+    let bestLen = -1;
+    for (const [pattern, route] of byHost) {
+        if (!isWildcard(pattern))
+            continue;
+        const suffix = wildcardSuffix(pattern);
+        if (host.endsWith(suffix) && suffix.length > bestLen) {
+            best = route;
+            bestLen = suffix.length;
+        }
+    }
+    return best;
+}
+/**
+ * Strip the port from a `Host` header value.
+ *
+ * IPv6 literals arrive bracketed (`[::1]:8080`), so a naive split on the
+ * last `:` would mangle them; the brackets are what disambiguate.
+ */
+export function hostWithoutPort(hostHeader) {
+    const h = hostHeader.trim();
+    if (h.startsWith("[")) {
+        const close = h.indexOf("]");
+        if (close !== -1)
+            return h.slice(0, close + 1);
+        return h;
+    }
+    const colon = h.lastIndexOf(":");
+    return colon === -1 ? h : h.slice(0, colon);
+}

package/dist/harness/http-proxy.d.ts

@@ -0,0 +1,62 @@
+/**
+ * HTTP semantics the ingress proxy has to get right: which headers must
+ * not be forwarded, and how CORS is answered.
+ *
+ * Ported out of `daemon.ts`. Pure request→response logic, so the rules
+ * below are now assertable rather than inferred from a header list.
+ */
+/**
+ * Headers that describe **this** connection rather than the message, and
+ * so must never be copied to the next hop (RFC 9110 §7.6.1).
+ *
+ * Forwarding `transfer-encoding` or `content-length` from a re-encoded
+ * body is the classic way to produce a response the client cannot frame;
+ * forwarding `connection` leaks our keep-alive intent to the upstream.
+ * `host` is here because the proxy sets its own — the upstream must see
+ * the service it actually is, not the public name the client asked for.
+ */
+export declare const HOP_BY_HOP_HEADERS: ReadonlySet<string>;
+export declare function isHopByHop(name: string): boolean;
+/** Copy headers, dropping the ones that belong to this connection. */
+export declare function forwardableHeaders(headers: Headers): Headers;
+/**
+ * A CORS preflight is an `OPTIONS` carrying both `Origin` and
+ * `Access-Control-Request-Method`. An `OPTIONS` without them is a normal
+ * request (an API asking what it supports) and must be proxied, not
+ * answered here.
+ */
+export declare function isCorsPreflight(req: {
+    method: string;
+    headers: {
+        has(n: string): boolean;
+    };
+}): boolean;
+/**
+ * Answer a preflight permissively — the environment is hermetic, so
+ * there is nothing here to protect from itself, and a test failing on
+ * CORS teaches nothing about the app.
+ *
+ * The one rule that is not a matter of taste: the **specific** origin is
+ * echoed rather than `*`. `Allow-Origin: *` together with
+ * `Allow-Credentials: true` is a spec violation that browsers reject
+ * outright, so a wildcard would break exactly the credentialed requests
+ * this is meant to permit.
+ */
+export declare function corsPreflightResponse(req: {
+    headers: {
+        get(n: string): string | null;
+    };
+}): Response;
+/**
+ * Add CORS headers to a proxied response, without overriding the
+ * upstream's own.
+ *
+ * An app that already sets `Access-Control-Allow-Origin` has an opinion —
+ * possibly a deliberately restrictive one that a test is checking — and
+ * replacing it would make the environment lie about the app's behaviour.
+ */
+export declare function augmentCorsResponse(req: {
+    headers: {
+        get(n: string): string | null;
+    };
+}, res: Response): Response;

package/dist/harness/http-proxy.js

@@ -0,0 +1,104 @@
+/**
+ * HTTP semantics the ingress proxy has to get right: which headers must
+ * not be forwarded, and how CORS is answered.
+ *
+ * Ported out of `daemon.ts`. Pure request→response logic, so the rules
+ * below are now assertable rather than inferred from a header list.
+ */
+/**
+ * Headers that describe **this** connection rather than the message, and
+ * so must never be copied to the next hop (RFC 9110 §7.6.1).
+ *
+ * Forwarding `transfer-encoding` or `content-length` from a re-encoded
+ * body is the classic way to produce a response the client cannot frame;
+ * forwarding `connection` leaks our keep-alive intent to the upstream.
+ * `host` is here because the proxy sets its own — the upstream must see
+ * the service it actually is, not the public name the client asked for.
+ */
+export const HOP_BY_HOP_HEADERS = new Set([
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailers",
+    "transfer-encoding",
+    "upgrade",
+    "host",
+]);
+export function isHopByHop(name) {
+    return HOP_BY_HOP_HEADERS.has(name.toLowerCase());
+}
+/** Copy headers, dropping the ones that belong to this connection. */
+export function forwardableHeaders(headers) {
+    const out = new Headers();
+    headers.forEach((value, key) => {
+        if (!isHopByHop(key))
+            out.append(key, value);
+    });
+    return out;
+}
+/**
+ * A CORS preflight is an `OPTIONS` carrying both `Origin` and
+ * `Access-Control-Request-Method`. An `OPTIONS` without them is a normal
+ * request (an API asking what it supports) and must be proxied, not
+ * answered here.
+ */
+export function isCorsPreflight(req) {
+    return (req.method === "OPTIONS" &&
+        req.headers.has("origin") &&
+        req.headers.has("access-control-request-method"));
+}
+/**
+ * Answer a preflight permissively — the environment is hermetic, so
+ * there is nothing here to protect from itself, and a test failing on
+ * CORS teaches nothing about the app.
+ *
+ * The one rule that is not a matter of taste: the **specific** origin is
+ * echoed rather than `*`. `Allow-Origin: *` together with
+ * `Allow-Credentials: true` is a spec violation that browsers reject
+ * outright, so a wildcard would break exactly the credentialed requests
+ * this is meant to permit.
+ */
+export function corsPreflightResponse(req) {
+    const origin = req.headers.get("origin") ?? "*";
+    const reqHeaders = req.headers.get("access-control-request-headers");
+    const reqMethod = req.headers.get("access-control-request-method");
+    const headers = new Headers();
+    headers.set("access-control-allow-origin", origin);
+    headers.set("access-control-allow-credentials", "true");
+    headers.set("access-control-allow-methods", reqMethod && reqMethod.length > 0 ? reqMethod : "GET,HEAD,PUT,PATCH,POST,DELETE,OPTIONS");
+    headers.set("access-control-allow-headers", reqHeaders && reqHeaders.length > 0 ? reqHeaders : "*");
+    headers.set("access-control-max-age", "600");
+    // The answer depends on what was asked — say so, or a cache will serve
+    // one origin's preflight to another.
+    headers.append("vary", "Origin");
+    headers.append("vary", "Access-Control-Request-Headers");
+    return new Response(null, { status: 204, headers });
+}
+/**
+ * Add CORS headers to a proxied response, without overriding the
+ * upstream's own.
+ *
+ * An app that already sets `Access-Control-Allow-Origin` has an opinion —
+ * possibly a deliberately restrictive one that a test is checking — and
+ * replacing it would make the environment lie about the app's behaviour.
+ */
+export function augmentCorsResponse(req, res) {
+    const origin = req.headers.get("origin");
+    if (!origin)
+        return res;
+    if (res.headers.has("access-control-allow-origin"))
+        return res;
+    try {
+        res.headers.set("access-control-allow-origin", origin);
+        res.headers.set("access-control-allow-credentials", "true");
+        res.headers.append("vary", "Origin");
+    }
+    catch {
+        // Some responses carry guarded/immutable headers — a 101 upgrade stub,
+        // for instance. Leave those exactly as they are rather than failing the
+        // request over a cosmetic header.
+    }
+    return res;
+}

package/dist/harness/ingress-table.d.ts

@@ -0,0 +1,148 @@
+/**
+ * The live ingress tables: which hostname reaches which upstream, and
+ * which certificate serves the TLS handshake for it.
+ *
+ * Ported out of `daemon.ts` as part of the harness split. This module owns
+ * the *tables and the decisions*; the listeners themselves (`Bun.serve`)
+ * stay with the process that binds them, because a socket is not something
+ * you can hand across a module boundary usefully.
+ *
+ * ## Why this state is special
+ *
+ * These tables are ordinary module-scope objects, and that is the whole
+ * design. They live in the harness process, so they are captured by the
+ * memory snapshot and **fork with it** — exactly like fake state and the
+ * names registry. A `dependsOn` child inherits every route its parent
+ * bound; a sibling forked from an earlier snapshot never sees them. That
+ * is what lets a fake provision a real service mid-test and hand the app a
+ * CA-trusted `https://…` endpoint that only that branch of the test DAG
+ * can reach.
+ *
+ * The failure mode to design against is therefore *silence*: a route that
+ * fails to survive doesn't raise anything, it just isn't inherited, and
+ * the test that depended on it fails somewhere else entirely.
+ *
+ * ## The two rules worth stating
+ *
+ * **A route table is identified by its object, not its contents.** Every
+ * listener's request handler closes over the `Map` it was bound with, so
+ * adding an entry takes effect with no rebind — that is what makes a
+ * runtime route possible at all. Replacing the `Map` (rather than mutating
+ * it) silently orphans every listener still holding the old one, and the
+ * routes added afterwards go nowhere. {@link routesFor} is the only way to
+ * reach a table so that this can't be done by accident.
+ *
+ * **A rebind is not free, so it must be earned.** Bun fixes a server's TLS
+ * config at `Bun.serve` time — `reload` will not add an SNI entry — so a
+ * genuinely new certificate means stopping and re-serving :443. It's cheap
+ * (~1 ms) but it is a real interruption of live traffic, and a hostname
+ * already covered by an existing exact or wildcard cert needs nothing but a
+ * route entry. {@link planBind} is that judgement, separated from the
+ * mutation so it can be tested without a network stack.
+ */
+/**
+ * One hostname's upstream: a fake handled in-process, or a container.
+ *
+ * Generic in the fake's runtime record so the harness keeps its own type
+ * through the tables — the alternative, `unknown` plus a cast at each
+ * dispatch site, would trade a real type for a comment.
+ */
+export type Route<F = unknown> = {
+    kind: "fake";
+    fake: F;
+} | {
+    kind: "proxy";
+    service: string;
+    port: number;
+};
+/** A PEM leaf + key, as handed to `Bun.serve`'s TLS config. */
+export interface Leaf {
+    cert: string;
+    key: string;
+}
+/**
+ * The mutable ingress state of one harness process.
+ *
+ * Held by the caller rather than this module so there is no hidden
+ * singleton: tests build one per case, and the harness holds exactly one.
+ */
+export interface IngressTables<F = unknown> {
+    /** Listen port → (hostname → route). Values are mutated in place. */
+    routesByPort: Map<number, Map<string, Route<F>>>;
+    /** SNI server name → leaf. Adding to this is what forces a rebind. */
+    certByHost: Map<string, Leaf>;
+}
+/** Fixed HTTPS port shared by every TLS route (fakes + service `tls`). */
+export declare const INGRESS_HTTPS_PORT = 443;
+/** Fixed HTTP port, always bound alongside :443 so both schemes work. */
+export declare const INGRESS_HTTP_PORT = 80;
+export declare function emptyTables<F = unknown>(): IngressTables<F>;
+/**
+ * The route table for `port`, creating it if absent.
+ *
+ * Always returns the *same* object for a given port for as long as the
+ * tables live. Callers must mutate what they get back and must never swap
+ * in a replacement — see the module header for what that breaks.
+ */
+export declare function routesFor<F>(tables: IngressTables<F>, port: number): Map<string, Route<F>>;
+/** What binding `hostname` will require, before anything is mutated. */
+export interface BindPlan {
+    /** No existing cert covers the hostname, so a leaf must be minted. */
+    needsCert: boolean;
+    /** The :443 listener must be stopped and re-served. */
+    needsHttpsRebind: boolean;
+}
+/**
+ * Decide what binding `hostname` for TLS costs.
+ *
+ * A rebind is needed when a new certificate is going into the SNI table,
+ * or when :443 isn't listening yet. It is deliberately *not* needed for a
+ * hostname an existing wildcard already covers — the common case when a
+ * component claims a whole domain up front and services appear under it
+ * later, and the reason a fake can mint endpoints in a loop without
+ * restarting the listener once per iteration.
+ */
+export declare function planBind<F>(tables: IngressTables<F>, hostname: string, opts: {
+    httpsListening: boolean;
+}): BindPlan;
+/**
+ * Point `hostname` at `route` on both :80 and :443.
+ *
+ * Boot `tls` serves both schemes, and runtime `tls` matches it — a service
+ * reachable only over https would differ from its boot-time twin in a way
+ * nothing declares.
+ */
+export declare function bindRoute<F>(tables: IngressTables<F>, hostname: string, route: Route<F>): void;
+/**
+ * Drop `hostname`'s routes, so it 404s.
+ *
+ * The certificate is deliberately left in the SNI table: it is harmless
+ * without a route, and removing it would force an otherwise unnecessary
+ * :443 rebind at exactly the moment a service is going away.
+ */
+export declare function unbindRoute<F>(tables: IngressTables<F>, hostname: string): void;
+/** The SNI entries for `Bun.serve`'s TLS config. */
+export declare function certEntries<F>(tables: IngressTables<F>): Array<{
+    cert: string;
+    key: string;
+    serverName: string;
+}>;
+/** Clear every table — used between `/load` calls so a new project's
+ *  routes bind against a clean slate rather than the old project's. */
+export declare function clearTables<F>(tables: IngressTables<F>): void;
+/**
+ * Point a hostname at an IP in a names registry document, choosing the
+ * exact or wildcard table by the hostname's shape.
+ *
+ * A wildcard has no `--add-host` or `--network-alias` equivalent, so the
+ * resolver's suffix table is the only place it can exist; an exact name
+ * could live in either, and goes in the exact table so it keeps winning
+ * over any wildcard that also matches.
+ */
+export declare function registryTarget(hostname: string): {
+    wildcard: true;
+    suffix: string;
+} | {
+    wildcard: false;
+    host: string;
+};