@claxedo/workspace-relay 0.6.0 → 0.8.0

package/dist/main.d.ts

@@ -1,51 +1,69 @@
 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";
 /**
- * D12 observability: Sentry on the relay (ops floor ADR
- * docs/plans/2026-07-11-016-wp-ops-floor-design.md §4).
+ * PostHog is the relay's error sink — one vendor carries error tracking for
+ * every runtime behind one distinct_id space.
  *
- * Gated on `CLAXEDO_RELAY_SENTRY_DSN` (the relay's OWN DSN env — separate
- * Sentry project from the control plane). Absent DSN → `Sentry.init` is never
- * called: zero SDK overhead, zero network — the documented no-op posture, safe
- * before the Sentry account exists. Release = git SHA passed by the D11
- * deploy workflow (`CLAXEDO_RELEASE`; `GIT_SHA` accepted as alias); events are
- * tagged unit=relay + deployment_mode (absent → "self-host", mirroring D9's
- * default). Tracing stays off (ADR: it is where Sentry gets expensive).
+ * 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 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").
  *
- * The relay is a Bun process (`Bun.serve`), so this uses `@sentry/bun` —
- * Sentry's Bun-native SDK with the same init-gated pattern as @sentry/node
- * (https://docs.sentry.io/platforms/javascript/guides/bun/).
+ * `posthog-node` runs fine on Bun (`Bun.serve`), unlike the Cloudflare
+ * Worker, which keeps it off its import graph entirely (see worker.ts).
  */
 export type RelayObservabilityEnv = {
-    CLAXEDO_RELAY_SENTRY_DSN?: string | undefined;
+    /** Only `on` permits sending, matched case-insensitively after trimming. */
+    CLAXEDO_TELEMETRY_MODE?: string | undefined;
+    CLAXEDO_POSTHOG_KEY?: string | undefined;
+    POSTHOG_KEY?: string | undefined;
+    CLAXEDO_POSTHOG_HOST?: string | undefined;
     CLAXEDO_RELEASE?: string | undefined;
     GIT_SHA?: string | undefined;
     CLAXEDO_DEPLOYMENT_MODE?: string | undefined;
     /** Accept process.env verbatim (extra keys are ignored). */
     [key: string]: string | undefined;
 };
-export type RelaySentryOptions = {
-    dsn: string;
+export type RelayTelemetryOptions = {
+    key: string;
+    host: string;
     release?: string;
-    tracesSampleRate: 0;
-    initialScope: {
-        tags: {
-            unit: "relay";
-            deployment_mode: string;
-        };
+    tags: {
+        unit: "relay";
+        deployment_mode: string;
     };
 };
 /**
- * Pure env → Sentry options resolver. `undefined` = DSN absent = do NOT init
- * (no client, no network). Exported for tests.
+ * Pure env → PostHog options resolver. `undefined` = do NOT construct a client
+ * (no client, no network), which is the answer unless BOTH opt-ins are
+ * present. The mode is read before the key so that a deployment which has not
+ * said `on` stays silent no matter which keys reach its environment.
+ * Exported for tests.
  */
-export declare function relaySentryOptions(env: RelayObservabilityEnv): RelaySentryOptions | undefined;
+export declare function relayTelemetryOptions(env: RelayObservabilityEnv): RelayTelemetryOptions | undefined;
 export declare function initRelayObservability(env?: RelayObservabilityEnv): {
     enabled: boolean;
 };
+/**
+ * Capture-and-flush used by the fatal handlers and the startup catch. With no
+ * initialized client (key absent) this is a documented no-op. Never throws —
+ * observability must not preempt the exit path.
+ *
+ * `distinctId: "system"` mirrors the ops-plane convention: process-fatal
+ * events carry no user identity. `client.flush()` has no built-in timeout,
+ * so it races a 2s timer; the flush promise's
+ * rejection is swallowed even when the timer wins the race, so a slow network
+ * failure that resolves after the timeout never surfaces as a second
+ * unhandledRejection mid-shutdown.
+ */
+export declare function reportFatal(error: unknown): Promise<void>;
 /**
  * Production fail-closed gate for the relay → claxedo-server resolver channel.
  *
@@ -102,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;
@@ -128,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.
  */
@@ -138,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.
  */
@@ -157,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
@@ -177,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.
  *
@@ -199,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>;
@@ -212,12 +239,14 @@ export type FatalProcessHandlerOptions = {
     log?: (message: string) => void;
     register?: boolean;
     /**
-     * D12: error-tracker hook, invoked (and awaited) before teardown so a fatal
-     * crash reaches Sentry before the process exits. Failures are logged and
-     * never block the exit path. Defaults to none (tests, DSN-absent runs).
+     * 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>;