@benzenejs/mesh-discovery-kubernetes 0.0.0-stage → 0.1.0-beta.2

package/dist/Extensions.d.ts

@@ -0,0 +1,8 @@
+import { IBenzeneServiceContainer } from '@benzenejs/abstractions';
+/**
+ * Registers `KubernetesServiceDiscoveryProvider` (as an additional `IMeshDiscoveryProvider`) over an
+ * in-cluster `CoreV1Api` client, plus a `MeshDiscoveryRunner` over all registered providers. Intended for a
+ * mesh running inside the cluster (uses `KubeConfig.loadFromCluster()` - the port of
+ * `KubernetesClientConfiguration.InClusterConfig`); its ServiceAccount needs RBAC to list Services.
+ */
+export declare function addMeshKubernetesDiscovery(services: IBenzeneServiceContainer): IBenzeneServiceContainer;

package/dist/Extensions.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addMeshKubernetesDiscovery = addMeshKubernetesDiscovery;
+/** Port of Benzene.Mesh.Discovery.Kubernetes.Extensions. */
+const client_node_1 = require("@kubernetes/client-node");
+const mesh_contracts_1 = require("@benzenejs/mesh-contracts");
+const IKubernetesServiceLister_1 = require("./IKubernetesServiceLister");
+const KubernetesApiServiceLister_1 = require("./KubernetesApiServiceLister");
+const KubernetesServiceDiscoveryProvider_1 = require("./KubernetesServiceDiscoveryProvider");
+/**
+ * Registers `KubernetesServiceDiscoveryProvider` (as an additional `IMeshDiscoveryProvider`) over an
+ * in-cluster `CoreV1Api` client, plus a `MeshDiscoveryRunner` over all registered providers. Intended for a
+ * mesh running inside the cluster (uses `KubeConfig.loadFromCluster()` - the port of
+ * `KubernetesClientConfiguration.InClusterConfig`); its ServiceAccount needs RBAC to list Services.
+ */
+function addMeshKubernetesDiscovery(services) {
+    const kubeConfig = new client_node_1.KubeConfig();
+    kubeConfig.loadFromCluster();
+    const client = kubeConfig.makeApiClient(client_node_1.CoreV1Api);
+    services.addSingletonFactory(IKubernetesServiceLister_1.IKubernetesServiceLister, () => new KubernetesApiServiceLister_1.KubernetesApiServiceLister(client));
+    services.addSingletonFactory(mesh_contracts_1.IMeshDiscoveryProvider, (resolver) => new KubernetesServiceDiscoveryProvider_1.KubernetesServiceDiscoveryProvider(resolver.getService(IKubernetesServiceLister_1.IKubernetesServiceLister)));
+    services.addSingletonFactory(mesh_contracts_1.MeshDiscoveryRunner, (resolver) => new mesh_contracts_1.MeshDiscoveryRunner(resolver.getServices(mesh_contracts_1.IMeshDiscoveryProvider)));
+    return services;
+}

package/dist/IKubernetesServiceLister.d.ts

@@ -0,0 +1,28 @@
+/** Port of Benzene.Mesh.Discovery.Kubernetes.IKubernetesServiceLister (+ KubernetesServiceInfo). */
+import { ServiceToken } from '@benzenejs/abstractions';
+/**
+ * The subset of a Kubernetes Service that mesh discovery needs. C# `record` -> a plain interface;
+ * `IReadOnlyDictionary` -> `Record`.
+ */
+export interface KubernetesServiceInfo {
+    /** The Service's metadata name (used as the mesh service name and DNS host). */
+    readonly name: string;
+    /** The Service's namespace (part of its in-cluster DNS). */
+    readonly namespace: string;
+    /** The Service's first exposed port (the port its cluster DNS resolves traffic to). */
+    readonly port: number;
+    /** The Service's labels (matched against the discovery filter). */
+    readonly labels: Record<string, string>;
+}
+/**
+ * A minimal port over the Kubernetes API for listing Services, so `KubernetesServiceDiscoveryProvider`'s
+ * discovery logic (label-selector construction, URL building, filtering) is unit-testable without the
+ * Kubernetes client SDK. The real implementation is `KubernetesApiServiceLister`. `CancellationToken` ->
+ * optional `AbortSignal`; `string?` namespace -> `string | undefined` (`undefined` = all namespaces).
+ */
+export interface IKubernetesServiceLister {
+    /** Lists Services matching `labelSelector` in `namespace` (or across all namespaces when it is `undefined`). */
+    listServicesAsync(namespace: string | undefined, labelSelector: string, cancellationToken?: AbortSignal): Promise<KubernetesServiceInfo[]>;
+}
+/** Container token: the discovery provider resolves its lister by this interface. */
+export declare const IKubernetesServiceLister: ServiceToken<IKubernetesServiceLister>;

