kubernetes-fluent-client 0.0.0-development → 1.0.0

package/src/fluent/types.ts

@@ -0,0 +1,151 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { KubernetesListObject, KubernetesObject } from "@kubernetes/client-node";
+import { Operation } from "fast-json-patch";
+import { Agent } from "http";
+
+import { GenericClass, GroupVersionKind } from "../types";
+
+/**
+ * The Phase matched when using the K8s Watch API.
+ */
+export enum WatchPhase {
+  Added = "ADDED",
+  Modified = "MODIFIED",
+  Deleted = "DELETED",
+}
+
+export type FetchMethods = "GET" | "APPLY" | "POST" | "PUT" | "DELETE" | "PATCH" | "WATCH";
+
+export interface Filters {
+  kindOverride?: GroupVersionKind;
+  fields?: Record<string, string>;
+  labels?: Record<string, string>;
+  name?: string;
+  namespace?: string;
+}
+
+export type GetFunction<K extends KubernetesObject> = {
+  (): Promise<KubernetesListObject<K>>;
+  (name: string): Promise<K>;
+};
+
+export type KubeFilteredActions<K extends KubernetesObject> = {
+  /**
+   * Get the resource or resources matching the filters.
+   * If no filters are specified, all resources will be returned.
+   * If a name is specified, only a single resource will be returned.
+   */
+  Get: GetFunction<K>;
+
+  /**
+   * Delete the resource if it exists.
+   *
+   * @param filter - the resource or resource name to delete
+   */
+  Delete: (filter?: K | string) => Promise<void>;
+
+  /**
+   *
+   * @param callback
+   * @returns
+   */
+  Watch: (callback: (payload: K, phase: WatchPhase) => void) => Promise<void>;
+};
+
+export type KubeUnfilteredActions<K extends KubernetesObject> = {
+  /**
+   * Perform a server-side apply of the provided K8s resource.
+   *
+   * @param resource
+   * @returns
+   */
+  Apply: (resource: K) => Promise<K>;
+
+  /**
+   * Create the provided K8s resource or throw an error if it already exists.
+   *
+   * @param resource
+   * @returns
+   */
+  Create: (resource: K) => Promise<K>;
+
+  /**
+   * Advanced JSON Patch operations for when Server Side Apply, Kube().Apply(), is insufficient.
+   *
+   * Note: Throws an error on an empty list of patch operations.
+   *
+   * @param payload The patch operations to run
+   * @returns The patched resource
+   */
+  Patch: (payload: Operation[]) => Promise<K>;
+};
+
+export type KubeWithFilters<K extends KubernetesObject> = KubeFilteredActions<K> & {
+  /**
+   * Filter the query by the given field.
+   * Note multiple calls to this method will result in an AND condition. e.g.
+   *
+   * ```ts
+   * Kube(given.Deployment)
+   *  .WithField("metadata.name", "bar")
+   *  .WithField("metadata.namespace", "qux")
+   *  .Delete(...)
+   * ```
+   *
+   * Will only delete the Deployment if it has the `metadata.name=bar` and `metadata.namespace=qux` fields.
+   *
+   * @param key  The field key
+   * @param value The field value
+   * @returns
+   */
+  WithField: <P extends Paths<K>>(key: P, value?: string) => KubeWithFilters<K>;
+
+  /**
+   * Filter the query by the given label. If no value is specified, the label simply must exist.
+   * Note multiple calls to this method will result in an AND condition. e.g.
+   *
+   * ```ts
+   * Kube(given.Deployment)
+   *   .WithLabel("foo", "bar")
+   *   .WithLabel("baz", "qux")
+   *   .Delete(...)
+   * ```
+   *
+   * Will only delete the Deployment if it has the`foo=bar` and `baz=qux` labels.
+   *
+   * @param key The label key
+   * @param value (optional) The label value
+   */
+  WithLabel: (key: string, value?: string) => KubeWithFilters<K>;
+};
+
+export type KubeInit<K extends KubernetesObject> = KubeWithFilters<K> &
+  KubeUnfilteredActions<K> & {
+    /**
+     * Filter the query by the given namespace.
+     *
+     * @param namespace
+     * @returns
+     */
+    InNamespace: (namespace: string) => KubeWithFilters<K>;
+  };
+
+export type WatchAction<T extends GenericClass, K extends KubernetesObject = InstanceType<T>> = (
+  update: K,
+  phase: WatchPhase,
+) => Promise<void> | void;
+
+// Special types to handle the recursive keyof typescript lookup
+type Join<K, P> = K extends string | number
+  ? P extends string | number
+    ? `${K}${"" extends P ? "" : "."}${P}`
+    : never
+  : never;
+
+export type Paths<T, D extends number = 10> = [D] extends [never]
+  ? never
+  : T extends object
+  ? { [K in keyof T]-?: K extends string | number ? `${K}` | Join<K, Paths<T[K]>> : never }[keyof T]
+  : "";

