@telorun/k8s-runner 0.13.0 → 0.15.0

package/dist/k8s/routing/routing-mode.d.ts

@@ -0,0 +1,45 @@
+import type { K8sRunnerConfig } from "../../config.js";
+import type { KubeClient } from "../client.js";
+export type ResolvedRouting = {
+    layer: "none";
+    reason: string;
+} | {
+    layer: "ingress";
+} | {
+    layer: "gateway";
+    apiVersion: string;
+};
+export interface ClusterRoutingSupport {
+    /** Served Gateway API version, preferred first; undefined when the group is
+     *  not served at all. */
+    gatewayApiVersion?: string;
+    /** Number of IngressClasses, or **undefined when the list could not be read**.
+     *  `networking.k8s.io` is always served, so the API being present is no
+     *  evidence anyone can route with it — an installed controller registers a
+     *  class, and that is the usable signal. Zero and unknown are kept apart
+     *  because a refusal phrased from them is a different claim: one is about the
+     *  cluster, the other about this runner's permissions. */
+    ingressClassCount?: number;
+    /** Set when at least one IngressClass carries the default-class annotation. */
+    hasDefaultIngressClass: boolean;
+    /** Why the IngressClass list could not be read, when it could not. */
+    ingressClassError?: unknown;
+}
+/** What the cluster can actually route with. Both probes fail SOFT — discovery
+ *  and IngressClass listing are the runner's least important permissions — but a
+ *  failure is REPORTED rather than folded into a zero, so nothing downstream can
+ *  turn a permission error into a claim about the cluster. */
+export declare function detectRoutingSupport(kube: KubeClient): Promise<ClusterRoutingSupport>;
+/**
+ * Decide the routing layer ONCE, at boot, so a misconfiguration fails the runner
+ * instead of 404-ing every session it later accepts.
+ *
+ * `auto` resolves on what is CONFIGURED before what is INSTALLED, and that order
+ * is the whole point: Gateway API CRDs are frequently present without being the
+ * intended path, so "both APIs available" is not evidence of intent and must not
+ * decide anything. Only a cluster that offers two usable layers and was told
+ * nothing is genuinely ambiguous — and there the answer is to refuse, because
+ * guessing wrong publishes routes nothing reconciles, which is silent.
+ */
+export declare function resolveRouting(kube: KubeClient, config: K8sRunnerConfig): Promise<ResolvedRouting>;
+//# sourceMappingURL=routing-mode.d.ts.map

package/dist/k8s/routing/routing-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-mode.d.ts","sourceRoot":"","sources":["../../../src/k8s/routing/routing-mode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAQ/C,MAAM,MAAM,eAAe,GACvB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,KAAK,EAAE,SAAS,CAAA;CAAE,GACpB;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAM7C,MAAM,WAAW,qBAAqB;IACpC;6BACyB;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;8DAK0D;IAC1D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,+EAA+E;IAC/E,sBAAsB,EAAE,OAAO,CAAC;IAChC,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;8DAG8D;AAC9D,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAyB3F;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,eAAe,CAAC,CAmB1B"}

package/dist/k8s/routing/routing-mode.js