package/dist/IKubernetesServiceLister.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IKubernetesServiceLister = void 0;
+/** Port of Benzene.Mesh.Discovery.Kubernetes.IKubernetesServiceLister (+ KubernetesServiceInfo). */
+const abstractions_1 = require("@benzenejs/abstractions");
+/** Container token: the discovery provider resolves its lister by this interface. */
+exports.IKubernetesServiceLister = (0, abstractions_1.serviceToken)('IKubernetesServiceLister');

package/dist/KubernetesApiServiceLister.d.ts

@@ -0,0 +1,18 @@
+/** Port of Benzene.Mesh.Discovery.Kubernetes.KubernetesApiServiceLister. */
+import { CoreV1Api } from '@kubernetes/client-node';
+import { IKubernetesServiceLister, KubernetesServiceInfo } from './IKubernetesServiceLister';
+/**
+ * The real `IKubernetesServiceLister` over the Kubernetes client SDK's `CoreV1Api`. Kept thin (no discovery
+ * logic) so the SDK coupling lives in one place and `KubernetesServiceDiscoveryProvider` stays
+ * unit-testable against the port.
+ *
+ * `KubernetesClient`/`IKubernetes` -> `@kubernetes/client-node`'s `CoreV1Api`; the v1 client's list methods
+ * take a single param object (`listServiceForAllNamespaces({ labelSelector })` /
+ * `listNamespacedService({ namespace, labelSelector })`). The `CancellationToken` isn't threaded - the JS
+ * client's abort handling is via `ConfigurationOptions`, not a token, and this thin lister isn't unit-tested.
+ */
+export declare class KubernetesApiServiceLister implements IKubernetesServiceLister {
+    private readonly client;
+    constructor(client: CoreV1Api);
+    listServicesAsync(namespace: string | undefined, labelSelector: string, _cancellationToken?: AbortSignal): Promise<KubernetesServiceInfo[]>;
+}

package/dist/KubernetesApiServiceLister.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KubernetesApiServiceLister = void 0;
+/**
+ * The real `IKubernetesServiceLister` over the Kubernetes client SDK's `CoreV1Api`. Kept thin (no discovery
+ * logic) so the SDK coupling lives in one place and `KubernetesServiceDiscoveryProvider` stays
+ * unit-testable against the port.
+ *
+ * `KubernetesClient`/`IKubernetes` -> `@kubernetes/client-node`'s `CoreV1Api`; the v1 client's list methods
+ * take a single param object (`listServiceForAllNamespaces({ labelSelector })` /
+ * `listNamespacedService({ namespace, labelSelector })`). The `CancellationToken` isn't threaded - the JS
+ * client's abort handling is via `ConfigurationOptions`, not a token, and this thin lister isn't unit-tested.
+ */
+class KubernetesApiServiceLister {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async listServicesAsync(namespace, labelSelector, _cancellationToken) {
+        const list = namespace === undefined
+            ? await this.client.listServiceForAllNamespaces({ labelSelector })
+            : await this.client.listNamespacedService({ namespace, labelSelector });
+        const services = [];
+        for (const service of list.items ?? []) {
+            const name = service.metadata?.name;
+            if (name === undefined || name.length === 0) {
+                continue;
+            }
+            services.push({
+                name,
+                namespace: service.metadata?.namespace ?? 'default',
+                port: service.spec?.ports?.[0]?.port ?? 80,
+                labels: service.metadata?.labels ?? {},
+            });
+        }
+        return services;
+    }
+}
+exports.KubernetesApiServiceLister = KubernetesApiServiceLister;

package/dist/KubernetesServiceDiscoveryProvider.d.ts