package/src/fluent/utils.test.ts

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { beforeEach, describe, expect, it, jest } from "@jest/globals";
+
+import { fetch } from "../fetch";
+import { GenericClass } from "../types";
+import { ClusterRole, Ingress, Pod } from "../upstream";
+import { Filters } from "./types";
+import { kubeExec, pathBuilder } from "./utils";
+
+jest.mock("https");
+jest.mock("../fetch");
+
+describe("pathBuilder Function", () => {
+  const serverUrl = "https://jest-test:8080";
+  it("should throw an error if the kind is not specified and the model is not a KubernetesObject", () => {
+    const model = { name: "Unknown" } as unknown as GenericClass;
+    const filters: Filters = {};
+    expect(() => pathBuilder("", model, filters)).toThrow("Kind not specified for Unknown");
+  });
+
+  it("should generate a path for core group kinds", () => {
+    const filters: Filters = { namespace: "default", name: "mypod" };
+    const result = pathBuilder(serverUrl, Pod, filters);
+    const expected = new URL("/api/v1/namespaces/default/pods/mypod", serverUrl);
+    expect(result).toEqual(expected);
+  });
+
+  it("should generate a path for non-core group kinds", () => {
+    const filters: Filters = {
+      namespace: "default",
+      name: "myingress",
+    };
+    const result = pathBuilder(serverUrl, Ingress, filters);
+    const expected = new URL(
+      "/apis/networking.k8s.io/v1/namespaces/default/ingresses/myingress",
+      serverUrl,
+    );
+    expect(result).toEqual(expected);
+  });
+
+  it("should generate a path without a namespace if not provided", () => {
+    const filters: Filters = { name: "tester" };
+    const result = pathBuilder(serverUrl, ClusterRole, filters);
+    const expected = new URL("/apis/rbac.authorization.k8s.io/v1/clusterroles/tester", serverUrl);
+    expect(result).toEqual(expected);
+  });
+
+  it("should generate a path without a name if excludeName is true", () => {
+    const filters: Filters = { namespace: "default", name: "mypod" };
+    const result = pathBuilder(serverUrl, Pod, filters, true);
+    const expected = new URL("/api/v1/namespaces/default/pods", serverUrl);
+    expect(result).toEqual(expected);
+  });
+});
+
+describe("kubeExec Function", () => {
+  const mockedFetch = jest.mocked(fetch);
+
+  const fakeFilters: Filters = { name: "fake", namespace: "default" };
+  const fakeMethod = "GET";
+  const fakePayload = { metadata: { name: "fake", namespace: "default" } };
+  const fakeUrl = new URL("http://jest-test:8080/api/v1/namespaces/default/pods/fake");
+  const fakeOpts = {
+    body: JSON.stringify(fakePayload),
+    headers: {
+      "Content-Type": "application/json",
+      "User-Agent": `kubernetes-fluent-client`,
+    },
+    method: fakeMethod,
+  };
+
+  beforeEach(() => {
+    mockedFetch.mockClear();
+  });
+
+  it("should make a successful fetch call", async () => {
+    mockedFetch.mockResolvedValueOnce({
+      ok: true,
+      data: fakePayload,
+      status: 200,
+      statusText: "OK",
+    });
+
+    const result = await kubeExec(Pod, fakeFilters, fakeMethod, fakePayload);
+
+    expect(result).toEqual(fakePayload);
+    expect(mockedFetch).toHaveBeenCalledWith(fakeUrl, expect.objectContaining(fakeOpts));
+  });
+
+  it("should handle fetch call failure", async () => {
+    const fakeStatus = 404;
+    const fakeStatusText = "Not Found";
+
+    mockedFetch.mockResolvedValueOnce({
+      ok: false,
+      data: null,
+      status: fakeStatus,
+      statusText: fakeStatusText,
+    });
+
+    await expect(kubeExec(Pod, fakeFilters, fakeMethod, fakePayload)).rejects.toEqual(
+      expect.objectContaining({
+        status: fakeStatus,
+        statusText: fakeStatusText,
+      }),
+    );
+  });
+});