@@ -0,0 +1,141 @@
+import { RunnerConfigError } from "../../config.js";
+import { apiReason } from "../api-error.js";
+const GATEWAY_GROUP = "gateway.networking.k8s.io";
+/** Preference order among served Gateway API versions. `v1` is GA; plenty of
+ *  clusters still serve only `v1beta1`, and an HTTPRoute posted at a version the
+ *  apiserver does not serve is a 404 at publish time rather than a bad route. */
+const GATEWAY_VERSIONS = ["v1", "v1beta1"];
+/** The annotation by which a cluster nominates the class unqualified Ingresses
+ *  go to — which is exactly what this runner creates when no class is set. */
+const DEFAULT_CLASS_ANNOTATION = "ingressclass.kubernetes.io/is-default-class";
+/** What the cluster can actually route with. Both probes fail SOFT — discovery
+ *  and IngressClass listing are the runner's least important permissions — but a
+ *  failure is REPORTED rather than folded into a zero, so nothing downstream can
+ *  turn a permission error into a claim about the cluster. */
+export async function detectRoutingSupport(kube) {
+    let gatewayApiVersion;
+    try {
+        const groups = await kube.apis.getAPIVersions();
+        const group = groups.groups?.find((g) => g.name === GATEWAY_GROUP);
+        const served = new Set((group?.versions ?? []).map((v) => v.version));
+        gatewayApiVersion =
+            GATEWAY_VERSIONS.find((v) => served.has(v)) ?? group?.preferredVersion?.version;
+    }
+    catch {
+        gatewayApiVersion = undefined;
+    }
+    try {
+        const classes = await kube.networking.listIngressClass();
+        const items = classes.items ?? [];
+        return {
+            gatewayApiVersion,
+            ingressClassCount: items.length,
+            hasDefaultIngressClass: items.some((c) => c.metadata?.annotations?.[DEFAULT_CLASS_ANNOTATION] === "true"),
+        };
+    }
+    catch (err) {
+        return { gatewayApiVersion, hasDefaultIngressClass: false, ingressClassError: err };
+    }
+}
+/**
+ * Decide the routing layer ONCE, at boot, so a misconfiguration fails the runner
+ * instead of 404-ing every session it later accepts.
+ *
+ * `auto` resolves on what is CONFIGURED before what is INSTALLED, and that order
+ * is the whole point: Gateway API CRDs are frequently present without being the
+ * intended path, so "both APIs available" is not evidence of intent and must not
+ * decide anything. Only a cluster that offers two usable layers and was told
+ * nothing is genuinely ambiguous — and there the answer is to refuse, because
+ * guessing wrong publishes routes nothing reconciles, which is silent.
+ */
+export async function resolveRouting(kube, config) {
+    const routing = config.sessionRouting;
+    if (routing.mode === "none") {
+        return { layer: "none", reason: "SESSION_ROUTING_MODE=none" };
+    }
+    // The base domain is what makes a host constructible at all, so it stays the
+    // master switch it has always been — no domain, no routing, whatever the mode.
+    if (!routing.baseDomain) {
+        return {
+            layer: "none",
+            reason: "SESSION_ROUTING_BASE_DOMAIN is unset, so no session host can be constructed",
+        };
+    }
+    const support = await detectRoutingSupport(kube);
+    const resolved = decideLayer(config, support);
+    assertTlsMatchesLayer(config, resolved);
+    return resolved;
+}
+/** The origin certificate is refused HERE as well as at config load, because
+ *  under `auto` the effective layer is not known until now: a named Gateway wins,
+ *  so `mode: auto` + a Gateway + `SESSION_INGRESS_TLS_SECRET` passed the
+ *  config-time check and then routed on Gateway API with the certificate
+ *  ignored — plaintext origin traffic under a configuration that reads as
+ *  TLS-configured, which is the silent downgrade the check exists to prevent. */
+function assertTlsMatchesLayer(config, resolved) {
+    if (resolved.layer !== "gateway" || !config.sessionRouting.tlsSecretName)
+        return;
+    throw new RunnerConfigError("SESSION_INGRESS_TLS_SECRET is set but session routing resolved to Gateway API. Under Gateway " +
+        "API the origin certificate belongs to the Gateway listener's own `tls.certificateRefs`, not " +
+        "to the per-session route, so this Secret would be silently ignored. Move the reference to " +
+        "the Gateway and unset this, or set SESSION_ROUTING_MODE=ingress.");
+}
+function decideLayer(config, support) {
+    const routing = config.sessionRouting;
+    if (routing.mode === "ingress")
+        return { layer: "ingress" };
+    if (routing.mode === "gateway") {
+        if (!support.gatewayApiVersion) {
+            throw new RunnerConfigError(`SESSION_ROUTING_MODE=gateway but the cluster does not serve '${GATEWAY_GROUP}'. ` +
+                "Install the Gateway API CRDs, or set SESSION_ROUTING_MODE=ingress.");
+        }
+        return { layer: "gateway", apiVersion: support.gatewayApiVersion };
+    }
+    // auto — configured target first.
+    if (routing.gateway) {
+        if (!support.gatewayApiVersion) {
+            throw new RunnerConfigError(`SESSION_GATEWAY_NAME is set but the cluster does not serve '${GATEWAY_GROUP}'. ` +
+                "Install the Gateway API CRDs, or unset SESSION_GATEWAY_NAME to route via Ingress.");
+        }
+        return { layer: "gateway", apiVersion: support.gatewayApiVersion };
+    }
+    if (routing.ingressClassName)
+        return { layer: "ingress" };
+    // A DEFAULT-marked IngressClass is configuration, not mere availability: the
+    // cluster has nominated where an unqualified Ingress goes, and unqualified is
+    // exactly what this runner creates. It therefore ranks with a named Gateway
+    // and a configured class rather than with "an IngressClass exists" — without
+    // which every cluster that ships the Gateway CRDs beside a default ingress
+    // controller would refuse to boot after this upgrade, having worked before.
+    if (support.hasDefaultIngressClass)
+        return { layer: "ingress" };
+    const gatewayUsable = Boolean(support.gatewayApiVersion);
+    const ingressUsable = (support.ingressClassCount ?? 0) > 0;
+    if (gatewayUsable && ingressUsable) {
+        throw new RunnerConfigError(`SESSION_ROUTING_MODE=auto cannot choose: this cluster serves '${GATEWAY_GROUP}' AND has ` +
+            `${support.ingressClassCount} IngressClass(es) with none marked default, and nothing says ` +
+            "which should carry session traffic. Set SESSION_ROUTING_MODE=ingress (with " +
+            "SESSION_INGRESS_CLASS) or SESSION_ROUTING_MODE=gateway (with SESSION_GATEWAY_NAME).");
+    }
+    if (gatewayUsable) {
+        throw new RunnerConfigError(`SESSION_ROUTING_MODE=auto resolved to Gateway API, but SESSION_GATEWAY_NAME is unset — a ` +
+            "route has to name the Gateway it attaches to, and picking one of several would fail as " +
+            "silently as publishing none. Set SESSION_GATEWAY_NAME (and SESSION_GATEWAY_NAMESPACE " +
+            `when the Gateway is not in '${config.sessionNamespace}').`);
+    }
+    if (ingressUsable)
+        return { layer: "ingress" };
+    // Say which of the two it is. Reporting a permission failure as "no
+    // IngressClass exists" is a claim about the cluster drawn from a fact about
+    // this runner's access, and it sends an operator to install a controller they
+    // already have.
+    if (support.ingressClassError !== undefined) {
+        throw new RunnerConfigError("SESSION_ROUTING_BASE_DOMAIN is set but the routing layer could not be resolved: listing " +
+            `IngressClasses failed (${apiReason(support.ingressClassError)}) and '${GATEWAY_GROUP}' is ` +
+            "not served. Grant `list` on `ingressclasses`, or set SESSION_ROUTING_MODE explicitly.");
+    }
+    throw new RunnerConfigError("SESSION_ROUTING_BASE_DOMAIN is set but this cluster offers no usable routing layer: no " +
+        `IngressClass exists and '${GATEWAY_GROUP}' is not served. Install an Ingress controller or ` +
+        "the Gateway API, or set SESSION_ROUTING_MODE=none to run logs-only.");
+}
+//# sourceMappingURL=routing-mode.js.map