@@ -0,0 +1,31 @@
+/** Port of Benzene.Mesh.Discovery.Kubernetes.KubernetesServiceDiscoveryProvider. */
+import { IMeshDiscoveryProvider, MeshDiscoveryFilter, MeshServiceRegistryEntry } from '@benzenejs/mesh-contracts';
+import { IKubernetesServiceLister } from './IKubernetesServiceLister';
+/**
+ * Discovers Benzene services by listing the Kubernetes Services that match the `MeshDiscoveryFilter` (by
+ * default, carry the `benzene` label) via the Kubernetes API, and emitting an HTTP registry entry per
+ * Service pointing at its in-cluster DNS (`http://{name}.{namespace}.svc.cluster.local[:port]/benzene/spec|health`).
+ * The services are HTTP-addressable in-cluster, so entries use the default HTTP interrogation source
+ * (`MeshServiceSource.http`) - `HttpMeshServiceSource` interrogates each.
+ *
+ * The mesh's ServiceAccount needs RBAC to `list` Services. Spec/health paths follow the Cloud Service
+ * Profile defaults; a Service can override them with `benzene.spec-path`/`benzene.health-path` labels, and
+ * its scheme/port with `benzene.scheme`.
+ */
+export declare class KubernetesServiceDiscoveryProvider implements IMeshDiscoveryProvider {
+    private readonly lister;
+    /** Label overriding the spec path (default `/benzene/spec?type=benzene`). */
+    static readonly SpecPathLabel = "benzene.spec-path";
+    /** Label overriding the health path (default `/benzene/health`). */
+    static readonly HealthPathLabel = "benzene.health-path";
+    /** Label overriding the URL scheme (default `http`). */
+    static readonly SchemeLabel = "benzene.scheme";
+    constructor(lister: IKubernetesServiceLister);
+    get key(): string;
+    discoverAsync(filter: MeshDiscoveryFilter, cancellationToken?: AbortSignal): Promise<readonly MeshServiceRegistryEntry[]>;
+    /**
+     * Builds a Kubernetes label selector from the filter's tags: `key` (present with any value) or
+     * `key=value` (exact match), comma-joined - the same semantics Kubernetes applies natively.
+     */
+    static buildLabelSelector(filter: MeshDiscoveryFilter): string;
+}