package/src/fluent/utils.ts

@@ -0,0 +1,152 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { KubeConfig, PatchStrategy } from "@kubernetes/client-node";
+
+import { Headers } from "node-fetch";
+import { URL } from "url";
+import { fetch } from "../fetch";
+import { modelToGroupVersionKind } from "../kinds";
+import { GenericClass } from "../types";
+import { FetchMethods, Filters } from "./types";
+
+const SSA_CONTENT_TYPE = "application/apply-patch+yaml";
+
+/**
+ * Generate a path to a Kubernetes resource
+ *
+ * @param serverUrl
+ * @param model
+ * @param filters
+ * @param excludeName
+ * @returns
+ */
+export function pathBuilder<T extends GenericClass>(
+  serverUrl: string,
+  model: T,
+  filters: Filters,
+  excludeName = false,
+) {
+  const matchedKind = filters.kindOverride || modelToGroupVersionKind(model.name);
+
+  // If the kind is not specified and the model is not a KubernetesObject, throw an error
+  if (!matchedKind) {
+    throw new Error(`Kind not specified for ${model.name}`);
+  }
+
+  // Use the plural property if it exists, otherwise use lowercase kind + s
+  const plural = matchedKind.plural || `${matchedKind.kind.toLowerCase()}s`;
+
+  let base = "/api/v1";
+
+  // If the kind is not in the core group, add the group and version to the path
+  if (matchedKind.group) {
+    if (!matchedKind.version) {
+      throw new Error(`Version not specified for ${model.name}`);
+    }
+
+    base = `/apis/${matchedKind.group}/${matchedKind.version}`;
+  }
+
+  // Namespaced paths require a namespace prefix
+  const namespace = filters.namespace ? `namespaces/${filters.namespace}` : "";
+
+  // Name should not be included in some paths
+  const name = excludeName ? "" : filters.name;
+
+  // Build the complete path to the resource
+  const path = [base, namespace, plural, name].filter(Boolean).join("/");
+
+  // Generate the URL object
+  const url = new URL(path, serverUrl);
+
+  // Add field selectors to the query params
+  if (filters.fields) {
+    const fieldSelector = Object.entries(filters.fields)
+      .map(([key, value]) => `${key}=${value}`)
+      .join(",");
+
+    url.searchParams.set("fieldSelector", fieldSelector);
+  }
+
+  // Add label selectors to the query params
+  if (filters.labels) {
+    const labelSelector = Object.entries(filters.labels)
+      .map(([key, value]) => `${key}=${value}`)
+      .join(",");
+
+    url.searchParams.set("labelSelector", labelSelector);
+  }
+
+  return url;
+}
+
+/**
+ * Sets up the kubeconfig and https agent for a request
+ *
+ * A few notes:
+ * - The kubeconfig is loaded from the default location, and can check for in-cluster config
+ * - We have to create an agent to handle the TLS connection (for the custom CA + mTLS in some cases)
+ * - The K8s lib uses request instead of node-fetch today so the object is slightly different
+ *
+ * @param method
+ * @returns
+ */
+export async function kubeCfg(method: FetchMethods) {
+  const kubeConfig = new KubeConfig();
+  kubeConfig.loadFromDefault();
+
+  const cluster = kubeConfig.getCurrentCluster();
+  if (!cluster) {
+    throw new Error("No currently active cluster");
+  }
+
+  // Setup the TLS options & auth headers, as needed
+  const opts = await kubeConfig.applyToFetchOptions({
+    method,
+    headers: {
+      // Set the default content type to JSON
+      "Content-Type": "application/json",
+      // Set the user agent like kubectl does
+      "User-Agent": `kubernetes-fluent-client`,
+    },
+  });
+
+  return { opts, serverUrl: cluster.server };
+}
+
+export async function kubeExec<T extends GenericClass, K>(
+  model: T,
+  filters: Filters,
+  method: FetchMethods,
+  payload?: K | unknown,
+) {
+  const { opts, serverUrl } = await kubeCfg(method);
+  const url = pathBuilder(serverUrl, model, filters, method === "POST");
+
+  switch (opts.method) {
+    case "PATCH":
+      (opts.headers as Headers).set("Content-Type", PatchStrategy.JsonPatch);
+      break;
+
+    case "APPLY":
+      (opts.headers as Headers).set("Content-Type", SSA_CONTENT_TYPE);
+      opts.method = "PATCH";
+      url.searchParams.set("fieldManager", "pepr");
+      url.searchParams.set("fieldValidation", "Strict");
+      url.searchParams.set("force", "false");
+      break;
+  }
+
+  if (payload) {
+    opts.body = JSON.stringify(payload);
+  }
+
+  const resp = await fetch<K>(url, opts);
+
+  if (resp.ok) {
+    return resp.data;
+  }
+
+  throw resp;
+}