package/dist/k8s/routing/routing-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-mode.js","sourceRoot":"","sources":["../../../src/k8s/routing/routing-mode.ts"],"names":[],"mappings":"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"}

package/dist/k8s/routing/session-endpoints.d.ts

@@ -0,0 +1,25 @@
+import type { PortMapping, RunnerEndpoint } from "@telorun/runner-core";
+import type { K8sRunnerConfig } from "../../config.js";
+/** Host fronting a single tcp port: `<port>-<sessionId>.<domain>`. The port rides
+ *  as a leading label (no dots), so it stays a single label under the base domain
+ *  — matching the docker runner's proxy scheme and compatible with a single-label
+ *  wildcard cert (`*.<domain>`).
+ *
+ *  Shared by both routing layers on purpose: the host scheme is what a client is
+ *  told and what DNS is configured for, so it must not vary with the cluster's
+ *  choice of Ingress or Gateway API. */
+export declare function hostForPort(config: K8sRunnerConfig, sessionId: string, port: number): string;
+/**
+ * Endpoints announced on the `running` status. Every tcp port is fronted by its
+ * own per-session host (served on 443) and carries an external `url`. udp ports
+ * aren't HTTP-routable, so they keep the host-less form. Without a base domain,
+ * host is left blank for the client adapter to fill (parity with docker).
+ *
+ * `routed` is what says a URL will be served, and it is separate from the base
+ * domain because the two can disagree: `SESSION_ROUTING_MODE=none` with a domain
+ * configured is a valid, documented setup that publishes nothing. Keying on the
+ * domain alone handed the editor a URL nothing serves — and the route watch
+ * never runs in that mode, so no `route` event would have said so either.
+ */
+export declare function endpointsFor(config: K8sRunnerConfig, sessionId: string, ports: PortMapping[], routed: boolean): RunnerEndpoint[];
+//# sourceMappingURL=session-endpoints.d.ts.map

