@claxedo/workspace-relay 0.7.0 → 0.8.0

package/dist/main.d.ts

@@ -1,22 +1,20 @@
 import { type WorkspaceRelayBunDrainController } from "./bun";
 import { type WorkspaceRelayDirectory } from "./directory";
 import { type RelayHostPublicKey, type RevocationLookup, type WorkspaceRelayTarget } from "./server";
-import type { RelayKey } from "./auth";
+import { type RelayKey } from "./auth";
 export { createCachedRevocationClient, createCachedTargetClient } from "./server";
 /**
- * W2c (2026-07-28-001): PostHog is the relay's error sink — one vendor
- * carries error tracking for every runtime behind one distinct_id space.
+ * PostHog is the relay's error sink — one vendor carries error tracking for
+ * every runtime behind one distinct_id space.
  *
  * Sending requires two independent opt-ins: `CLAXEDO_TELEMETRY_MODE=on` AND
  * `CLAXEDO_POSTHOG_KEY` (`POSTHOG_KEY` accepted as a fallback — the same
- * unprefixed name claxedo-server's posthog.ts already reads). Any other
- * combination → no `PostHog` client is ever constructed: zero SDK overhead,
- * zero network — a clean no-op safe to ship before the telemetry account
- * exists. Host defaults to `https://us.i.posthog.com` (the canonical ingest
- * host — NOT the legacy `app.posthog.com` default some SDKs ship). Release =
- * git SHA passed by the D11 deploy workflow (`CLAXEDO_RELEASE`; `GIT_SHA`
- * accepted as alias); captures are tagged unit=relay + deployment_mode
- * (absent → "self-host", mirroring D9's default).
+ * unprefixed name claxedo-server's posthog.ts reads). Any other combination
+ * constructs no `PostHog` client: zero SDK overhead, zero network. Host
+ * defaults to `https://us.i.posthog.com` (the ingest host, not the legacy
+ * `app.posthog.com` default some SDKs ship). Release is the git SHA from
+ * `CLAXEDO_RELEASE` (`GIT_SHA` accepted as alias); captures are tagged
+ * unit=relay + deployment_mode (absent → "local").
  *
  * `posthog-node` runs fine on Bun (`Bun.serve`), unlike the Cloudflare
  * Worker, which keeps it off its import graph entirely (see worker.ts).
@@ -122,17 +120,10 @@ export declare function loadRuntimeAccessKeyOrJwks(env: LoadRuntimeAccessKeyEnv)
  */
 export type LoadRelayHostKeyMaterialEnv = {
     /**
-     * Used to gate the production fail-closed check for the RHT signing key.
-     * If `production` and no signing key PEM is configured, the loader exits
-     * with code 2 rather than silently generating an ephemeral key (which
-     * would be different on every instance and break verification across a
-     * multi-instance deploy).
-     *
-     * Note: T2's `validateProductionEnv` is the canonical home for top-level
-     * env validation, but this check lives here because the loader already
-     * inspects the signing-key env var and the failure mode is local. The
-     * boot path could optionally re-route through `validateProductionEnv` in
-     * a future refactor.
+     * Gates the production fail-closed check: with no signing-key PEM in
+     * `production` the loader exits 2 instead of generating an ephemeral key.
+     * The check lives here rather than in `validateProductionEnv` because the
+     * loader already inspects the signing-key env var.
      */
     NODE_ENV?: string | undefined;
     CLAXEDO_RELAY_HOST_SIGNING_KEY_PEM?: string | undefined;
@@ -148,7 +139,7 @@ export type RelayHostKeyMaterial = {
 };
 export declare function loadRelayHostKeyMaterial(env: LoadRelayHostKeyMaterialEnv): Promise<RelayHostKeyMaterial>;
 /**
- * T16: parse `CLAXEDO_RELAY_AUDIT_ACCEPT_SAMPLE_RATE` into a number in [0, 1].
+ * Parse `CLAXEDO_RELAY_AUDIT_ACCEPT_SAMPLE_RATE` into a number in [0, 1].
  * Falls back to a NODE_ENV-gated default (production: 0.1, dev/test: 1.0) if
  * unset, empty, or out of range. Exported for tests.
  */
@@ -158,7 +149,7 @@ export type ParseAuditAcceptSampleRateEnv = {
 };
 export declare function parseAuditAcceptSampleRate(env: ParseAuditAcceptSampleRateEnv): number;
 /**
- * T31: parse the `CLAXEDO_RELAY_METRICS_TOKEN` env var. Returns `undefined`
+ * Parse the `CLAXEDO_RELAY_METRICS_TOKEN` env var. Returns `undefined`
  * for missing/empty/whitespace-only values so the relay can fall back to its
  * loopback-only `/metrics` access policy.
  */
@@ -177,18 +168,28 @@ export declare function directHttpConcurrencyFromEnv(env: DirectHttpConcurrencyE
 export type ResolverClientCacheOptions = {
     targetCacheTtlMs?: number;
     revocationCacheTtlMs?: number;
+    /**
+     * Absolute URL of the control plane's host-generation lookup. Unset derives
+     * `<resolver base>/host-generation`, the route every resolver base serves
+     * next to `/target` and `/revocation`.
+     */
+    hostGenerationUrl?: string;
+    hostGenerationCacheTtlMs?: number;
 };
 export type ResolverClientCacheEnv = {
     CLAXEDO_RELAY_TARGET_CACHE_TTL_MS?: string | undefined;
     CLAXEDO_RELAY_REVOCATION_CACHE_TTL_MS?: string | undefined;
+    CLAXEDO_RELAY_HOST_GENERATION_URL?: string | undefined;
+    CLAXEDO_RELAY_HOST_GENERATION_CACHE_TTL_MS?: string | undefined;
 };
 export declare function resolverClientCacheOptionsFromEnv(env: ResolverClientCacheEnv): ResolverClientCacheOptions;
 export declare function createResolverClient(baseUrl: string, token: string | undefined, options?: ResolverClientCacheOptions): {
     target: (workspaceId: string, hostId: string) => Promise<WorkspaceRelayTarget | undefined>;
     revocation: RevocationLookup;
+    hostGeneration: import("./server").HostGenerationLookup;
 };
 /**
- * T9: graceful SIGTERM drain wiring.
+ * Graceful SIGTERM drain wiring.
  *
  * On `SIGTERM` (or `SIGINT` for local dev) the relay must:
  *   1. Flip the drain flag so `/health` reports 503 and Fly removes the
@@ -197,7 +198,7 @@ export declare function createResolverClient(baseUrl: string, token: string | un
  *   2. Wait up to `drainTimeoutMs` (default 30 s, override via
  *      `CLAXEDO_RELAY_DRAIN_TIMEOUT_MS`) for the in-flight tunnel HTTP
  *      response map to empty across every connected host tunnel.
- *   3. Release the directory's TTL sweep timer (T18 added `dispose()`) so
+ *   3. Release the directory's TTL sweep timer via `directory.dispose()` so
  *      the process can exit cleanly without a dangling `setInterval`.
  *   4. Exit with code 0.
  *
@@ -219,6 +220,12 @@ export type ShutdownDrainHandlerOptions = {
     signals?: NodeJS.Signals[];
     /** Defaults to a no-op (we let Bun.serve get GC'd as part of process exit). */
     stopServer?: () => Promise<void> | void;
+    /**
+     * Upper bound on `stopServer`. A wedged socket close must not outlast the
+     * platform's kill timeout, or a graceful exit becomes a SIGKILL that skips
+     * `directory.dispose()`. Defaults to 5 s; tests override it to stay fast.
+     */
+    stopTimeoutMs?: number;
 };
 export type ShutdownDrainHandle = {
     trigger(): Promise<void>;
@@ -232,12 +239,14 @@ export type FatalProcessHandlerOptions = {
     log?: (message: string) => void;
     register?: boolean;
     /**
-     * W2c: error-tracker hook, invoked (and awaited) before teardown so a fatal
+     * Error-tracker hook, invoked (and awaited) before teardown so a fatal
      * crash reaches PostHog before the process exits. Failures are logged and
      * never block the exit path. Defaults to none (tests, key-absent runs).
      */
     report?: (error: unknown, source: "uncaughtException" | "unhandledRejection") => void | Promise<void>;
     stopServer?: () => Promise<void> | void;
+    /** Upper bound on `stopServer`; see `ShutdownDrainHandlerOptions.stopTimeoutMs`. */
+    stopTimeoutMs?: number;
 };
 export type FatalProcessHandle = {
     trigger(error: unknown, source: "uncaughtException" | "unhandledRejection"): Promise<void>;