package/dist/KubernetesServiceDiscoveryProvider.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KubernetesServiceDiscoveryProvider = void 0;
+/** Port of Benzene.Mesh.Discovery.Kubernetes.KubernetesServiceDiscoveryProvider. */
+const mesh_contracts_1 = require("@benzenejs/mesh-contracts");
+const DefaultSpecPath = '/benzene/spec?type=benzene';
+const DefaultHealthPath = '/benzene/health';
+/**
+ * Discovers Benzene services by listing the Kubernetes Services that match the `MeshDiscoveryFilter` (by
+ * default, carry the `benzene` label) via the Kubernetes API, and emitting an HTTP registry entry per
+ * Service pointing at its in-cluster DNS (`http://{name}.{namespace}.svc.cluster.local[:port]/benzene/spec|health`).
+ * The services are HTTP-addressable in-cluster, so entries use the default HTTP interrogation source
+ * (`MeshServiceSource.http`) - `HttpMeshServiceSource` interrogates each.
+ *
+ * The mesh's ServiceAccount needs RBAC to `list` Services. Spec/health paths follow the Cloud Service
+ * Profile defaults; a Service can override them with `benzene.spec-path`/`benzene.health-path` labels, and
+ * its scheme/port with `benzene.scheme`.
+ */
+class KubernetesServiceDiscoveryProvider {
+    lister;
+    /** Label overriding the spec path (default `/benzene/spec?type=benzene`). */
+    static SpecPathLabel = 'benzene.spec-path';
+    /** Label overriding the health path (default `/benzene/health`). */
+    static HealthPathLabel = 'benzene.health-path';
+    /** Label overriding the URL scheme (default `http`). */
+    static SchemeLabel = 'benzene.scheme';
+    constructor(lister) {
+        this.lister = lister;
+    }
+    get key() {
+        return 'Kubernetes';
+    }
+    async discoverAsync(filter, cancellationToken) {
+        const services = await this.lister.listServicesAsync(filter.namespace, KubernetesServiceDiscoveryProvider.buildLabelSelector(filter), cancellationToken);
+        const entries = [];
+        for (const service of services) {
+            // The lister already applied the label selector server-side, but re-check locally so the provider
+            // honours the filter's exact-value semantics uniformly across platforms.
+            if (!filter.matches(service.labels)) {
+                continue;
+            }
+            const scheme = sanitizeScheme(labelOrDefault(service.labels, KubernetesServiceDiscoveryProvider.SchemeLabel, 'http'));
+            const authority = `${service.name}.${service.namespace}.svc.cluster.local${portSuffix(scheme, service.port)}`;
+            const specPath = sanitizePath(labelOrDefault(service.labels, KubernetesServiceDiscoveryProvider.SpecPathLabel, DefaultSpecPath), DefaultSpecPath);
+            const healthPath = sanitizePath(labelOrDefault(service.labels, KubernetesServiceDiscoveryProvider.HealthPathLabel, DefaultHealthPath), DefaultHealthPath);
+            entries.push(new mesh_contracts_1.MeshServiceRegistryEntry(service.name, `${scheme}://${authority}${specPath}`, `${scheme}://${authority}${healthPath}`));
+        }
+        return entries;
+    }
+    /**
+     * Builds a Kubernetes label selector from the filter's tags: `key` (present with any value) or
+     * `key=value` (exact match), comma-joined - the same semantics Kubernetes applies natively.
+     */
+    static buildLabelSelector(filter) {
+        return Object.entries(filter.tags)
+            .map(([key, value]) => (value === null ? key : `${key}=${value}`))
+            .join(',');
+    }
+}
+exports.KubernetesServiceDiscoveryProvider = KubernetesServiceDiscoveryProvider;
+function portSuffix(scheme, port) {
+    const defaultPort = scheme.toLowerCase() === 'https' ? 443 : 80;
+    return port === defaultPort || port <= 0 ? '' : `:${port}`;
+}
+// The scheme label carries an attacker-influenceable value (anyone who can label the Service). Only
+// http/https may be used: a value like "https://evil.com/" would otherwise restructure the
+// "{scheme}://{authority}{path}" URL and redirect the aggregator's fetch off-cluster (SSRF). An
+// unrecognised scheme falls back to the safe http default rather than aborting discovery.
+function sanitizeScheme(scheme) {
+    const lower = scheme.toLowerCase();
+    return lower === 'http' || lower === 'https' ? scheme : 'http';
+}
+// A path override must be a real path (start with '/'); otherwise "{authority}{path}" would graft the value
+// onto the authority and redirect the fetch off the in-cluster host. An invalid override falls back to the
+// safe default path.
+function sanitizePath(path, fallback) {
+    return path.startsWith('/') ? path : fallback;
+}
+function labelOrDefault(labels, key, fallback) {
+    const value = labels[key];
+    return value !== undefined && value.trim().length > 0 ? value : fallback;
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Port of Benzene.Mesh.Discovery.Kubernetes - self-discovery of Benzene services from Kubernetes Services.
+ * `KubernetesServiceDiscoveryProvider` (pure label-selector construction, in-cluster-DNS URL building,
+ * SSRF-safe scheme/path sanitisation) sits over the `IKubernetesServiceLister` seam, whose real
+ * implementation (`KubernetesApiServiceLister`) adapts the Kubernetes client SDK to `@kubernetes/client-node`.
+ * Wired via `addMeshKubernetesDiscovery`.
+ */
+export * from './IKubernetesServiceLister';
+export * from './KubernetesServiceDiscoveryProvider';
+export * from './KubernetesApiServiceLister';
+export * from './Extensions';

package/dist/index.js

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Port of Benzene.Mesh.Discovery.Kubernetes - self-discovery of Benzene services from Kubernetes Services.
+ * `KubernetesServiceDiscoveryProvider` (pure label-selector construction, in-cluster-DNS URL building,
+ * SSRF-safe scheme/path sanitisation) sits over the `IKubernetesServiceLister` seam, whose real
+ * implementation (`KubernetesApiServiceLister`) adapts the Kubernetes client SDK to `@kubernetes/client-node`.
+ * Wired via `addMeshKubernetesDiscovery`.
+ */
+__exportStar(require("./IKubernetesServiceLister"), exports);
+__exportStar(require("./KubernetesServiceDiscoveryProvider"), exports);
+__exportStar(require("./KubernetesApiServiceLister"), exports);
+__exportStar(require("./Extensions"), exports);

package/package.json

@@ -1,6 +1,17 @@
 {
   "name": "@benzenejs/mesh-discovery-kubernetes",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.2",
+  "description": "TypeScript port of Benzene.Mesh.Discovery.Kubernetes",
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "@benzenejs/abstractions": "0.1.0-beta.2",
+    "@benzenejs/mesh-contracts": "0.1.0-beta.2",
+    "@kubernetes/client-node": "^1.4.0"
+  },
+  "files": [
+    "dist"
+  ]
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.