package/dist/k8s/routing/session-endpoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-endpoints.d.ts","sourceRoot":"","sources":["../../../src/k8s/routing/session-endpoints.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAExE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD;;;;;;;wCAOwC;AACxC,wBAAgB,WAAW,CAAC,MAAM,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,eAAe,EACvB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,WAAW,EAAE,EACpB,MAAM,EAAE,OAAO,GACd,cAAc,EAAE,CAWlB"}

package/dist/k8s/routing/session-endpoints.js

@@ -0,0 +1,36 @@
+/** Host fronting a single tcp port: `<port>-<sessionId>.<domain>`. The port rides
+ *  as a leading label (no dots), so it stays a single label under the base domain
+ *  — matching the docker runner's proxy scheme and compatible with a single-label
+ *  wildcard cert (`*.<domain>`).
+ *
+ *  Shared by both routing layers on purpose: the host scheme is what a client is
+ *  told and what DNS is configured for, so it must not vary with the cluster's
+ *  choice of Ingress or Gateway API. */
+export function hostForPort(config, sessionId, port) {
+    return `${port}-${sessionId}.${config.sessionRouting.baseDomain}`;
+}
+/**
+ * Endpoints announced on the `running` status. Every tcp port is fronted by its
+ * own per-session host (served on 443) and carries an external `url`. udp ports
+ * aren't HTTP-routable, so they keep the host-less form. Without a base domain,
+ * host is left blank for the client adapter to fill (parity with docker).
+ *
+ * `routed` is what says a URL will be served, and it is separate from the base
+ * domain because the two can disagree: `SESSION_ROUTING_MODE=none` with a domain
+ * configured is a valid, documented setup that publishes nothing. Keying on the
+ * domain alone handed the editor a URL nothing serves — and the route watch
+ * never runs in that mode, so no `route` event would have said so either.
+ */
+export function endpointsFor(config, sessionId, ports, routed) {
+    if (!routed || !config.sessionRouting.baseDomain || ports.length === 0) {
+        return ports.map((p) => ({ host: "", port: p.port, protocol: p.protocol }));
+    }
+    return ports.map((p) => {
+        if (p.protocol !== "tcp") {
+            return { host: "", port: p.port, protocol: p.protocol };
+        }
+        const host = hostForPort(config, sessionId, p.port);
+        return { host, port: p.port, protocol: p.protocol, url: `https://${host}` };
+    });
+}
+//# sourceMappingURL=session-endpoints.js.map

