@spine-event-engine/deployment-gke 2.0.0-snapshot.11

package/dist/discovery/gke-log.js

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+/**
+ * Records a contained GKE discovery warning without changing discovery outcomes.
+ *
+ * @param logger Receives the contained record when supplied.
+ */
+export const gkeDiscoveryLog = Object.freeze({
+    warn(logger) {
+        if (logger === undefined)
+            return;
+        try {
+            const record = logger.withMetadata({
+                operation: "deployment.gke.discovery.refresh",
+                reasonCode: "failed",
+            });
+            const emit = record.warn.bind(record);
+            const emitted = emit("deployment.gke.discovery.refresh_failed");
+            if (gkeDiscoveryLog.isPromiseLike(emitted))
+                void Promise.resolve(emitted).catch(() => undefined);
+        }
+        catch {
+            // Logging must not affect the containing runtime outcome.
+        }
+    },
+    isPromiseLike(value) {
+        return ((typeof value === "object" || typeof value === "function") &&
+            value !== null &&
+            "then" in value &&
+            typeof value.then === "function");
+    },
+});
+//# sourceMappingURL=gke-log.js.map

package/dist/discovery/gke-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gke-log.js","sourceRoot":"","sources":["../../src/discovery/gke-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAGvB,MAAM,CAAC,MAAM,CAAC;IACjB,IAAI,CAAC,MAA6B;QAChC,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO;QACjC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC;gBACjC,SAAS,EAAE,kCAAkC;gBAC7C,UAAU,EAAE,QAAQ;aACrB,CAAC,CAAC;YACH,MAAM,IAAI,GAA+B,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAClE,MAAM,OAAO,GAAG,IAAI,CAAC,yCAAyC,CAAC,CAAC;YAChE,IAAI,eAAe,CAAC,aAAa,CAAC,OAAO,CAAC;gBACxC,KAAK,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QACzD,CAAC;QAAC,MAAM,CAAC;YACP,0DAA0D;QAC5D,CAAC;IACH,CAAC;IAED,aAAa,CAAC,KAAc;QAC1B,OAAO,CACL,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,UAAU,CAAC;YAC1D,KAAK,KAAK,IAAI;YACd,MAAM,IAAI,KAAK;YACf,OAAQ,KAA4B,CAAC,IAAI,KAAK,UAAU,CACzD,CAAC;IACJ,CAAC;CACF,CAAC,CAAC"}

package/dist/discovery/gke-node-discovery.d.ts

@@ -0,0 +1,104 @@
+import { ApplicationNode, type NodeDiscovery, type NodeScheduler } from "@spine-event-engine/deployment";
+import type { ILogLayer } from "loglayer";
+/**
+ * Represents one DNS address with its optional answer TTL in seconds.
+ */
+export interface GkeDnsAddress {
+    /**
+     *
+     * Provides one ready-Pod IPv4 or IPv6 address.
+     */
+    readonly address: string;
+    /**
+     *
+     * Provides the record lifetime in seconds when DNS includes it.
+     */
+    readonly ttl?: number;
+}
+/**
+ * Resolves the complete ready-Pod address set for one headless Service.
+ */
+export interface GkeDnsResolver {
+    /**
+     * Resolves the current answer and cooperates with cancellation.
+     *
+     * @param serviceName Supplies the configured headless-Service DNS name.
+     * @param signal Cancels the pending DNS request.
+     * @returns The complete address answer or an empty answer for name-not-found.
+     */
+    resolve(serviceName: string, signal: AbortSignal): Promise<readonly GkeDnsAddress[]>;
+}
+/**
+ * Configures GKE headless-Service discovery for one standalone Gateway.
+ */
+export interface GkeNodeDiscoveryOptions {
+    /**
+     *
+     * Identifies the headless-Service DNS name.
+     */
+    readonly serviceName: string;
+    /**
+     *
+     * Identifies the reachable application TCP port.
+     */
+    readonly port: number;
+    /**
+     *
+     * Selects the HTTP transport scheme.
+     */
+    readonly scheme?: "http" | "https";
+    /**
+     *
+     * Sets the maximum interval between DNS lookups in milliseconds.
+     */
+    readonly refreshIntervalMs?: number;
+    /**
+     *
+     * Supplies the DNS lookup adapter.
+     */
+    readonly resolver?: GkeDnsResolver;
+    /**
+     *
+     * Schedules future DNS lookups.
+     */
+    readonly scheduler?: NodeScheduler;
+    /**
+     *
+     * Returns the current time for TTL validity.
+     *
+     * @returns The current Unix time in milliseconds.
+     */
+    readonly now?: () => number;
+    /**
+     * Application-owned logger reserved for component-local records. The component
+     * does not retain or close the supplied logger.
+     */
+    readonly logger?: ILogLayer;
+}
+/**
+ * Publishes ready GKE Pods from a headless-Service DNS answer.
+ */
+export declare class GkeNodeDiscovery implements NodeDiscovery {
+    #private;
+    /**
+     * Creates discovery with a ten-second refresh interval by default.
+     *
+     * @param options Supplies the Service name, reachable port, and optional runtime seams.
+     */
+    constructor(options: GkeNodeDiscoveryOptions);
+    /**
+     * Starts the only complete membership watch.
+     *
+     * @param onSnapshot Receives every successful or expired membership snapshot.
+     * @returns Stops future refreshes and joins the active DNS request.
+     */
+    watch(onSnapshot: (nodes: readonly ApplicationNode[]) => void): () => Promise<void>;
+    /**
+     * Cancels scheduled and in-flight DNS work permanently.
+     *
+     * @returns Completes after the admitted resolver request settles.
+     */
+    close(): Promise<void>;
+}
+export { NodeDnsResolver, type DnsLookup } from "./node-dns-resolver.js";
+//# sourceMappingURL=gke-node-discovery.d.ts.map

