@claxedo/workspace-relay 0.8.0 → 0.10.0

package/dist/main.d.ts

@@ -1,255 +0,0 @@
-import { type WorkspaceRelayBunDrainController } from "./bun";
-import { type WorkspaceRelayDirectory } from "./directory";
-import { type RelayHostPublicKey, type RevocationLookup, type WorkspaceRelayTarget } from "./server";
-import { type RelayKey } from "./auth";
-export { createCachedRevocationClient, createCachedTargetClient } from "./server";
-/**
- * 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 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).
- */
-export type RelayObservabilityEnv = {
-    /** 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 RelayTelemetryOptions = {
-    key: string;
-    host: string;
-    release?: string;
-    tags: {
-        unit: "relay";
-        deployment_mode: string;
-    };
-};
-/**
- * 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 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.
- *
- * If `CLAXEDO_RELAY_RESOLVER_TOKEN` is missing/empty in production the relay
- * would otherwise call the resolver unauthenticated. Refuse to boot.
- *
- * Allowed in dev/test for ergonomics — the resolver itself falls back to a
- * loopback-only check when no token is configured.
- */
-export type ValidateProductionEnvInput = {
-    NODE_ENV?: string | undefined;
-    CLAXEDO_RELAY_RESOLVER_TOKEN?: string | undefined;
-};
-export type ValidateProductionEnvResult = {
-    ok: true;
-} | {
-    ok: false;
-    exitCode: 2;
-    message: string;
-};
-export declare function validateProductionEnv(env: ValidateProductionEnvInput): ValidateProductionEnvResult;
-/**
- * Resolve the verification key (or keyset resolver) for Runtime Access Tokens.
- *
- * Precedence: `CLAXEDO_CONTROL_PLANE_JWKS_URL` > `CLAXEDO_RUNTIME_ACCESS_TOKEN_PUBLIC_KEY_PEM`.
- * The PEM env var is kept as a fallback so JWKS rollouts can ship gradually.
- *
- * Exported for tests.
- */
-export type LoadRuntimeAccessKeyEnv = {
-    CLAXEDO_CONTROL_PLANE_JWKS_URL?: string | undefined;
-    CLAXEDO_RUNTIME_ACCESS_TOKEN_PUBLIC_KEY_PEM?: string | undefined;
-};
-export declare function loadRuntimeAccessKeyOrJwks(env: LoadRuntimeAccessKeyEnv): Promise<RelayKey>;
-/**
- * Resolve the RHT key material — both the private key used to sign RHTs and
- * the public key(s) we publish at `/.well-known/jwks.json`.
- *
- * Precedence for the public counterpart:
- *   1. `CLAXEDO_RELAY_HOST_PUBLIC_KEY_PEM` (explicit override; useful when
- *      the private key is held in an HSM-style import that strips public bits).
- *   2. Derived from the private key via `exportJWK` (works because we now
- *      load the private key with `extractable: true`).
- *
- * `kid` is the explicit `CLAXEDO_RELAY_HOST_KID` env var if set, otherwise
- * SHA-256(public-key-x).slice(0, 16). Mint and JWKS use the same derivation
- * so they always agree.
- *
- * `next` is optional and is included in JWKS only — never used to mint. It
- * exists to support rolling rotation: publish the next key, drain the
- * current one, swap signing key, retire the old.
- *
- * Exported for tests.
- */
-export type LoadRelayHostKeyMaterialEnv = {
-    /**
-     * 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;
-    CLAXEDO_RELAY_HOST_PUBLIC_KEY_PEM?: string | undefined;
-    CLAXEDO_RELAY_HOST_NEXT_PUBLIC_KEY_PEM?: string | undefined;
-    CLAXEDO_RELAY_HOST_KID?: string | undefined;
-    CLAXEDO_RELAY_HOST_NEXT_KID?: string | undefined;
-};
-export type RelayHostKeyMaterial = {
-    privateKey: CryptoKey;
-    current: RelayHostPublicKey;
-    next?: RelayHostPublicKey;
-};
-export declare function loadRelayHostKeyMaterial(env: LoadRelayHostKeyMaterialEnv): Promise<RelayHostKeyMaterial>;
-/**
- * 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.
- */
-export type ParseAuditAcceptSampleRateEnv = {
-    CLAXEDO_RELAY_AUDIT_ACCEPT_SAMPLE_RATE?: string | undefined;
-    NODE_ENV?: string | undefined;
-};
-export declare function parseAuditAcceptSampleRate(env: ParseAuditAcceptSampleRateEnv): number;
-/**
- * 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.
- */
-export type ParseMetricsTokenEnv = {
-    CLAXEDO_RELAY_METRICS_TOKEN?: string | undefined;
-};
-export declare function parseMetricsToken(env: ParseMetricsTokenEnv): string | undefined;
-export type RuntimeAccessTokenCacheEnv = {
-    CLAXEDO_RELAY_RUNTIME_ACCESS_TOKEN_CACHE_TTL_MS?: string | undefined;
-};
-export declare function runtimeAccessTokenCacheTtlMsFromEnv(env: RuntimeAccessTokenCacheEnv): number;
-export type DirectHttpConcurrencyEnv = {
-    CLAXEDO_RELAY_DIRECT_HTTP_CONCURRENCY?: string | undefined;
-};
-export declare function directHttpConcurrencyFromEnv(env: DirectHttpConcurrencyEnv): number | undefined;
-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;
-};
-/**
- * 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
- *      machine from routing, and so new HTTP requests + tunnel registrations
- *      fast-path to 503 before doing any auth or upstream work.
- *   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 via `directory.dispose()` so
- *      the process can exit cleanly without a dangling `setInterval`.
- *   4. Exit with code 0.
- *
- * Exposed for tests so the trigger logic can be exercised without actually
- * raising signals or stopping the process. Pass `register: false` in tests
- * to skip the real `process.on(...)` registration.
- */
-export type ShutdownDrainHandlerOptions = {
-    drain: WorkspaceRelayBunDrainController;
-    directory: Pick<WorkspaceRelayDirectory, "dispose">;
-    drainTimeoutMs: number;
-    /** Defaults to `process.exit`. Override for tests. */
-    exit?: (code?: number) => void;
-    /** Defaults to a no-op log. */
-    log?: (message: string) => void;
-    /** When true (default), register `SIGTERM` and `SIGINT` handlers on `process`. */
-    register?: boolean;
-    /** Signals to listen for. Defaults to `["SIGTERM", "SIGINT"]`. */
-    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>;
-    isShuttingDown(): boolean;
-};
-export declare function installShutdownDrainHandler(options: ShutdownDrainHandlerOptions): ShutdownDrainHandle;
-export type FatalProcessHandlerOptions = {
-    drain: WorkspaceRelayBunDrainController;
-    directory: Pick<WorkspaceRelayDirectory, "dispose">;
-    exit?: (code?: number) => void;
-    log?: (message: string) => void;
-    register?: boolean;
-    /**
-     * 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>;
-    isFatal(): boolean;
-};
-export declare function installFatalProcessHandlers(options: FatalProcessHandlerOptions): FatalProcessHandle;