package/dist/k8s/routing/session-endpoints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-endpoints.js","sourceRoot":"","sources":["../../../src/k8s/routing/session-endpoints.ts"],"names":[],"mappings":"AAIA;;;;;;;wCAOwC;AACxC,MAAM,UAAU,WAAW,CAAC,MAAuB,EAAE,SAAiB,EAAE,IAAY;IAClF,OAAO,GAAG,IAAI,IAAI,SAAS,IAAI,MAAM,CAAC,cAAc,CAAC,UAAU,EAAE,CAAC;AACpE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAC1B,MAAuB,EACvB,SAAiB,EACjB,KAAoB,EACpB,MAAe;IAEf,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,UAAU,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACrB,IAAI,CAAC,CAAC,QAAQ,KAAK,KAAK,EAAE,CAAC;YACzB,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC;QAC1D,CAAC;QACD,MAAM,IAAI,GAAG,WAAW,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QACpD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,GAAG,EAAE,WAAW,IAAI,EAAE,EAAE,CAAC;IAC9E,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/k8s/routing/session-router.d.ts

@@ -0,0 +1,57 @@
+import type { PortMapping } from "@telorun/runner-core";
+/** One published host and the session port behind it. */
+export interface PublishedRoute {
+    host: string;
+    port: number;
+}
+export interface PublishRouteArgs {
+    sessionId: string;
+    /** The Service the routing object points at. */
+    serviceName: string;
+    /** Owner of every object created — see `podOwnerRef`. */
+    podName: string;
+    podUid: string;
+    /** Every port the session must carry. Non-tcp ports are ignored: they are not
+     *  HTTP-routable, and the Service still exposes them. */
+    ports: PortMapping[];
+}
+/**
+ * What a routing layer has to say about one published host.
+ *
+ * `pending` is a real answer, not an absence: a controller that has not yet
+ * written status is indistinguishable from one that will never claim the route,
+ * and only time separates them.
+ */
+export type RouteVerdict = {
+    kind: "programmed";
+} | {
+    kind: "pending";
+} | {
+    kind: "rejected";
+    reason: string;
+};
+/**
+ * How this cluster publishes a session's public routes.
+ *
+ * The seam exists because Ingress and Gateway API are both current: neither is a
+ * migration target for the other, clusters ship one, the other, or both, and a
+ * runner that hardcodes either is unroutable on half of them. It deliberately
+ * stays inside the k8s backend — docker publishes host ports through its own
+ * proxy and has no use for it, and `runner-core` owns the backend-neutral `/v1`
+ * contract, where "Ingress or HTTPRoute" is not a distinction that exists.
+ */
+export interface SessionRouter {
+    /** Names the layer for diagnostics. */
+    readonly layer: "ingress" | "gateway";
+    /** Create-or-replace this session's routing objects. Returns the hosts it
+     *  published, which is what the route watch then asks about. */
+    publish(args: PublishRouteArgs): Promise<PublishedRoute[]>;
+    /** This layer's current verdict on one published host. Asked repeatedly by the
+     *  route watch until it settles or the deadline passes. */
+    verdictFor(sessionId: string, route: PublishedRoute): Promise<RouteVerdict>;
+    /** What to tell an operator when a route is still `pending` at the deadline.
+     *  Layer-specific because the causes are: no controller for the IngressClass,
+     *  versus a Gateway that never claimed the route. */
+    unclaimedReason(): string;
+}
+//# sourceMappingURL=session-router.d.ts.map