package/src/fluent/watch.ts

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import readline from "readline";
+
+import fetch from "node-fetch";
+import { GenericClass } from "../types";
+import { Filters, WatchAction, WatchPhase } from "./types";
+import { kubeCfg, pathBuilder } from "./utils";
+
+/**
+ * Execute a watch on the specified resource.
+ */
+export async function ExecWatch<T extends GenericClass>(
+  model: T,
+  filters: Filters,
+  callback: WatchAction<T>,
+) {
+  // Build the path and query params for the resource, excluding the name
+  const { opts, serverUrl } = await kubeCfg("GET");
+  const url = pathBuilder(serverUrl, model, filters, true);
+
+  // Enable the watch query param
+  url.searchParams.set("watch", "true");
+
+  // Allow bookmarks to be used for the watch
+  url.searchParams.set("allowWatchBookmarks", "true");
+
+  // If a name is specified, add it to the query params
+  if (filters.name) {
+    url.searchParams.set("fieldSelector", `metadata.name=${filters.name}`);
+  }
+
+  // Add abort controller to the long-running request
+  const controller = new AbortController();
+  opts.signal = controller.signal;
+
+  // Close the connection and make the callback function no-op
+  let close = (err?: Error) => {
+    controller.abort();
+    close = () => {};
+    if (err) {
+      throw err;
+    }
+  };
+
+  try {
+    // Make the actual request
+    const response = await fetch(url, opts);
+
+    // If the request is successful, start listening for events
+    if (response.ok) {
+      const { body } = response;
+
+      // Bind connection events to the close function
+      body.on("error", close);
+      body.on("close", close);
+      body.on("finish", close);
+
+      // Create a readline interface to parse the stream
+      const rl = readline.createInterface({
+        input: response.body!,
+        terminal: false,
+      });
+
+      // Listen for events and call the callback function
+      rl.on("line", line => {
+        try {
+          // Parse the event payload
+          const { object: payload, type: phase } = JSON.parse(line) as {
+            type: WatchPhase;
+            object: InstanceType<T>;
+          };
+
+          // Call the callback function with the parsed payload
+          void callback(payload, phase as WatchPhase);
+        } catch (ignore) {
+          // ignore parse errors
+        }
+      });
+    } else {
+      // If the request fails, throw an error
+      const error = new Error(response.statusText) as Error & {
+        statusCode: number | undefined;
+      };
+      error.statusCode = response.status;
+      throw error;
+    }
+  } catch (e) {
+    close(e);
+  }
+
+  return controller;
+}

package/src/index.ts

@@ -4,11 +4,16 @@
 // Export kinds as a single object
 import * as kind from "./upstream";
 
-/** given is a collection of K8s types to be used within a Kube call: `Kube(Secret).Apply({})`. `a` may also be used in it's place */
+/** given is a collection of K8s types to be used within a Kube call: `Kube(kind.Secret).Apply({})`. `a` may also be used in it's place */
 export { kind };
 
-// export { Kube } from "./fluent/kube";
+// Export the node-fetch wrapper
+export { fetch } from "./fetch";
 
-export { modelToGroupVersionKind, gvkMap, RegisterKind } from "./kinds";
+// Export the fluent API entrypoint
+export { Kube } from "./fluent/kube";
+
+// Export helpers for working with K8s types
+export { modelToGroupVersionKind, RegisterKind } from "./kinds";
 
 export * from "./types";

package/src/kinds.test.ts

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: Apache-2.0
-// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+// SPDX-FileCopyrightText: 2023-Present The Kubernetes Fluent Client Authors
 
 import { expect, test } from "@jest/globals";
 

package/src/kinds.ts

@@ -3,7 +3,7 @@
 
 import { GenericClass, GroupVersionKind } from "./types";
 
-export const gvkMap: Record<string, GroupVersionKind> = {
+const gvkMap: Record<string, GroupVersionKind> = {
   /**
    * Represents a K8s ClusterRole resource.
    * ClusterRole is a set of permissions that can be bound to a user or group in a cluster-wide scope.