package/dist/discovery/gke-node-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gke-node-discovery.d.ts","sourceRoot":"","sources":["../../src/discovery/gke-node-discovery.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,eAAe,EACf,KAAK,aAAa,EAClB,KAAK,aAAa,EACnB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAK1C;;GAEG;AACH,MAAM,WAAW,aAAa;IAG5B;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAG7B;;;;;;OAMG;IACH,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAAC;CACtF;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IAGtC;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAEnC;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAEpC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IAEnC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;IAEnC;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAE5B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;CAC7B;AAcD;;GAEG;AACH,qBAAa,gBAAiB,YAAW,aAAa;;IAqBpD;;;;OAIG;gBACS,OAAO,EAAE,uBAAuB;IAmB5C;;;;;OAKG;IACH,KAAK,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,KAAK,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;IASnF;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CA0GvB;AAED,OAAO,EAAE,eAAe,EAAE,KAAK,SAAS,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/discovery/gke-node-discovery.js

@@ -0,0 +1,198 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { ApplicationNode, } from "@spine-event-engine/deployment";
+import { NodeDnsResolver } from "./node-dns-resolver.js";
+import { gkeDiscoveryLog } from "./gke-log.js";
+const systemScheduler = {
+    schedule(delayMs, onTick) {
+        const timer = setTimeout(onTick, delayMs);
+        timer.unref();
+        return () => {
+            clearTimeout(timer);
+        };
+    },
+};
+const maximumRefreshes = 2;
+/**
+ * Publishes ready GKE Pods from a headless-Service DNS answer.
+ */
+export class GkeNodeDiscovery {
+    #serviceName;
+    #port;
+    #scheme;
+    #refreshIntervalMs;
+    #resolver;
+    #scheduler;
+    #now;
+    #logger;
+    #cancel;
+    #expiryCancel;
+    #controllers = new Set();
+    #watcher;
+    #refreshes = new Set();
+    #validUntilMs;
+    #expired = false;
+    #empty = false;
+    #closed = false;
+    #closing;
+    #epoch = 0;
+    /**
+     * Creates discovery with a ten-second refresh interval by default.
+     *
+     * @param options Supplies the Service name, reachable port, and optional runtime seams.
+     */
+    constructor(options) {
+        if (!ApplicationNode.tls(options.serviceName))
+            throw new Error("GKE Service name is invalid.");
+        if (!Number.isSafeInteger(options.port) || options.port < 1 || options.port > 65_535)
+            throw new RangeError("GKE node port must be a valid TCP port.");
+        if (options.refreshIntervalMs !== undefined &&
+            (!Number.isSafeInteger(options.refreshIntervalMs) || options.refreshIntervalMs < 1))
+            throw new RangeError("GKE refresh interval must be a positive safe integer.");
+        this.#serviceName = ApplicationNode.tls(options.serviceName);
+        this.#port = options.port;
+        this.#scheme = options.scheme ?? "http";
+        this.#refreshIntervalMs = options.refreshIntervalMs ?? 10_000;
+        this.#resolver = options.resolver ?? new NodeDnsResolver();
+        this.#scheduler = options.scheduler ?? systemScheduler;
+        this.#now = options.now ?? Date.now;
+        this.#logger = options.logger;
+    }
+    /**
+     * Starts the only complete membership watch.
+     *
+     * @param onSnapshot Receives every successful or expired membership snapshot.
+     * @returns Stops future refreshes and joins the active DNS request.
+     */
+    watch(onSnapshot) {
+        if (this.#closed)
+            throw new Error("GKE node discovery is closed.");
+        if (this.#watcher !== undefined)
+            throw new Error("GKE node discovery supports one active watch.");
+        this.#watcher = onSnapshot;
+        this.#schedule(0);
+        return () => this.close();
+    }
+    /**
+     * Cancels scheduled and in-flight DNS work permanently.
+     *
+     * @returns Completes after the admitted resolver request settles.
+     */
+    close() {
+        if (this.#closing !== undefined)
+            return this.#closing;
+        this.#closing = this.#close();
+        return this.#closing;
+    }
+    async #close() {
+        this.#closed = true;
+        this.#cancel?.();
+        this.#expiryCancel?.();
+        for (const controller of this.#controllers)
+            controller.abort();
+        this.#watcher = undefined;
+        await Promise.allSettled([...this.#refreshes]);
+    }
+    #schedule(delayMs) {
+        this.#cancel?.();
+        this.#cancel = this.#scheduler.schedule(delayMs, () => {
+            this.#cancel = undefined;
+            if (this.#expired)
+                this.#schedule(this.#refreshIntervalMs);
+            if (this.#controllers.size >= maximumRefreshes)
+                return;
+            const refresh = this.#refresh(++this.#epoch);
+            this.#refreshes.add(refresh);
+            // spine-log-boundary: deployment_gke.discovery_refresh_tail
+            void refresh.catch(() => undefined).finally(() => this.#refreshes.delete(refresh));
+        });
+    }
+    #scheduleExpiry(delayMs) {
+        this.#expiryCancel?.();
+        this.#expiryCancel = this.#scheduler.schedule(delayMs, () => {
+            if (!this.#closed &&
+                this.#validUntilMs !== undefined &&
+                this.#now() >= this.#validUntilMs &&
+                !this.#empty) {
+                this.#watcher?.([]);
+                this.#expired = true;
+                this.#empty = true;
+                this.#schedule(this.#refreshIntervalMs);
+            }
+        });
+    }
+    async #refresh(epoch) {
+        if (this.#closed)
+            return;
+        const controller = new AbortController();
+        this.#controllers.add(controller);
+        try {
+            const answer = await this.#resolver.resolve(this.#serviceName, controller.signal);
+            if (controller.signal.aborted || epoch !== this.#epoch)
+                return;
+            const nodes = this.#nodes(answer);
+            this.#watcher?.(nodes);
+            this.#expired = false;
+            this.#empty = nodes.length === 0;
+            this.#expiryCancel?.();
+            this.#expiryCancel = undefined;
+            const ttlMs = this.#ttlMs(answer);
+            this.#validUntilMs = this.#now() + ttlMs;
+            this.#schedule(nodes.length === 0 ? this.#refreshIntervalMs : Math.min(this.#refreshIntervalMs, ttlMs));
+            if (nodes.length > 0)
+                this.#scheduleExpiry(ttlMs);
+        }
+        catch {
+            if (controller.signal.aborted || epoch !== this.#epoch)
+                return;
+            // spine-log-boundary: deployment_gke.discovery_refresh
+            gkeDiscoveryLog.warn(this.#logger);
+            if (this.#validUntilMs !== undefined &&
+                this.#now() >= this.#validUntilMs &&
+                !this.#expired &&
+                !this.#empty) {
+                this.#watcher?.([]);
+                this.#expired = true;
+                this.#empty = true;
+            }
+            this.#schedule(this.#refreshIntervalMs);
+        }
+        finally {
+            this.#controllers.delete(controller);
+        }
+    }
+    #ttlMs(answer) {
+        const positive = answer
+            .map((entry) => entry.ttl)
+            .filter((ttl) => ttl !== undefined && Number.isFinite(ttl) && ttl > 0);
+        return positive.length === 0 ? this.#refreshIntervalMs : Math.min(...positive) * 1000;
+    }
+    #nodes(answer) {
+        const nodes = new Map();
+        for (const entry of answer) {
+            const host = entry.address.includes(":") ? `[${entry.address}]` : entry.address;
+            const endpoint = `${this.#scheme}://${host}:${this.#port.toString()}`;
+            const canonical = new ApplicationNode({ id: "gke", endpoint }).endpoint;
+            const node = new ApplicationNode({
+                id: `gke/${canonical}/${this.#scheme === "https" ? this.#serviceName : ""}`,
+                endpoint: canonical,
+                ...(this.#scheme === "https" ? { tlsServerName: this.#serviceName } : {}),
+            });
+            nodes.set(node.id, node);
+        }
+        return [...nodes.values()];
+    }
+}
+export { NodeDnsResolver } from "./node-dns-resolver.js";
+//# sourceMappingURL=gke-node-discovery.js.map

package/dist/discovery/gke-node-discovery.js.map

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

package/dist/discovery/node-dns-resolver.d.ts

@@ -0,0 +1,58 @@
+import type { GkeDnsAddress, GkeDnsResolver } from "./gke-node-discovery.js";
+/**
+ * Supplies cancellable TTL-aware Node DNS address-family lookups.
+ */
+export interface DnsLookup {
+    /**
+     * Resolves TTL-aware IPv4 records.
+     *
+     * @param name Supplies the DNS name.
+     * @param options Requests TTL metadata.
+     * @returns The current IPv4 records.
+     */
+    resolve4(name: string, options: {
+        readonly ttl: true;
+    }): Promise<readonly {
+        readonly address: string;
+        readonly ttl: number;
+    }[]>;
+    /**
+     * Resolves TTL-aware IPv6 records.
+     *
+     * @param name Supplies the DNS name.
+     * @param options Requests TTL metadata.
+     * @returns The current IPv6 records.
+     */
+    resolve6(name: string, options: {
+        readonly ttl: true;
+    }): Promise<readonly {
+        readonly address: string;
+        readonly ttl: number;
+    }[]>;
+    /**
+     * Cancels every active lookup.
+     */
+    cancel(): void;
+}
+/**
+ * Resolves IPv4 and IPv6 headless-Service records through Node DNS.
+ */
+export declare class NodeDnsResolver implements GkeDnsResolver {
+    #private;
+    /**
+     * Creates the Node DNS adapter.
+     *
+     * @param create Supplies a resolver factory for deterministic integration tests.
+     */
+    constructor(create?: () => DnsLookup);
+    /**
+     * Resolves both address families and exposes DNS TTLs when Node supplies them.
+     *
+     * @param serviceName Supplies the headless-Service DNS name.
+     * @param signal Cancels the resolver request.
+     * @returns All successful A and AAAA records, or an empty name-not-found answer.
+     */
+    resolve(serviceName: string, signal: AbortSignal): Promise<readonly GkeDnsAddress[]>;
+    private static empty;
+}
+//# sourceMappingURL=node-dns-resolver.d.ts.map

package/dist/discovery/node-dns-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-dns-resolver.d.ts","sourceRoot":"","sources":["../../src/discovery/node-dns-resolver.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE7E;;GAEG;AACH,MAAM,WAAW,SAAS;IAGxB;;;;;;OAMG;IACH,QAAQ,CACN,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAA;KAAE,GAC9B,OAAO,CAAC,SAAS;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC,CAAC;IAE1E;;;;;;OAMG;IACH,QAAQ,CACN,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAA;KAAE,GAC9B,OAAO,CAAC,SAAS;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC,CAAC;IAE1E;;OAEG;IACH,MAAM,IAAI,IAAI,CAAC;CAChB;AAED;;GAEG;AACH,qBAAa,eAAgB,YAAW,cAAc;;IAGpD;;;;OAIG;gBACS,MAAM,GAAE,MAAM,SAAgC;IAI1D;;;;;;OAMG;IACG,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC;IAkC1F,OAAO,CAAC,MAAM,CAAC,KAAK;CASrB"}

package/dist/discovery/node-dns-resolver.js

@@ -0,0 +1,78 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { Resolver } from "node:dns/promises";
+/**
+ * Resolves IPv4 and IPv6 headless-Service records through Node DNS.
+ */
+export class NodeDnsResolver {
+    #create;
+    /**
+     * Creates the Node DNS adapter.
+     *
+     * @param create Supplies a resolver factory for deterministic integration tests.
+     */
+    constructor(create = () => new Resolver()) {
+        this.#create = create;
+    }
+    /**
+     * Resolves both address families and exposes DNS TTLs when Node supplies them.
+     *
+     * @param serviceName Supplies the headless-Service DNS name.
+     * @param signal Cancels the resolver request.
+     * @returns All successful A and AAAA records, or an empty name-not-found answer.
+     */
+    async resolve(serviceName, signal) {
+        const resolver = this.#create();
+        if (signal.aborted) {
+            resolver.cancel();
+            signal.throwIfAborted();
+        }
+        const cancel = () => {
+            resolver.cancel();
+        };
+        signal.addEventListener("abort", cancel, { once: true });
+        try {
+            const lookup = async (request) => {
+                try {
+                    return await request;
+                }
+                catch (error) {
+                    if (!NodeDnsResolver.empty(error))
+                        resolver.cancel();
+                    if (NodeDnsResolver.empty(error))
+                        return [];
+                    throw error;
+                }
+            };
+            const [ipv4, ipv6] = await Promise.all([
+                lookup(resolver.resolve4(serviceName, { ttl: true })),
+                lookup(resolver.resolve6(serviceName, { ttl: true })),
+            ]);
+            signal.throwIfAborted();
+            const records = [...ipv4, ...ipv6];
+            return records.map((record) => ({ address: record.address, ttl: record.ttl }));
+        }
+        finally {
+            signal.removeEventListener("abort", cancel);
+        }
+    }
+    static empty(error) {
+        return (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            (error.code === "ENOTFOUND" ||
+                error.code === "ENODATA"));
+    }
+}
+//# sourceMappingURL=node-dns-resolver.js.map

package/dist/discovery/node-dns-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-dns-resolver.js","sourceRoot":"","sources":["../../src/discovery/node-dns-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAwC7C;;GAEG;AACH,MAAM,OAAO,eAAe;IACjB,OAAO,CAAkB;IAElC;;;;OAIG;IACH,YAAY,SAA0B,GAAG,EAAE,CAAC,IAAI,QAAQ,EAAE;QACxD,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CAAC,WAAmB,EAAE,MAAmB;QACpD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QAChC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,QAAQ,CAAC,MAAM,EAAE,CAAC;YAClB,MAAM,CAAC,cAAc,EAAE,CAAC;QAC1B,CAAC;QACD,MAAM,MAAM,GAAG,GAAG,EAAE;YAClB,QAAQ,CAAC,MAAM,EAAE,CAAC;QACpB,CAAC,CAAC;QACF,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACzD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,KAAK,EAClB,OAA+E,EAC/E,EAAE;gBACF,IAAI,CAAC;oBACH,OAAO,MAAM,OAAO,CAAC;gBACvB,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,KAAK,CAAC;wBAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;oBACrD,IAAI,eAAe,CAAC,KAAK,CAAC,KAAK,CAAC;wBAAE,OAAO,EAAE,CAAC;oBAC5C,MAAM,KAAK,CAAC;gBACd,CAAC;YACH,CAAC,CAAC;YACF,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;gBACrC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;gBACrD,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;aACtD,CAAC,CAAC;YACH,MAAM,CAAC,cAAc,EAAE,CAAC;YACxB,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC,CAAC;YACnC,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACjF,CAAC;gBAAS,CAAC;YACT,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;IAEO,MAAM,CAAC,KAAK,CAAC,KAAc;QACjC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;YACzB,KAAK,KAAK,IAAI;YACd,MAAM,IAAI,KAAK;YACf,CAAE,KAAqC,CAAC,IAAI,KAAK,WAAW;gBACzD,KAAqC,CAAC,IAAI,KAAK,SAAS,CAAC,CAC7D,CAAC;IACJ,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { GkeNodeDiscovery, NodeDnsResolver, type DnsLookup, type GkeDnsAddress, type GkeDnsResolver, type GkeNodeDiscoveryOptions, } from "./discovery/gke-node-discovery.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,uBAAuB,GAC7B,MAAM,mCAAmC,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+export { GkeNodeDiscovery, NodeDnsResolver, } from "./discovery/gke-node-discovery.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,gBAAgB,EAChB,eAAe,GAKhB,MAAM,mCAAmC,CAAC"}