package/dist/k8s/routing/session-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-router.d.ts","sourceRoot":"","sources":["../../../src/k8s/routing/session-router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf;6DACyD;IACzD,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GACtB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAAC;IAEtC;oEACgE;IAChE,OAAO,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAE3D;+DAC2D;IAC3D,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAE5E;;yDAEqD;IACrD,eAAe,IAAI,MAAM,CAAC;CAC3B"}

package/dist/k8s/routing/session-router.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=session-router.js.map

package/dist/k8s/routing/session-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-router.js","sourceRoot":"","sources":["../../../src/k8s/routing/session-router.ts"],"names":[],"mappings":""}

package/dist/k8s/routing/session-service.d.ts

@@ -0,0 +1,14 @@
+import type { V1OwnerReference, V1Service } from "@kubernetes/client-node";
+import type { PortMapping } from "@telorun/runner-core";
+import type { K8sRunnerConfig } from "../../config.js";
+/** OwnerReference to the session Pod so every routing object is garbage collected
+ *  when the Pod dies — essential for sub-minute sessions that would otherwise leak
+ *  routing objects. Both routing layers use it: an HTTPRoute is namespaced like an
+ *  Ingress, so the same ownership works unchanged. */
+export declare function podOwnerRef(podName: string, podUid: string): V1OwnerReference;
+/** The name every routing object for one session shares. */
+export declare function sessionObjectName(sessionId: string): string;
+/** The Service both routing layers point at — the routing layer decides how
+ *  traffic ARRIVES, never what it arrives at, so this is layer-neutral. */
+export declare function buildSessionService(config: K8sRunnerConfig, sessionId: string, podName: string, podUid: string, ports: PortMapping[]): V1Service;
+//# sourceMappingURL=session-service.d.ts.map

package/dist/k8s/routing/session-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-service.d.ts","sourceRoot":"","sources":["../../../src/k8s/routing/session-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAE3E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD;;;sDAGsD;AACtD,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAS7E;AAED,4DAA4D;AAC5D,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;2EAC2E;AAC3E,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,eAAe,EACvB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,WAAW,EAAE,GACnB,SAAS,CAoBX"}

package/dist/k8s/routing/session-service.js

@@ -0,0 +1,42 @@
+/** OwnerReference to the session Pod so every routing object is garbage collected
+ *  when the Pod dies — essential for sub-minute sessions that would otherwise leak
+ *  routing objects. Both routing layers use it: an HTTPRoute is namespaced like an
+ *  Ingress, so the same ownership works unchanged. */
+export function podOwnerRef(podName, podUid) {
+    return {
+        apiVersion: "v1",
+        kind: "Pod",
+        name: podName,
+        uid: podUid,
+        controller: true,
+        blockOwnerDeletion: true,
+    };
+}
+/** The name every routing object for one session shares. */
+export function sessionObjectName(sessionId) {
+    return `telo-run-${sessionId}`;
+}
+/** The Service both routing layers point at — the routing layer decides how
+ *  traffic ARRIVES, never what it arrives at, so this is layer-neutral. */
+export function buildSessionService(config, sessionId, podName, podUid, ports) {
+    return {
+        apiVersion: "v1",
+        kind: "Service",
+        metadata: {
+            name: sessionObjectName(sessionId),
+            namespace: config.sessionNamespace,
+            labels: { "app.kubernetes.io/managed-by": config.managedByLabel },
+            ownerReferences: [podOwnerRef(podName, podUid)],
+        },
+        spec: {
+            selector: { "telo.run/session-id": sessionId },
+            ports: ports.map((p) => ({
+                name: `p${p.port}`,
+                port: p.port,
+                targetPort: p.port,
+                protocol: p.protocol.toUpperCase(),
+            })),
+        },
+    };
+}
+//# sourceMappingURL=session-service.js.map

package/dist/k8s/routing/session-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-service.js","sourceRoot":"","sources":["../../../src/k8s/routing/session-service.ts"],"names":[],"mappings":"AAMA;;;sDAGsD;AACtD,MAAM,UAAU,WAAW,CAAC,OAAe,EAAE,MAAc;IACzD,OAAO;QACL,UAAU,EAAE,IAAI;QAChB,IAAI,EAAE,KAAK;QACX,IAAI,EAAE,OAAO;QACb,GAAG,EAAE,MAAM;QACX,UAAU,EAAE,IAAI;QAChB,kBAAkB,EAAE,IAAI;KACzB,CAAC;AACJ,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,iBAAiB,CAAC,SAAiB;IACjD,OAAO,YAAY,SAAS,EAAE,CAAC;AACjC,CAAC;AAED;2EAC2E;AAC3E,MAAM,UAAU,mBAAmB,CACjC,MAAuB,EACvB,SAAiB,EACjB,OAAe,EACf,MAAc,EACd,KAAoB;IAEpB,OAAO;QACL,UAAU,EAAE,IAAI;QAChB,IAAI,EAAE,SAAS;QACf,QAAQ,EAAE;YACR,IAAI,EAAE,iBAAiB,CAAC,SAAS,CAAC;YAClC,SAAS,EAAE,MAAM,CAAC,gBAAgB;YAClC,MAAM,EAAE,EAAE,8BAA8B,EAAE,MAAM,CAAC,cAAc,EAAE;YACjE,eAAe,EAAE,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;SAChD;QACD,IAAI,EAAE;YACJ,QAAQ,EAAE,EAAE,qBAAqB,EAAE,SAAS,EAAE;YAC9C,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBACvB,IAAI,EAAE,IAAI,CAAC,CAAC,IAAI,EAAE;gBAClB,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,UAAU,EAAE,CAAC,CAAC,IAAI;gBAClB,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE;aACnC,CAAC,CAAC;SACJ;KACF,CAAC;AACJ,CAAC"}

package/dist/k8s/watch-session.d.ts

@@ -1,19 +1,21 @@
 import type { BackendSession, BackendStartSpec } from "@telorun/runner-core";
 import type { K8sRunnerConfig } from "../config.js";
 import type { KubeClient } from "./client.js";
+import { type SessionRouter } from "./routing/index.js";
 export interface WatchSessionDeps {
     kube: KubeClient;
     config: K8sRunnerConfig;
+    /** Resolved at boot; absent → logs-only. */
+    router?: SessionRouter;
 }
 /**
  * A watch session: one pod, one workspace volume, one container per running
  * application, and the session outliving every run inside it.
  *
- * What it does NOT do is as load-bearing as what it does: it never builds an
- * image. The build path exists to put a dependency closure on disk before boot;
- * a watch session resolves its own into a per-app cache directory that lives as
- * long as the pod, so the download happens once per app per session and every
- * later reload resolves from local disk.
+ * Its cache is what separates it from a run session: the module closure lands in
+ * a directory that lives as long as the POD rather than as long as one run, so
+ * the download happens once per session and every later reload resolves from
+ * local disk.
  */
 export declare function startWatchSession(deps: WatchSessionDeps, spec: BackendStartSpec): Promise<BackendSession>;
 //# sourceMappingURL=watch-session.d.ts.map

package/dist/k8s/watch-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"watch-session.d.ts","sourceRoot":"","sources":["../../src/k8s/watch-session.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAEV,cAAc,EACd,gBAAgB,EAMjB,MAAM,sBAAsB,CAAC;AAW9B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAsB9C,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,eAAe,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,gBAAgB,EACtB,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,cAAc,CAAC,CA6kBzB"}
+{"version":3,"file":"watch-session.d.ts","sourceRoot":"","sources":["../../src/k8s/watch-session.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAEV,cAAc,EACd,gBAAgB,EAMjB,MAAM,sBAAsB,CAAC;AAW9B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAGpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAOL,KAAK,aAAa,EACnB,MAAM,oBAAoB,CAAC;AAqB5B,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,eAAe,CAAC;IACxB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,gBAAgB,EACtB,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,cAAc,CAAC,CAqlBzB"}